klaviyo-automation

Klaviyo Automation via Rube MCP 是一个通过 Composio 的 Klaviyo 工具包、经由 Rube MCP 来自动化 Klaviyo 邮件与短信营销操作的技能。

用途

该技能用于自动化 Klaviyo 的邮件和短信营销任务，包括管理邮件/短信活动、查看活动消息、跟踪标签以及监控发送任务。

前置条件

• 必须已连接 Rube MCP（RUBE_SEARCH_TOOLS 可用）。
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Klaviyo 连接，工具包为 klaviyo。
• 始终先调用 RUBE_SEARCH_TOOLS 以获取当前工具架构。

设置方式

1. 获取 Rube MCP：在客户端配置中添加 https://rube.app/mcp 作为 MCP 服务器。无需 API 密钥，只需添加端点即可使用。
2. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用。
3. 调用 RUBE_MANAGE_CONNECTIONS，工具包为 klaviyo。
4. 如果连接不是 ACTIVE，请按照返回的认证链接完成 Klaviyo 认证。
5. 在运行任何工作流之前，确认连接状态显示为 ACTIVE。

主要能力与工作流

1. 列出与筛选活动

适用场景：用户想要浏览、搜索或筛选营销活动。 工具序列：

• KLAVIYO_GET_CAMPAIGNS - 按渠道和状态筛选列出活动 [必需] 关键参数：
• channel：活动渠道，'email' 或 'sms'（Klaviyo API 要求必填）
• filter：附加筛选字符串（例如 equals(status,"draft")）
• sort：排序字段，可选 - 前缀表示降序（例如 '-created_at'、'name'）
• page_cursor：下一页的分页游标
• include_archived：是否包含已归档活动（默认 false） 注意事项：
• channel 为必填；省略可能导致结果不完整或异常。
• 分页是完整覆盖的必要条件；单次调用只返回一页（默认约 10 条）。
• 持续跟随 page_cursor 直到耗尽，以获取所有活动。
• 通过 filter（例如 equals(status,"draft")）进行状态筛选可能返回混合状态；始终在客户端验证 data[].attributes.status。
• 状态字符串区分大小写，且可能是复合状态（例如 'Cancelled: No Recipients'）。
• 响应结构嵌套：response.data.data，状态位于 data[].attributes.status。

2. 获取活动详情

适用场景：用户想要获取特定活动的详细信息。 工具序列：

• KLAVIYO_GET_CAMPAIGNS - 查找活动以获取其 ID [前置]
• KLAVIYO_GET_CAMPAIGN - 获取完整活动详情 [必需] 关键参数：
• campaign_id：活动 ID 字符串（例如 '01GDDKASAP8TKDDA2GRZDSVP4H'）
• include_messages：在响应中包含活动消息
• include_tags：在响应中包含标签 注意事项：
• 活动 ID 是字母数字字符串，不是数字。
• include_messages 和 include_tags 通过 Klaviyo 的 include 机制向响应添加相关数据。
• 活动详情包括受众、发送策略、跟踪选项和排期信息。

3. 查看活动消息

适用场景：用户想要查看活动的邮件/短信内容。 工具序列：

• KLAVIYO_GET_CAMPAIGN - 查找活动及其消息 ID [前置]
• KLAVIYO_GET_CAMPAIGN_MESSAGE - 获取消息内容详情 [必需] 关键参数：
• id：消息 ID 字符串
• fields__campaign__message：消息属性的稀疏字段集（例如 'content.subject'、'content.from_email'、'content.body'）
• fields__campaign：活动属性的稀疏字段集
• fields__template：模板属性的稀疏字段集
• include：要包含的相关资源（'campaign'、'template'） 注意事项：
• 消息 ID 与活动 ID 不同；需从活动响应中提取。
• 稀疏字段集语法对嵌套字段使用点号：'content.subject'、'content.from_email'。
• 邮件消息的内容字段包括：subject、preview_text、from_email、from_label、reply_to_email。
• 短信消息的内容字段包括：body。
• 包含 'template' 可提供邮件的 HTML/文本内容。

4. 管理活动标签

适用场景：用户想要查看与活动关联的标签以进行组织管理。 工具序列：

• KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS - 获取活动的标签 ID [必需] 关键参数：
• id：活动 ID 字符串 注意事项：
• 仅返回标签 ID，不返回标签名称/详情。
• 标签 ID 可与 Klaviyo 的标签端点配合使用以获取完整详情。
• 速率限制：突发 3/s，稳定 60/m（比其他端点更严格）。

5. 监控活动发送任务

适用场景：用户想要检查活动发送操作的状态。 工具序列：

• KLAVIYO_GET_CAMPAIGN_SEND_JOB - 检查发送任务状态 [必需] 关键参数：
• id：发送任务 ID 注意事项：
• 发送任务 ID 在发起活动发送时返回。
• 任务状态指示发送是排队中、进行中、已完成还是失败。
• 速率限制：突发 10/s，稳定 150/m。

常见模式

活动发现模式

1. 调用 KLAVIYO_GET_CAMPAIGNS，channel='email'。
2. 通过 page_cursor 分页遍历所有结果。
3. 在客户端按状态筛选以确保准确性。
4. 提取活动 ID 以进行详细检查。

稀疏字段集模式

Klaviyo 支持稀疏字段集以减少响应大小：

• fields__campaign__message=['content.subject', 'content.from_email', 'send_times']
• fields__campaign=['name', 'status', 'send_time']
• fields__template=['name', 'html', 'text']

分页

• Klaviyo 使用基于游标的分页。
• 检查响应中分页元数据里的 page_cursor。
• 在下一个请求中将游标作为 page_cursor 传入。
• 默认页大小约为 10 个活动。
• 持续直到不再返回游标。

筛选语法

• equals(status,"draft") - 草稿状态的活动
• equals(name,"Newsletter") - 名为 "Newsletter" 的活动
• greater-than(created_at,"2024-01-01T00:00:00Z") - 在指定日期之后创建

已知注意事项

API 版本

• Klaviyo API 使用带版本的端点（例如 v2024-07-15）。
• 响应架构可能在不同 API 版本之间变化。
• 工具响应遵循 Composio 集成中配置的版本。

响应嵌套

• 数据嵌套为：response.data.data[].attributes。
• 活动状态位于 data[].attributes.status。
• 错误解析嵌套会导致空结果或不正确结果。
• 始终防御性地沿完整路径导航。

速率限制

• 突发：10/s（标签端点为 3/s）。
• 稳定：150/m（标签端点为 60/m）。
• 所需权限范围：campaigns:read。
• 对 429 响应实施退避。

状态值

• 状态字符串区分大小写。
• 存在复合状态（例如 'Cancelled: No Recipients'）。
• 服务端筛选可能返回混合状态；始终在客户端验证。

快速参考

任务	工具 Slug	关键参数
列出活动	KLAVIYO_GET_CAMPAIGNS	channel, filter, sort, page_cursor
获取活动详情	KLAVIYO_GET_CAMPAIGN	campaign_id, include_messages, include_tags
获取活动消息	KLAVIYO_GET_CAMPAIGN_MESSAGE	id, fields__campaign__message
获取活动标签	KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS	id
获取发送任务状态	KLAVIYO_GET_CAMPAIGN_SEND_JOB	id