mailchimp-automation

通过 Rube MCP 实现 Mailchimp 自动化

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

前提条件

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

设置

使用现有的已批准 Rube 连接；仅配置端点无法完成 Mailchimp 身份验证。若需设置，请使用受支持的主机流程。

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
• 保留合并字段验证；只有在有文档说明的架构依据时才绕过必填字段，绝不能将其作为默认的错误规避方式
• 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 设置内容
• 测试邮件要求营销活动已设置内容

快速参考

任务	工具标识	关键参数
列出受众	MAILCHIMP_GET_LISTS_INFO	count, offset
获取受众详情	MAILCHIMP_GET_LIST_INFO	list_id
创建营销活动	MAILCHIMP_ADD_CAMPAIGN	type, recipients__list__id, settings__subject__line
设置营销活动内容	MAILCHIMP_SET_CAMPAIGN_CONTENT	campaign_id, html
发送测试邮件	MAILCHIMP_SEND_TEST_EMAIL	campaign_id, test_emails
发送营销活动	MAILCHIMP_SEND_CAMPAIGN	campaign_id
定时发送营销活动	MAILCHIMP_SCHEDULE_CAMPAIGN	campaign_id, schedule_time
获取营销活动信息	MAILCHIMP_GET_CAMPAIGN_INFO	campaign_id
搜索营销活动	MAILCHIMP_SEARCH_CAMPAIGNS	query
列出营销活动	MAILCHIMP_LIST_CAMPAIGNS	status, count, offset
复制营销活动	MAILCHIMP_REPLICATE_CAMPAIGN	campaign_id
列出订阅者	MAILCHIMP_LIST_MEMBERS_INFO	list_id, status, count, offset
搜索成员	MAILCHIMP_SEARCH_MEMBERS	query, list_id
获取成员信息	MAILCHIMP_GET_MEMBER_INFO	list_id, subscriber_hash
添加订阅者	MAILCHIMP_ADD_MEMBER_TO_LIST	list_id, email_address, status
更新插入订阅者	MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER	list_id, subscriber_hash, email_address, status_if_new
批量处理成员	MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS	list_id, segment_id
列出细分	MAILCHIMP_LIST_SEGMENTS	list_id
营销活动报告	MAILCHIMP_GET_CAMPAIGN_REPORT	campaign_id
所有报告	MAILCHIMP_LIST_CAMPAIGN_REPORTS	count, offset
链接点击详情	MAILCHIMP_LIST_CAMPAIGN_DETAILS	campaign_id, count
订阅者活动	MAILCHIMP_GET_SUBSCRIBER_EMAIL_ACTIVITY	campaign_id, subscriber_hash
成员近期活动	MAILCHIMP_VIEW_RECENT_ACTIVITY	list_id, subscriber_hash
营销活动内容	MAILCHIMP_GET_CAMPAIGN_CONTENT	campaign_id

何时使用

该技能适用于执行概述中描述的工作流或操作。

限制

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