klaviyo-automation

通过 Rube MCP 自动化 Klaviyo

通过 Rube MCP 使用 Composio 的 Klaviyo 工具包，自动执行 Klaviyo 电子邮件和短信营销操作。

工具包文档：composio.dev/toolkits/klaviyo

前置条件

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

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥——只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用
2. 使用工具包 klaviyo 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请按照返回的身份验证链接完成 Klaviyo 身份验证
4. 运行任何工作流前，确认连接状态为 ACTIVE

核心工作流

1. 列出并筛选营销活动

适用场景：用户想浏览、搜索或筛选营销活动

工具调用顺序：

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. 获取营销活动详情

适用场景：用户想详细了解某个营销活动

工具调用顺序：

1. KLAVIYO_GET_CAMPAIGNS - 查找营销活动并获取其 ID［前置步骤］
2. KLAVIYO_GET_CAMPAIGN - 获取营销活动的完整详情［必需］

关键参数：

• campaign_id：营销活动 ID 字符串（例如，'01GDDKASAP8TKDDA2GRZDSVP4H'）
• include_messages：是否在响应中包含营销活动消息
• include_tags：是否在响应中包含标签

注意事项：

• 营销活动 ID 是字母数字字符串，并非纯数字
• include_messages 和 include_tags 通过 Klaviyo 的 include 机制在响应中添加相关数据
• 营销活动详情包含受众、发送策略、跟踪选项和排期信息

3. 查看营销活动消息

适用场景：用户想查看营销活动中的电子邮件／短信内容

工具调用顺序：

1. KLAVIYO_GET_CAMPAIGN - 查找营销活动及其消息 ID［前置步骤］
2. 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. 管理营销活动标签

适用场景：用户希望查看与营销活动关联的标签，以便进行组织管理

工具调用顺序：

1. KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS - 获取营销活动的标签 ID［必需］

关键参数：

• id：营销活动 ID 字符串

注意事项：

• 仅返回标签 ID，不返回标签名称或详情
• 标签 ID 可用于调用 Klaviyo 的标签端点获取完整详情
• 速率限制：突发 3 次/秒，稳定 60 次/分钟（比其他端点更严格）

5. 监控营销活动发送任务

适用场景：用户希望检查营销活动发送操作的状态

工具调用顺序：

1. KLAVIYO_GET_CAMPAIGN_SEND_JOB - 检查发送任务状态［必需］

关键参数：

• id：发送任务 ID

注意事项：

• 启动营销活动发送时会返回发送任务 ID
• 任务状态表示发送是否在排队、进行中、已完成或失败
• 速率限制：突发 10 次/秒，稳定 150 次/分钟

常见模式

营销活动发现模式

1. Call KLAVIYO_GET_CAMPAIGNS with channel='email'
2. Paginate through all results via page_cursor
3. Filter by status client-side for accuracy
4. Extract campaign IDs for detailed inspection

稀疏字段集模式

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") - Campaigns in draft status
- equals(name,"Newsletter") - Campaign named "Newsletter"
- greater-than(created_at,"2024-01-01T00:00:00Z") - Created after date

已知注意事项

API 版本：

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

响应嵌套：

• 数据采用嵌套结构：response.data.data[].attributes
• 营销活动状态位于 data[].attributes.status
• 错误解析嵌套结构会导致结果为空或不正确
• 始终谨慎地沿完整路径访问数据

速率限制：

• 突发：10 次/秒（标签端点为 3 次/秒）
• 稳定：150 次/分钟（标签端点为 60 次/分钟）
• 所需范围：campaigns:read
• 收到 429 响应时实施退避

状态值：

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

快速参考

任务	工具标识	关键参数
列出营销活动	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

---

由 Composio 提供支持