gmail-automation

通过 Rube MCP 自动化 Gmail

通过 Rube MCP 使用 Composio 的 Gmail 工具包自动化 Gmail 操作。

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

前提条件

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

设置

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

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

核心工作流

1. 发送邮件

适用情况：用户想撰写并发送新邮件

工具调用顺序：

1. GMAIL_SEARCH_PEOPLE - 将联系人姓名解析为电子邮件地址［可选］
2. GMAIL_SEND_EMAIL - 发送邮件［必需］

关键参数：

• recipient_email：电子邮件地址，或用 'me' 表示自己
• subject：邮件主题
• body：邮件内容（纯文本或 HTML）
• is_html：如果正文包含 HTML 标记，则必须设为 true
• cc/bcc：电子邮件地址数组
• attachment：包含 {s3key, mimetype, name} 的对象，取自之前的下载操作

注意事项：

• recipient_email、cc 或 bcc 中至少有一个为必填项
• subject 或 body 中至少有一个为必填项
• 附件的 mimetype 必须包含“/”（例如 'application/pdf'，而不是 'pdf'）
• Base64 编码后的邮件总大小上限约为 25MB
• from_email 只能用于 Gmail“Send mail as”设置中已验证的别名

2. 回复邮件会话

适用情况：用户想回复现有的邮件会话

工具调用顺序：

1. GMAIL_FETCH_EMAILS - 查找要回复的邮件/会话［前置条件］
2. GMAIL_REPLY_TO_THREAD - 在会话中发送回复［必需］

关键参数：

• thread_id：来自 FETCH_EMAILS 的十六进制字符串（例如 '169eefc8138e68ca'）
• message_body：回复内容
• recipient_email：回复对象
• is_html：HTML 内容请设为 true

注意事项：

• thread_id 必须是十六进制字符串；'msg-f:' 之类的前缀会自动移除
• 不支持旧版 Gmail 网页界面的 ID（例如 'FMfcgz...'）
• 主题会沿用原会话的主题；设置主题会另建一个会话
• 若要在原会话中回复，请勿添加主题参数

3. 搜索和筛选邮件

适用情况：用户想按发件人、主题、日期、标签等查找特定邮件

工具调用顺序：

1. GMAIL_FETCH_EMAILS - 使用 Gmail 查询语法搜索［必需］
2. GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID - 获取所选结果的完整邮件详情［可选］

关键参数：

• query：Gmail 搜索语法（from:、to:、subject:、is:unread、has:attachment、after:YYYY/MM/DD、before:YYYY/MM/DD）
• max_results：每页 1-500 封邮件
• label_ids：系统 ID，例如 'INBOX'、'UNREAD'
• include_payload：设为 true 以获取完整邮件内容
• ids_only：设为 true 以仅获取邮件 ID
• page_token：用于分页（取自 nextPageToken）

注意事项：

• 每页最多返回约 500 封邮件；请通过 page_token 使用 nextPageToken，直到不再返回该令牌
• resultSizeEstimate 是近似值，并非精确数量
• 对状态使用 'is:'（is:unread、is:snoozed、is:starred）
• 仅对用户创建的标签使用 'label:'
• 常见错误：'label:snoozed' 是错误用法——应使用 'is:snoozed'
• 在范围较大的搜索中设置 include_payload=true 会产生巨大的响应；默认仅获取元数据
• 自定义标签必须使用标签 ID（例如 'Label_123'），而不是标签名称

4. 管理标签

适用场景：用户希望创建、修改或整理标签

工具调用顺序：

1. GMAIL_LIST_LABELS - 列出所有标签，以查找 ID 并检测冲突 [必需]
2. GMAIL_CREATE_LABEL - 创建新标签 [可选]
3. GMAIL_PATCH_LABEL - 重命名标签或更改标签颜色/可见性 [可选]
4. GMAIL_DELETE_LABEL - 删除用户创建的标签（不可撤销）[可选]

关键参数：

• label_name：最多 225 个字符，不得包含逗号；使用 '/' 表示嵌套（例如，'Work/Projects'）
• background_color/text_color：Gmail 预定义调色板中的十六进制值
• id：PATCH/DELETE 操作所用的标签 ID

注意事项：

• 名称为空、重复或为保留名称（INBOX、SPAM、CATEGORY_*）时会返回 400/409 错误
• 颜色规格必须使用 Gmail 预定义调色板中的 102 个十六进制值
• DELETE 操作不可撤销，并会从所有邮件中移除该标签
• 无法删除系统标签（INBOX、SENT、DRAFT 等）

5. 为邮件添加/移除标签

适用场景：用户希望为邮件添加标签、归档邮件，或将邮件标记为已读/未读

工具调用顺序：

1. GMAIL_LIST_LABELS - 获取自定义标签的 ID [前置条件]
2. GMAIL_FETCH_EMAILS - 查找目标邮件 [前置条件]
3. GMAIL_BATCH_MODIFY_MESSAGES - 批量添加/移除标签（最多 1000 封邮件）[必需]
4. GMAIL_ADD_LABEL_TO_EMAIL - 更改单封邮件的标签 [备用方案]

关键参数：

• messageIds：邮件 ID 数组（最多 1000 个）
• addLabelIds：要添加的标签 ID 数组
• removeLabelIds：要移除的标签 ID 数组
• message_id：用于单封邮件操作的 15-16 位十六进制字符串

注意事项：

• 每次 BATCH 调用最多处理 1000 个 messageIds；较大的集合需分批处理
• 使用 'CATEGORY_UPDATES'，而不是 'UPDATES'；类别标签必须使用完整前缀
• SENT、DRAFT、CHAT 不可更改，无法添加或移除
• 将邮件标记为已读：移除 'UNREAD'。归档邮件：移除 'INBOX'
• message_id 必须是 15-16 位十六进制字符串，不能使用 UUID 或网页界面 ID

6. 处理草稿和附件

适用场景：用户希望创建、编辑或发送邮件草稿，也可能包含附件

工具调用顺序：

1. GMAIL_CREATE_EMAIL_DRAFT - 创建新草稿 [必需]
2. GMAIL_UPDATE_DRAFT - 编辑草稿内容 [可选]
3. GMAIL_LIST_DRAFTS - 列出现有草稿 [可选]
4. GMAIL_SEND_DRAFT - 发送草稿（需要用户明确批准）[可选]
5. GMAIL_GET_ATTACHMENT - 下载现有邮件中的附件 [可选]

关键参数：

• recipient_email：草稿收件人
• subject：草稿主题（回复草稿可省略，以保留在原会话中）
• body：草稿内容
• is_html：HTML 内容设为 true
• attachment：包含 {s3key, mimetype, name} 的对象
• thread_id：用于回复草稿（将主题留空以保留在原会话中）

注意事项：

• 响应包含 data.id（draft_id）和 data.message.id；草稿操作请使用 data.id
• 为会话回复草稿设置主题会改为创建一个新会话
• 附件上限约为 25MB；base64 编码开销可能导致接近上限的文件超出限制
• UPDATE_DRAFT 会替换全部内容，而不是仅更新部分内容；请包含所有要保留的字段
• 批量创建草稿时可能收到 HTTP 429；请使用指数退避

常见模式

ID 解析

标签名称 → 标签 ID：

1. Call GMAIL_LIST_LABELS
2. Find label by name in response
3. Extract id field (e.g., 'Label_123')

联系人姓名 → 邮箱：

1. Call GMAIL_SEARCH_PEOPLE with query=contact_name
2. Extract emailAddresses from response

从搜索结果获取会话 ID：

1. Call GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS
2. Extract threadId (15-16 char hex string)

分页

• 每页的 max_results 最多设为 500
• 检查响应中的 nextPageToken
• 在下一次请求中将该令牌作为 page_token 传入
• 持续请求，直到 nextPageToken 不存在或为空字符串
• resultSizeEstimate 是估算值，并非精确值

Gmail 查询语法

运算符：

• from:[email protected] - 来自发件人的邮件
• to:[email protected] - 发给收件人的邮件
• subject:"exact phrase" - 主题包含确切短语
• is:unread - 未读邮件
• is:starred - 已加星标的邮件
• is:snoozed - 已延后的邮件
• has:attachment - 有附件
• after:2024/01/01 - 日期之后（YYYY/MM/DD）
• before:2024/12/31 - 日期之前
• label:custom_label - 用户创建的标签（使用标签 ID）
• in:sent - 位于已发送文件夹
• category:primary - 主要类别

组合运算符：

• AND - 同时满足两个条件（默认）
• OR - 满足任一条件
• NOT - 排除条件
• () - 对条件分组

示例：

• from:[email protected] is:unread - 来自老板的未读邮件
• subject:invoice has:attachment after:2024/01/01 - 今年带附件的发票
• (from:alice OR from:bob) is:starred - 来自 Alice 或 Bob 的已加星标邮件

已知注意事项

ID 格式：

• 自定义标签操作需要标签 ID（例如，'Label_123'），而不是显示名称
• 始终先调用 LIST_LABELS，将名称解析为 ID
• 邮件 ID 是 15-16 位十六进制字符串
• 不要使用 UUID、网页界面 ID 或 'thread-f:' 前缀

查询语法：

• 状态（未读、延后、已加星标）使用 'is:'
• 仅对用户创建的标签使用 'label:'
• 系统标签使用 'is:' 或 'in:'（例如，'is:sent'、'in:inbox'）

速率限制：

• BATCH_MODIFY_MESSAGES 每次调用最多处理 1000 封邮件
• 频繁使用会触发 403/429 速率限制
• 批量操作时实现指数退避

响应解析：

• 响应数据可能嵌套在 data_preview 或 data.messages 下
• 使用回退方案进行稳健解析
• 时间戳 messageTimestamp 使用带 'Z' 后缀的 RFC3339 格式
• 如有需要，解析前将其规范化为 '+00:00'

附件：

• 之前下载时获取的附件 s3key 可能会过期
• 获取后尽快使用
• Mimetype 必须包含 '/' 分隔符

快速参考

任务	工具标识	关键参数
发送邮件	GMAIL_SEND_EMAIL	recipient_email, subject, body, is_html
回复邮件会话	GMAIL_REPLY_TO_THREAD	thread_id, message_body, recipient_email
搜索邮件	GMAIL_FETCH_EMAILS	query, max_results, label_ids, page_token
获取邮件详情	GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID	message_id
列出标签	GMAIL_LIST_LABELS	(none)
创建标签	GMAIL_CREATE_LABEL	label_name, background_color, text_color
批量修改标签	GMAIL_BATCH_MODIFY_MESSAGES	messageIds, addLabelIds, removeLabelIds
创建草稿	GMAIL_CREATE_EMAIL_DRAFT	recipient_email, subject, body, thread_id
发送草稿	GMAIL_SEND_DRAFT	draft_id
获取附件	GMAIL_GET_ATTACHMENT	message_id, attachment_id
搜索联系人	GMAIL_SEARCH_PEOPLE	query
获取个人资料	GMAIL_GET_PROFILE	(none)

---

由 Composio 提供支持