mailchimp-automation

通过 Rube MCP 自动化 Mailchimp

通过 Composio 的 Mailchimp 工具包，自动化 Mailchimp 电子邮件营销工作流，包括创建和发送营销活动、管理受众群体/列表、订阅者操作、细分和效果分析。

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

前置条件

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

设置

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

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 是否可用
2. 使用工具包 mailchimp 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请按照返回的授权链接完成 Mailchimp OAuth
4. 确认连接状态显示为 ACTIVE 后，再运行任何工作流

核心工作流

1. 创建并发送电子邮件营销活动

适用场景：用户想要创建、配置、测试并发送电子邮件营销活动。

工具调用顺序：

1. MAILCHIMP_GET_LISTS_INFO - 列出可用受众群体并获取 list_id [前置条件]
2. MAILCHIMP_ADD_CAMPAIGN - 使用类型、受众群体、主题和发件人名称创建新的营销活动 [必需]
3. MAILCHIMP_SET_CAMPAIGN_CONTENT - 设置营销活动的 HTML 内容 [必需]
4. MAILCHIMP_SEND_TEST_EMAIL - 正式发送前向审核者发送预览 [可选]
5. MAILCHIMP_SEND_CAMPAIGN - 立即发送营销活动 [必需]
6. MAILCHIMP_SCHEDULE_CAMPAIGN - 安排未来发送，而非立即发送 [可选]

MAILCHIMP_ADD_CAMPAIGN 的关键参数：

• type："regular"、"plaintext"、"rss" 或 "variate"（必需）
• recipients__list__id：收件人的受众群体/列表 ID
• settings__subject__line：电子邮件主题
• settings__from__name：发件人显示名称
• settings__reply__to：回复邮箱地址（发送所必需）
• settings__title：营销活动内部标题
• settings__preview__text：收件箱中显示的预览文本

MAILCHIMP_SET_CAMPAIGN_CONTENT 的关键参数：

• campaign_id：创建步骤中获得的营销活动 ID（必需）
• html：电子邮件的原始 HTML 内容
• plain_text：纯文本版本（若省略则自动生成）
• template__id：使用预建模板，而非原始 HTML

注意事项：

• MAILCHIMP_SEND_CAMPAIGN 操作不可撤销；务必先发送测试邮件并获得用户明确批准
• 发送前，营销活动必须处于 "save"（草稿）状态，并包含有效受众群体、主题、发件人名称、已验证邮箱和内容
• MAILCHIMP_SCHEDULE_CAMPAIGN 需要有效的未来日期时间；过去的时间戳会导致失败
• 模板和 HTML 内容必须包含符合规范的页脚/取消订阅合并标签
• Mailchimp 使用双下划线表示嵌套参数（例如 settings__subject__line）

2. 管理受众和订阅者

使用时机：用户想查看受众、列出订阅者或查看订阅者详情时。

工具调用顺序：

1. MAILCHIMP_GET_LISTS_INFO - 列出所有受众及其成员数量［必需］
2. MAILCHIMP_GET_LIST_INFO - 获取特定受众的详情［可选］
3. MAILCHIMP_LIST_MEMBERS_INFO - 按状态筛选并分页列出成员［必需］
4. MAILCHIMP_SEARCH_MEMBERS - 跨列表按电子邮件或姓名搜索［可选］
5. MAILCHIMP_GET_MEMBER_INFO - 获取特定订阅者的详细资料［可选］
6. MAILCHIMP_LIST_SEGMENTS - 列出受众中的细分［可选］

MAILCHIMP_LIST_MEMBERS_INFO 的关键参数：

• list_id：受众 ID（必需）
• status："subscribed"、"unsubscribed"、"cleaned"、"pending"、"transactional"、"archived"
• count：每页记录数（默认值为 10，最大值为 1000）
• offset：分页偏移量（默认值为 0）
• sort_field："timestamp_opt"、"timestamp_signup" 或 "last_changed"
• fields：以逗号分隔的字段列表，用于限制响应大小

注意事项：

• stats.avg_open_rate 和 stats.avg_click_rate 的值是 0 到 1 的小数，而不是 0 到 100 的百分比
• 始终使用 status="subscribed" 筛选活跃订阅者；省略此参数会返回所有状态的成员
• 必须使用 count 和 offset 进行分页，直到收集的成员数与 total_items 一致
• 大型列表响应可能会被截断；数据位于 response.data.members 中

3. 添加和更新订阅者

使用时机：用户想添加新订阅者、更新现有订阅者或批量管理列表成员时。

工具调用顺序：

1. MAILCHIMP_GET_LIST_INFO - 验证目标受众是否存在［前置条件］
2. MAILCHIMP_SEARCH_MEMBERS - 检查联系人是否已存在［可选］
3. MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER - 插入或更新订阅者（创建或更新）［必需］
4. MAILCHIMP_ADD_MEMBER_TO_LIST - 添加新订阅者（仅创建）［可选］
5. MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS - 批量管理细分成员［可选］

MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER 的关键参数：

• list_id：受众 ID（必需）
• subscriber_hash：小写电子邮件的 MD5 哈希值（必需）
• email_address：订阅者电子邮件（必需）
• status_if_new：新订阅者的状态，例如 "subscribed"、"pending" 等（必需）
• status：现有订阅者的状态
• merge_fields：包含合并标签键的对象（例如，{"FNAME": "John", "LNAME": "Doe"}）
• tags：标签字符串数组

MAILCHIMP_ADD_MEMBER_TO_LIST 的关键参数：

• list_id：受众 ID（必需）
• email_address：订阅者电子邮件（必需）
• status："subscribed"、"pending"、"unsubscribed"、"cleaned"、"transactional"（必需）

注意事项：

• subscriber_hash 必须是小写电子邮件的 MD5 哈希值；大小写不正确会导致 404 错误或重复项
• 使用 MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER（插入或更新），而不是 MAILCHIMP_ADD_MEMBER_TO_LIST，以避免重复项错误
• status_if_new 仅决定新联系人的状态；现有联系人使用 status
• 使用 skip_merge_validation: true 跳过必填合并字段验证
• MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS 管理静态细分成员，而不是列表成员

4. 查看营销活动报告和分析数据

使用时机：用户想查看营销活动表现、打开率、点击率或订阅者参与度。

工具调用顺序：

1. MAILCHIMP_LIST_CAMPAIGNS - 列出已发送的营销活动及报告摘要 [必需]
2. MAILCHIMP_SEARCH_CAMPAIGNS - 按名称、主题或内容查找营销活动 [可选]
3. MAILCHIMP_GET_CAMPAIGN_REPORT - 获取营销活动的详细表现报告 [必需]
4. MAILCHIMP_LIST_CAMPAIGN_REPORTS - 批量获取多个营销活动的报告 [可选]
5. MAILCHIMP_LIST_CAMPAIGN_DETAILS - 获取链接级别的点击统计数据 [可选]
6. MAILCHIMP_GET_CAMPAIGN_LINK_DETAILS - 深入查看特定链接的点击数据 [可选]
7. MAILCHIMP_LIST_CLICKED_LINK_SUBSCRIBERS - 查看点击特定链接的人员 [可选]
8. MAILCHIMP_GET_SUBSCRIBER_EMAIL_ACTIVITY - 获取每位订阅者的营销活动动态 [可选]
9. MAILCHIMP_GET_CAMPAIGN_CONTENT - 获取营销活动的 HTML 内容 [可选]

MAILCHIMP_LIST_CAMPAIGNS 的关键参数：

• status："save"、"paused"、"schedule"、"sending"、"sent"
• count / offset：分页（默认 10，最大 1000）
• since_send_time / before_send_time：ISO 8601 日期范围筛选
• sort_field："create_time" 或 "send_time"
• fields：限制响应字段以提升性能

MAILCHIMP_GET_CAMPAIGN_REPORT 的关键参数：

• campaign_id：营销活动 ID（必需）
• 返回：打开、点击、退信、取消订阅、时间序列和行业统计数据

注意事项：

• MAILCHIMP_LIST_CAMPAIGNS 仅返回高层级的 report_summary；详细指标请使用 MAILCHIMP_GET_CAMPAIGN_REPORT
• 草稿或未发送的营销活动没有有意义的报告数据
• 在 LIST_CAMPAIGNS 中使用 fields 参数时，需明确请求 send_time 和 report_summary 子字段
• 分页默认值较低（10 条记录）；使用 count 和 offset 迭代，直至涵盖 total_items
• send_time 为带时区的 ISO 8601 格式；请谨慎解析

常见模式

ID 解析

操作前始终先将名称解析为 ID：

• 受众名称 -> list_id：调用 MAILCHIMP_GET_LISTS_INFO 并按名称匹配
• 订阅者邮箱 -> subscriber_hash：在代码中计算小写邮箱的 MD5 值
• 营销活动名称 -> campaign_id：使用查询参数调用 MAILCHIMP_SEARCH_CAMPAIGNS
• 细分名称 -> segment_id：使用 list_id 调用 MAILCHIMP_LIST_SEGMENTS

分页

Mailchimp 使用基于偏移量的分页：

• 使用 count（每页数量，最大 1000）和 offset（跳过 N 条记录）
• 持续获取，直至已收集的记录数与响应中的 total_items 一致
• count 默认值为 10；批量操作时务必显式设置
• 搜索端点最多支持 10 页（每页 30 条时共 300 条结果）

订阅者哈希

许多端点要求提供 subscriber_hash（小写邮箱的 MD5 值）：

import hashlib
subscriber_hash = hashlib.md5(email.lower().encode()).hexdigest()

已知注意事项

ID 格式

• list_id（受众 ID）是较短的字母数字字符串（例如 "abc123def4"）
• campaign_id 是字母数字字符串
• subscriber_hash 是 MD5 十六进制字符串（32 个字符）
• 细分 ID 是整数

速率限制

• Mailchimp 会实施 API 速率限制；批量处理订阅者时请使用批处理
• 高密度调用 GET_MEMBER_INFO 和 ADD_OR_UPDATE_LIST_MEMBER 可能触发限流
• 批量处理细分时请使用 MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS

参数注意事项

• 嵌套参数使用双下划线表示法：settings__subject__line、recipients__list__id
• avg_open_rate 和 avg_click_rate 的取值范围为 0 到 1，表示比例而非百分比
• status_if_new 仅适用于更新或插入操作中的新联系人
• subscriber_hash 必须是小写邮箱的 MD5 值；大小写错误会创建虚假记录
• 创建营销活动时必须指定 type；最常见的值是 "regular"
• MAILCHIMP_SEND_CAMPAIGN 成功时返回 HTTP 204（无响应正文）

内容和合规性

• 营销活动的 HTML 必须包含取消订阅链接和实际地址（合并标签）
• 发送前必须通过 MAILCHIMP_SET_CAMPAIGN_CONTENT 设置内容
• 测试邮件要求营销活动已设置内容

Quick Reference

Task	Tool Slug	Key Params
List audiences	MAILCHIMP_GET_LISTS_INFO	count, offset
Get audience details	MAILCHIMP_GET_LIST_INFO	list_id
Create campaign	MAILCHIMP_ADD_CAMPAIGN	type, recipients__list__id, settings__subject__line
Set campaign content	MAILCHIMP_SET_CAMPAIGN_CONTENT	campaign_id, html
Send test email	MAILCHIMP_SEND_TEST_EMAIL	campaign_id, test_emails
Send campaign	MAILCHIMP_SEND_CAMPAIGN	campaign_id
Schedule campaign	MAILCHIMP_SCHEDULE_CAMPAIGN	campaign_id, schedule_time
Get campaign info	MAILCHIMP_GET_CAMPAIGN_INFO	campaign_id
Search campaigns	MAILCHIMP_SEARCH_CAMPAIGNS	query
List campaigns	MAILCHIMP_LIST_CAMPAIGNS	status, count, offset
Replicate campaign	MAILCHIMP_REPLICATE_CAMPAIGN	campaign_id
List subscribers	MAILCHIMP_LIST_MEMBERS_INFO	list_id, status, count, offset
Search members	MAILCHIMP_SEARCH_MEMBERS	query, list_id
Get member info	MAILCHIMP_GET_MEMBER_INFO	list_id, subscriber_hash
Add subscriber	MAILCHIMP_ADD_MEMBER_TO_LIST	list_id, email_address, status
Upsert subscriber	MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER	list_id, subscriber_hash, email_address, status_if_new
Batch members	MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS	list_id, segment_id
List segments	MAILCHIMP_LIST_SEGMENTS	list_id
Campaign report	MAILCHIMP_GET_CAMPAIGN_REPORT	campaign_id
All reports	MAILCHIMP_LIST_CAMPAIGN_REPORTS	count, offset
Link click details	MAILCHIMP_LIST_CAMPAIGN_DETAILS	campaign_id, count
Subscriber activity	MAILCHIMP_GET_SUBSCRIBER_EMAIL_ACTIVITY	campaign_id, subscriber_hash
Member recent activity	MAILCHIMP_VIEW_RECENT_ACTIVITY	list_id, subscriber_hash
Campaign content	MAILCHIMP_GET_CAMPAIGN_CONTENT	campaign_id

---

Powered by Composio