sendgrid-automation

通过 Rube MCP 自动化 SendGrid

通过 Composio 的 SendGrid 工具包，自动化 SendGrid 邮件发送工作流，包括营销活动（Single Sends）、联系人和列表管理、发件人身份设置及邮件分析。

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

前提条件

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

设置

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

1. 确认 RUBE_SEARCH_TOOLS 能够响应，以验证 Rube MCP 可用
2. 调用 RUBE_MANAGE_CONNECTIONS，工具包设为 sendgrid
3. 如果连接状态不是 ACTIVE，请按照返回的授权链接完成 SendGrid API 密钥身份验证
4. 运行任何工作流前，确认连接状态显示为 ACTIVE

核心工作流

1. 创建并发送营销活动（Single Sends）

适用场景：用户希望创建营销邮件活动，并将其发送给联系人列表或细分群体。

工具调用顺序：

1. SENDGRID_RETRIEVE_ALL_LISTS - 列出可用的营销列表，以便确定目标 [前置条件]
2. SENDGRID_CREATE_A_LIST - 如有需要，创建新列表 [可选]
3. SENDGRID_ADD_OR_UPDATE_A_CONTACT - 将联系人添加到列表 [可选]
4. SENDGRID_GET_ALL_SENDER_IDENTITIES - 获取已验证的发件人 ID [前置条件]
5. SENDGRID_CREATE_SINGLE_SEND - 创建包含内容、发件人和收件人的营销活动 [必需]

SENDGRID_CREATE_SINGLE_SEND 的关键参数：

• name：营销活动名称（必需）
• email__config__subject：邮件主题行
• email__config__html__content：HTML 正文内容
• email__config__plain__content：纯文本版本
• email__config__sender__id：已验证的发件人身份 ID
• email__config__design__id：使用预先制作的设计时替代 html_content
• send__to__list__ids：要发送到的列表 UUID 数组
• send__to__segment__ids：细分群体 UUID 数组
• send__to__all：设为 true 可发送给所有联系人
• email__config__suppression__group__id 或 email__config__custom__unsubscribe__url：为符合规范，必须提供其中一项

注意事项：

• 在 CREATE 中设置 send_at 不会安排发送时间，只会预先填入界面中的日期；请单独使用 Schedule 端点
• send_at: "now" 仅适用于 Schedule 端点，不适用于 CREATE
• 为符合退订规范，必须提供 suppression_group_id 或 custom_unsubscribe_url
• 发件人必须先通过验证才能使用；请使用 SENDGRID_GET_ALL_SENDER_IDENTITIES 检查
• 嵌套参数使用双下划线表示法（例如 email__config__subject）

2. 管理联系人和列表

使用时机：用户想要创建联系人列表、添加/更新联系人、搜索联系人，或从列表中移除联系人。

工具调用顺序：

1. SENDGRID_RETRIEVE_ALL_LISTS - 列出所有营销列表 [Required]
2. SENDGRID_CREATE_A_LIST - 创建新的联系人列表 [Optional]
3. SENDGRID_GET_A_LIST_BY_ID - 获取列表详情和示例联系人 [Optional]
4. SENDGRID_ADD_OR_UPDATE_A_CONTACT - 添加或更新联系人，并关联列表 [Required]
5. SENDGRID_GET_CONTACTS_BY_EMAILS - 按电子邮件查找联系人 [Optional]
6. SENDGRID_GET_CONTACTS_BY_IDENTIFIERS - 按电子邮件、电话或外部 ID 查找联系人 [Optional]
7. SENDGRID_GET_LIST_CONTACT_COUNT - 操作后验证联系人数量 [Optional]
8. SENDGRID_REMOVE_CONTACTS_FROM_A_LIST - 从列表中移除联系人，但不删除联系人 [Optional]
9. SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS - 删除整个列表 [Optional]
10. SENDGRID_IMPORT_CONTACTS - 从 CSV 批量导入 [Optional]

SENDGRID_ADD_OR_UPDATE_A_CONTACT 的关键参数：

• contacts：联系人对象数组（最多 30,000 个或 6MB），每个对象至少包含一个标识符：email、phone_number_id、external_id 或 anonymous_id（必填）
• list_ids：用于关联联系人的列表 UUID 字符串数组

注意事项：

• SENDGRID_ADD_OR_UPDATE_A_CONTACT 为异步操作；会返回 202 和 job_id；联系人可能需要 10-30 秒才会显示
• 列表 ID 是 UUID（例如 "ca7a3796-e8a8-4029-9ccb-df8937940562"），而不是整数
• 列表名称必须唯一；重复名称会导致 400 错误
• SENDGRID_ADD_A_SINGLE_RECIPIENT_TO_A_LIST 使用旧版 API；建议改用带有 list_ids 的 SENDGRID_ADD_OR_UPDATE_A_CONTACT
• SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS 操作不可逆；必须先征得用户明确确认
• SendGrid 会自动将电子邮件地址转换为小写

3. 管理发件人身份

使用时机：用户想要设置或查看用于发送电子邮件的发件人身份（发件人地址）。

工具调用顺序：

1. SENDGRID_GET_ALL_SENDER_IDENTITIES - 列出所有现有发件人身份 [Required]
2. SENDGRID_CREATE_A_SENDER_IDENTITY - 创建新的发件人身份 [Optional]
3. SENDGRID_VIEW_A_SENDER_IDENTITY - 查看特定发件人的详情 [Optional]
4. SENDGRID_UPDATE_A_SENDER_IDENTITY - 更新发件人详情 [Optional]
5. SENDGRID_CREATE_VERIFIED_SENDER_REQUEST - 创建并验证新的发件人 [Optional]
6. SENDGRID_AUTHENTICATE_A_DOMAIN - 设置域名身份验证以实现自动验证 [Optional]

SENDGRID_CREATE_A_SENDER_IDENTITY 的关键参数：

• from__email：发件人电子邮件地址（必填）
• from__name：显示名称（必填）
• reply__to__email：回复地址（必填）
• nickname：内部标识符（必填）
• address、city、country：用于遵守 CAN-SPAM 要求的实际地址（必填）

注意事项：

• 新发件人必须先通过验证才能使用；如果域名未经身份验证，系统会发送验证电子邮件
• 每个账户最多可有 100 个不重复的发件人身份
• 避免使用 DMARC 政策严格的域名（gmail.com、yahoo.com）作为发件人地址
• SENDGRID_CREATE_VERIFIED_SENDER_REQUEST 会发送验证电子邮件；验证完成前无法使用该发件人

4. 查看电子邮件统计数据和活动

使用场景：用户想查看电子邮件投递统计数据、退信率、打开/点击指标或消息活动。

工具调用顺序：

1. SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS - 获取账户范围的投递指标 [必需]
2. SENDGRID_GET_ALL_CATEGORIES - 查找可用于筛选的类别 [可选]
3. SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES - 获取按类别细分的统计数据 [可选]
4. SENDGRID_FILTER_ALL_MESSAGES - 按收件人、状态或日期搜索电子邮件活动流 [可选]
5. SENDGRID_FILTER_MESSAGES_BY_MESSAGE_ID - 获取特定消息的详细事件 [可选]
6. SENDGRID_REQUEST_CSV - 将活动数据导出为 CSV，适用于大型数据集 [可选]
7. SENDGRID_DOWNLOAD_CSV - 下载导出的 CSV 文件 [可选]

SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS 的关键参数：

• start_date：开始日期 YYYY-MM-DD（必需）
• end_date：结束日期 YYYY-MM-DD
• aggregated_by："day"、"week" 或 "month"
• limit / offset：分页（默认值为 500）

SENDGRID_FILTER_ALL_MESSAGES 的关键参数：

• query：类似 SQL 的查询字符串，例如 status="delivered"、to_email="[email protected]"，以及使用 BETWEEN TIMESTAMP 的日期范围
• limit：1-1000（默认值为 10）

注意事项：

• SENDGRID_FILTER_ALL_MESSAGES 需要付费附加功能 "30 Days Additional Email Activity History"；未启用时会返回 403
• 全局统计数据嵌套在 details[].stats[0].metrics 下，而非扁平结构
• 类别统计数据仅适用于此前 13 个月
• SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES 每次请求最多支持 10 个类别
• CSV 导出每 12 小时限一次；链接会在 3 天后过期

5. 管理抑制列表

使用场景：用户想查看或管理退订组，以符合电子邮件规范。

工具调用顺序：

1. SENDGRID_GET_SUPPRESSION_GROUPS - 列出所有抑制组 [必需]
2. SENDGRID_RETRIEVE_ALL_SUPPRESSION_GROUPS_FOR_AN_EMAIL_ADDRESS - 检查特定电子邮件地址的抑制状态 [可选]

注意事项：

• 即使抑制地址存在于营销列表中，也仍无法向其投递
• 由于存在抑制项，营销活动的发送数量可能少于列表数量

常见模式

ID 解析

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

• 列表名称 -> list_id：调用 SENDGRID_RETRIEVE_ALL_LISTS 并按名称匹配
• 发件人名称 -> sender_id：调用 SENDGRID_GET_ALL_SENDER_IDENTITIES 并匹配
• 联系人电子邮件 -> contact_id：使用电子邮件数组调用 SENDGRID_GET_CONTACTS_BY_EMAILS
• 模板名称 -> template_id：使用 SendGrid 界面或模板端点

分页

• SENDGRID_RETRIEVE_ALL_LISTS：使用 page_token 和 page_size（最大值为 1000）进行基于令牌的分页
• SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS：使用 limit（最大值为 500）和 offset 进行基于偏移量的分页
• 获取列表时始终进行分页，以免遗漏现有列表

异步操作

联系人操作（ADD_OR_UPDATE_A_CONTACT、IMPORT_CONTACTS）为异步操作：

• 返回 202 和一个 job_id
• 等待 10-30 秒后，再使用 GET_CONTACTS_BY_EMAILS 验证
• 使用 GET_LIST_CONTACT_COUNT 确认列表数量增加

已知注意事项

ID 格式

• 营销列表 ID 为 UUID（例如 "ca7a3796-e8a8-4029-9ccb-df8937940562"）
• 旧版列表 ID 为整数；不要将其用于 Marketing API 端点
• 发件人身份 ID 为整数
• 模板 ID：动态模板以 "d-" 开头，旧版模板为 UUID
• 联系人 ID 为 UUID

速率限制

• SendGrid 可能返回 HTTP 429；请遵循 Retry-After 标头
• CSV 导出每 12 小时限一次
• 联系人批量插入或更新上限：每次请求最多 30,000 个联系人或 6MB

参数注意事项

• 嵌套参数使用双下划线：email__config__subject、from__email
• send_at 在 CREATE_SINGLE_SEND 上仅设置 UI 默认值，不会安排发送
• SENDGRID_ADD_A_SINGLE_RECIPIENT_TO_A_LIST 使用旧版 API；recipient_id 是经过 Base64 编码的小写邮箱地址
• SENDGRID_RETRIEVE_ALL_LISTS 和 SENDGRID_GET_ALL_LISTS 都存在；对于 Marketing API，优先使用 RETRIEVE_ALL_LISTS
• 添加联系人是异步操作（202）；请务必在延迟一段时间后进行验证

旧版 API 与 Marketing API

• 部分工具使用旧版 Contact Database API（/v3/contactdb/），在较新的账户上可能会返回 403
• 优先使用 Marketing API 工具：SENDGRID_ADD_OR_UPDATE_A_CONTACT、SENDGRID_RETRIEVE_ALL_LISTS、SENDGRID_CREATE_SINGLE_SEND

快速参考

任务	工具标识	关键参数
列出营销列表	SENDGRID_RETRIEVE_ALL_LISTS	page_size、page_token
创建列表	SENDGRID_CREATE_A_LIST	name
按 ID 获取列表	SENDGRID_GET_A_LIST_BY_ID	id
获取列表联系人数量	SENDGRID_GET_LIST_CONTACT_COUNT	id
添加/更新联系人	SENDGRID_ADD_OR_UPDATE_A_CONTACT	contacts、list_ids
按邮箱搜索联系人	SENDGRID_GET_CONTACTS_BY_EMAILS	emails
按标识符搜索	SENDGRID_GET_CONTACTS_BY_IDENTIFIERS	identifier_type、identifiers
从列表中移除	SENDGRID_REMOVE_CONTACTS_FROM_A_LIST	id、contact_ids
删除列表	SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS	id、delete_contacts
导入联系人 CSV	SENDGRID_IMPORT_CONTACTS	字段映射
创建 Single Send	SENDGRID_CREATE_SINGLE_SEND	name、email__config__*、send__to__list__ids
列出发件人身份	SENDGRID_GET_ALL_SENDER_IDENTITIES	（无）
创建发件人	SENDGRID_CREATE_A_SENDER_IDENTITY	from__email、from__name、address
验证发件人	SENDGRID_CREATE_VERIFIED_SENDER_REQUEST	from_email、nickname、address
验证域名	SENDGRID_AUTHENTICATE_A_DOMAIN	domain
全局邮件统计	SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS	start_date、aggregated_by
分类统计	SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES	start_date、categories
筛选邮件活动	SENDGRID_FILTER_ALL_MESSAGES	query、limit
邮件详情	SENDGRID_FILTER_MESSAGES_BY_MESSAGE_ID	msg_id
导出 CSV	SENDGRID_REQUEST_CSV	query
下载 CSV	SENDGRID_DOWNLOAD_CSV	download_uuid
列出类别	SENDGRID_GET_ALL_CATEGORIES	（无）
抑制组	SENDGRID_GET_SUPPRESSION_GROUPS	（无）
获取模板	SENDGRID_RETRIEVE_A_SINGLE_TRANSACTIONAL_TEMPLATE	template_id
复制模板	SENDGRID_DUPLICATE_A_TRANSACTIONAL_TEMPLATE	template_id、name

---

由 Composio 提供支持