klaviyo-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Klaviyo Automation via Rube MCP

通过Rube MCP实现Klaviyo自动化

Automate Klaviyo email and SMS marketing operations through Composio's Klaviyo toolkit via Rube MCP.

Toolkit docs: composio.dev/toolkits/klaviyo

通过Rube MCP，借助Composio的Klaviyo工具包自动化Klaviyo邮件和短信营销操作。

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

Prerequisites

前提条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active Klaviyo connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
klaviyo
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（需提供RUBE_SEARCH_TOOLS）
通过
```
RUBE_MANAGE_CONNECTIONS
```
并使用工具包
```
klaviyo
```
完成Klaviyo的激活连接
请始终先调用
```
RUBE_SEARCH_TOOLS
```
以获取最新的工具架构

Setup

设置步骤

Get Rube MCP: Add

https://rube.app/mcp

as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
klaviyo
```
If connection is not ACTIVE, follow the returned auth link to complete Klaviyo authentication
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥 — 只需添加端点即可使用。

确认
```
RUBE_SEARCH_TOOLS
```
可响应，以此验证Rube MCP是否可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
并指定工具包
```
klaviyo
```
如果连接状态未显示为ACTIVE，请按照返回的授权链接完成Klaviyo身份验证
在运行任何工作流之前，确认连接状态显示为ACTIVE

Core Workflows

核心工作流

1. List and Filter Campaigns

1. 列出并筛选营销活动

When to use: User wants to browse, search, or filter marketing campaigns

Tool sequence:

```
KLAVIYO_GET_CAMPAIGNS
```
- List campaigns with channel and status filters [Required]

Key parameters:

```
channel
```
: Campaign channel - 'email' or 'sms' (required by Klaviyo API)
```
filter
```
: Additional filter string (e.g.,
```
equals(status,"draft")
```
)
```
sort
```
: Sort field with optional
```
-
```
prefix for descending (e.g., '-created_at', 'name')
```
page_cursor
```
: Pagination cursor for next page
```
include_archived
```
: Include archived campaigns (default: false)

Pitfalls:

```
channel
```
is required; omitting it can produce incomplete or unexpected results
Pagination is mandatory for full coverage; a single call returns only one page (default ~10)
Follow
```
page_cursor
```
until exhausted to get all campaigns
Status filtering via
```
filter
```
(e.g.,
```
equals(status,"draft")
```
) can return mixed statuses; always validate
```
data[].attributes.status
```
client-side
Status strings are case-sensitive and can be compound (e.g., 'Cancelled: No Recipients')

Response shape is nested:

response.data.data

with status at

data[].attributes.status

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

工具执行序列：

```
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. Get Campaign Details

2. 获取营销活动详情

When to use: User wants detailed information about a specific campaign

Tool sequence:

```
KLAVIYO_GET_CAMPAIGNS
```
- Find campaign to get its ID [Prerequisite]
```
KLAVIYO_GET_CAMPAIGN
```
- Retrieve full campaign details [Required]

Key parameters:

```
campaign_id
```
: Campaign ID string (e.g., '01GDDKASAP8TKDDA2GRZDSVP4H')
```
include_messages
```
: Include campaign messages in response
```
include_tags
```
: Include tags in response

Pitfalls:

Campaign IDs are alphanumeric strings, not numeric
```
include_messages
```
and
```
include_tags
```
add related data to the response via Klaviyo's include mechanism
Campaign details include audiences, send strategy, tracking options, and scheduling info

适用场景：用户想要获取特定营销活动的详细信息

工具执行序列：

```
KLAVIYO_GET_CAMPAIGNS
```
- 找到目标营销活动以获取其ID [前提步骤]
```
KLAVIYO_GET_CAMPAIGN
```
- 获取完整的营销活动详情 [必填]

关键参数：

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

注意事项：

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

3. Inspect Campaign Messages

3. 查看营销活动消息

When to use: User wants to view the email/SMS content of a campaign

Tool sequence:

```
KLAVIYO_GET_CAMPAIGN
```
- Find campaign and its message IDs [Prerequisite]
```
KLAVIYO_GET_CAMPAIGN_MESSAGE
```
- Get message content details [Required]

Key parameters:

```
id
```
: Message ID string
```
fields__campaign__message
```
: Sparse fieldset for message attributes (e.g., 'content.subject', 'content.from_email', 'content.body')
```
fields__campaign
```
: Sparse fieldset for campaign attributes
```
fields__template
```
: Sparse fieldset for template attributes
```
include
```
: Related resources to include ('campaign', 'template')

Pitfalls:

Message IDs are separate from campaign IDs; extract from campaign response
Sparse fieldset syntax uses dot notation for nested fields: 'content.subject', 'content.from_email'
Email messages have content fields: subject, preview_text, from_email, from_label, reply_to_email
SMS messages have content fields: body
Including 'template' provides the HTML/text content of the email

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

工具执行序列：

```
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（回复邮箱）
SMS消息包含内容字段：body（正文）
包含'template'可获取邮件的HTML/文本内容

4. Manage Campaign Tags

4. 管理营销活动标签

When to use: User wants to view tags associated with campaigns for organization

Tool sequence:

```
KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS
```
- Get tag IDs for a campaign [Required]

Key parameters:

```
id
```
: Campaign ID string

Pitfalls:

Returns only tag IDs, not tag names/details
Tag IDs can be used with Klaviyo's tag endpoints for full details
Rate limit: 3/s burst, 60/m steady (stricter than other endpoints)

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

工具执行序列：

```
KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS
```
- 获取营销活动的标签ID [必填]

关键参数：

```
id
```
：营销活动ID字符串

注意事项：

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

5. Monitor Campaign Send Jobs

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

When to use: User wants to check the status of a campaign send operation

Tool sequence:

```
KLAVIYO_GET_CAMPAIGN_SEND_JOB
```
- Check send job status [Required]

Key parameters:

```
id
```
: Send job ID

Pitfalls:

Send job IDs are returned when a campaign send is initiated
Job statuses indicate whether the send is queued, in progress, complete, or failed
Rate limit: 10/s burst, 150/m steady

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

工具执行序列：

```
KLAVIYO_GET_CAMPAIGN_SEND_JOB
```
- 检查发送任务状态 [必填]

关键参数：

```
id
```
：发送任务ID

注意事项：

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

Common Patterns

通用模式

Campaign Discovery Pattern

营销活动发现模式

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

1. 调用KLAVIYO_GET_CAMPAIGNS并设置channel='email'
2. 通过page_cursor遍历所有结果
3. 在客户端进行状态筛选以确保准确性
4. 提取营销活动ID以便进行详细查看

Sparse Fieldset Pattern

稀疏字段集模式

Klaviyo supports sparse fieldsets to reduce response size:

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

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

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

Pagination

分页

Klaviyo uses cursor-based pagination
Check response for
```
page_cursor
```
in the pagination metadata
Pass cursor as
```
page_cursor
```
in next request
Default page size is ~10 campaigns
Continue until no more cursor is returned

Klaviyo使用基于游标的分页机制
在响应的分页元数据中检查
```
page_cursor
```
将游标作为
```
page_cursor
```
参数传入下一次请求
默认每页显示约10个营销活动
持续请求直到没有更多游标返回

Filter Syntax

筛选语法

- 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

- equals(status,"draft") - 草稿状态的营销活动
- equals(name,"Newsletter") - 名为"Newsletter"的营销活动
- greater-than(created_at,"2024-01-01T00:00:00Z") - 2024年1月1日之后创建的营销活动

Known Pitfalls

已知注意事项

API Version:

Klaviyo API uses versioned endpoints (e.g., v2024-07-15)
Response schemas may change between API versions
Tool responses follow the version configured in the Composio integration

Response Nesting:

Data is nested:
```
response.data.data[].attributes
```
Campaign status at
```
data[].attributes.status
```
Mis-parsing the nesting yields empty or incorrect results
Always navigate through the full path defensively

Rate Limits:

Burst: 10/s (3/s for tag endpoints)
Steady: 150/m (60/m for tag endpoints)
Required scope: campaigns:read
Implement backoff on 429 responses

Status Values:

Status strings are case-sensitive
Compound statuses exist (e.g., 'Cancelled: No Recipients')
Server-side filtering may return mixed statuses; always validate client-side

API版本：

Klaviyo API使用版本化端点（例如：v2024-07-15）
不同API版本的响应架构可能会有所变化
工具响应遵循Composio集成中配置的API版本

响应嵌套结构：

数据采用嵌套格式：
```
response.data.data[].attributes
```
营销活动状态位于
```
data[].attributes.status
```
解析时若忽略嵌套结构会导致结果为空或错误
请始终完整地遍历响应路径以确保正确获取数据

速率限制：

突发限制：10次/秒（标签端点为3次/秒）
稳定限制：150次/分钟（标签端点为60次/分钟）
所需权限范围：campaigns:read
收到429响应时请实现退避重试机制

状态值：

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

Quick Reference

快速参考

Task	Tool Slug	Key Params
List campaigns	KLAVIYO_GET_CAMPAIGNS	channel, filter, sort, page_cursor
Get campaign details	KLAVIYO_GET_CAMPAIGN	campaign_id, include_messages, include_tags
Get campaign message	KLAVIYO_GET_CAMPAIGN_MESSAGE	id, fields__campaign__message
Get campaign tags	KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS	id
Get send job status	KLAVIYO_GET_CAMPAIGN_SEND_JOB	id

Powered by Composio

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