sendgrid-automation

通过 Rube MCP 自动化 SendGrid

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

前提条件

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

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。对 MCP 服务/客户端进行身份验证并授权 SendGrid 账户；仅有此端点并不能获得访问权限。

1. 确认 RUBE_SEARCH_TOOLS 能够响应，以验证 Rube MCP 可用
2. 使用工具包 sendgrid 调用 RUBE_MANAGE_CONNECTIONS
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
• 提供服务要求的退订配置，并另行核实适用的同意和退订要求
• 使用前必须验证发件人；请通过 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 验证
• 验证实际任务结果和预期的联系人归属；仅凭数量增长无法证明所有更改都已成功

已知注意事项

ID 格式

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

速率限制

• SendGrid 可能会返回 HTTP 429；请遵守 Retry-After 标头
• CSV 导出每 12 小时仅限请求一次
• 批量联系人 upsert 上限：每次请求 30,000 个联系人或 6MB

参数注意事项

• 嵌套参数使用双下划线：email__config__subject、from__email
• send_at 在 CREATE_SINGLE_SEND 中仅设置界面默认值，不会安排发送时间
• 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 的 SendGrid 工具包，自动化 SendGrid 邮件投递工作流，包括营销活动（Single Sends）、联系人和列表管理、发件人身份设置以及邮件分析。

限制

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

这是历史连接器架构/限制快照；实时发现结果和提供商文档优先。创建 Single Send 只是草稿，并不能证明邮件已送达；只有在发送已获明确授权，且最终内容、发件人、受众和时间均已确定时，才发现实际的计划发送端点。不要默认使用 send_to_all。导入联系人并不代表已获得同意，也不允许重新订阅已被抑制的收件人。验证邮件、更改发件人和 DNS 身份验证都需要各自获得授权的目标。应使用有界退避轮询异步任务，而不要假定固定延迟；对于结果未知的发送，不要重复操作。打开/点击事件可能来自隐私代理或机器人，并非真人阅读。尽量减少导出中的收件人数据，并将临时下载 URL 视为敏感信息。