klaviyo-automation

通过 Rube MCP 自动化 Klaviyo

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

前提条件

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

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。必须根据宿主环境连接并完成端点身份验证；每项服务连接仍需使用各自获得授权的账号和权限范围。

1. 确认 RUBE_SEARCH_TOOLS 能够响应，以验证 Rube MCP 已就绪
2. 调用 RUBE_MANAGE_CONNECTIONS，并指定工具包 klaviyo
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. 检查营销活动消息

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

工具调用顺序：

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 不同；请从营销活动响应中提取消息 ID
• 稀疏字段集语法使用点号表示嵌套字段：'content.subject'、'content.from_email'
• 电子邮件消息的内容字段包括：subject、preview_text、from_email、from_label、reply_to_email
• SMS 消息的内容字段包括：body
• 包含 'template' 可获取电子邮件的 HTML/文本内容

4. 管理营销活动标签

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

工具调用顺序：

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

关键参数：

• id：营销活动 ID 字符串

注意事项：

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

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

适用场景：用户想查看营销活动发送操作的状态

工具调用顺序：

1. KLAVIYO_GET_CAMPAIGN_SEND_JOB — 查看发送任务状态［必需］

关键参数：

• id：发送任务 ID

注意事项：

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

常见模式

营销活动发现模式

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/s（标签端点为 3/s）
• 稳定：150/m（标签端点为 60/m）
• 必需权限范围：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

适用场景

当需要执行概述中所述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要输入、权限、安全边界或成功标准，请停止并寻求澄清。

此处的工作流用于检查现有营销活动和发送任务，并不授权发起电子邮件/SMS 发送、更改受众/同意状态或删除营销活动。请保护收件人和消息数据的隐私；确认账户和渠道，并使用已发现的 API 修订版本/架构，不要假设所列速率限制仍然有效。