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.

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

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'
邮件消息包含以下内容字段：主题、预览文本、发件人邮箱、发件人标签、回复邮箱
SMS消息包含内容字段：正文
包含'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. 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

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

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集成中配置的版本

响应嵌套结构:

数据为嵌套结构：
```
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

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