gmail-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gmail Automation via Rube MCP

通过Rube MCP实现Gmail自动化

Automate Gmail operations through Composio's Gmail toolkit via Rube MCP.

Toolkit docs: composio.dev/toolkits/gmail

通过Composio的Gmail工具包，借助Rube MCP自动化Gmail操作。

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

Prerequisites

前提条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active Gmail connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
gmail
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（需可使用
```
RUBE_SEARCH_TOOLS
```
）
通过
```
RUBE_MANAGE_CONNECTIONS
```
并选择工具包
```
gmail
```
，完成Gmail的激活连接
请始终先调用
```
RUBE_SEARCH_TOOLS
```
获取最新的工具架构

Setup

设置步骤

Get Rube MCP: Add

https://rube.app/mcp

as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
gmail
```
If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥 — 只需添加端点即可使用。

确认
```
RUBE_SEARCH_TOOLS
```
可正常响应，以此验证Rube MCP是否可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
并指定工具包
```
gmail
```
如果连接状态未显示为ACTIVE，请按照返回的授权链接完成Google OAuth认证
在运行任何工作流之前，确认连接状态为ACTIVE

Core Workflows

核心工作流

1. Send an Email

1. 发送邮件

When to use: User wants to compose and send a new email

Tool sequence:

```
GMAIL_SEARCH_PEOPLE
```
- Resolve contact name to email address [Optional]
```
GMAIL_SEND_EMAIL
```
- Send the email [Required]

Key parameters:

```
recipient_email
```
: Email address or 'me' for self
```
subject
```
: Email subject line
```
body
```
: Email content (plain text or HTML)
```
is_html
```
: Must be
```
true
```
if body contains HTML markup
```
cc
```
/
```
bcc
```
: Arrays of email addresses
```
attachment
```
: Object with
```
{s3key, mimetype, name}
```
from prior download

Pitfalls:

At least one of
```
recipient_email
```
,
```
cc
```
, or
```
bcc
```
required
At least one of
```
subject
```
or
```
body
```
required
Attachment
```
mimetype
```
MUST contain '/' (e.g., 'application/pdf', not 'pdf')
Total message size limit ~25MB after base64 encoding
Use
```
from_email
```
only for verified aliases in Gmail 'Send mail as' settings

适用场景：用户需要撰写并发送新邮件

工具序列:

```
GMAIL_SEARCH_PEOPLE
```
- 将联系人姓名解析为邮箱地址（可选）
```
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“以其他身份发送”设置中已验证的别名时，才可使用该参数

2. Reply to a Thread

2. 回复邮件线程

When to use: User wants to reply to an existing email conversation

Tool sequence:

```
GMAIL_FETCH_EMAILS
```
- Find the email/thread to reply to [Prerequisite]
```
GMAIL_REPLY_TO_THREAD
```
- Send reply within the thread [Required]

Key parameters:

```
thread_id
```
: Hex string from FETCH_EMAILS (e.g., '169eefc8138e68ca')
```
message_body
```
: Reply content
```
recipient_email
```
: Reply recipient
```
is_html
```
: Set
```
true
```
for HTML content

Pitfalls:

```
thread_id
```
must be hex string; prefixes like 'msg-f:' are auto-stripped
Legacy Gmail web UI IDs (e.g., 'FMfcgz...') are NOT supported
Subject is inherited from original thread; setting it creates a new thread instead
Do NOT include subject parameter to stay within thread

适用场景：用户需要回复现有邮件会话

工具序列:

```
GMAIL_FETCH_EMAILS
```
- 找到需要回复的邮件/线程（前提步骤）
```
GMAIL_REPLY_TO_THREAD
```
- 在该线程内发送回复（必填）

关键参数:

```
thread_id
```
: 来自FETCH_EMAILS的十六进制字符串（例如'169eefc8138e68ca'）
```
message_body
```
: 回复内容
```
recipient_email
```
: 回复收件人
```
is_html
```
: 若为HTML内容则设为
```
true
```

注意事项:

```
thread_id
```
必须是十六进制字符串；类似'thread-f:'的前缀会被自动移除
不支持旧版Gmail网页端ID（例如'FMfcgz...'）
主题会继承自原线程；若手动设置主题，将创建新的线程
请勿填写subject参数，以确保回复在原线程内

3. Search and Filter Emails

3. 搜索与筛选邮件

When to use: User wants to find specific emails by sender, subject, date, label, etc.

Tool sequence:

```
GMAIL_FETCH_EMAILS
```
- Search with Gmail query syntax [Required]
```
GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID
```
- Get full message details for selected results [Optional]

Key parameters:

```
query
```
: Gmail search syntax (from:, to:, subject:, is:unread, has:attachment, after:YYYY/MM/DD, before:YYYY/MM/DD)
```
max_results
```
: 1-500 messages per page
```
label_ids
```
: System IDs like 'INBOX', 'UNREAD'
```
include_payload
```
: Set
```
true
```
to get full message content
```
ids_only
```
: Set
```
true
```
for just message IDs
```
page_token
```
: For pagination (from
```
nextPageToken
```
)

Pitfalls:

Returns max ~500 per page; follow
```
nextPageToken
```
via
```
page_token
```
until absent
```
resultSizeEstimate
```
is approximate, not exact count
Use 'is:' for states (is:unread, is:snoozed, is:starred)
Use 'label:' ONLY for user-created labels
Common mistake: 'label:snoozed' is WRONG — use 'is:snoozed'
```
include_payload=true
```
on broad searches creates huge responses; default to metadata
Custom labels require label ID (e.g., 'Label_123'), NOT label name

适用场景：用户需要按发件人、主题、日期、标签等条件查找特定邮件

工具序列:

```
GMAIL_FETCH_EMAILS
```
- 使用Gmail查询语法进行搜索（必填）
```
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. Manage Labels

4. 管理标签

When to use: User wants to create, modify, or organize labels

Tool sequence:

```
GMAIL_LIST_LABELS
```
- List all labels to find IDs and detect conflicts [Required]
```
GMAIL_CREATE_LABEL
```
- Create a new label [Optional]
```
GMAIL_PATCH_LABEL
```
- Rename or change label colors/visibility [Optional]
```
GMAIL_DELETE_LABEL
```
- Delete a user-created label (irreversible) [Optional]

Key parameters:

```
label_name
```
: Max 225 chars, no commas, '/' for nesting (e.g., 'Work/Projects')
```
background_color
```
/
```
text_color
```
: Hex values from Gmail's predefined palette
```
id
```
: Label ID for PATCH/DELETE operations

Pitfalls:

400/409 error if name is blank, duplicate, or reserved (INBOX, SPAM, CATEGORY_*)
Color specs must use Gmail's predefined palette of 102 hex values
DELETE is permanent and removes label from all messages
Cannot delete system labels (INBOX, SENT, DRAFT, etc.)

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

工具序列:

```
GMAIL_LIST_LABELS
```
- 列出所有标签以获取ID并检测冲突（必填）
```
GMAIL_CREATE_LABEL
```
- 创建新标签（可选）
```
GMAIL_PATCH_LABEL
```
- 重命名或修改标签颜色/可见性（可选）
```
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. Apply/Remove Labels on Messages

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

When to use: User wants to label, archive, or mark emails as read/unread

Tool sequence:

```
GMAIL_LIST_LABELS
```
- Get label IDs for custom labels [Prerequisite]
```
GMAIL_FETCH_EMAILS
```
- Find target messages [Prerequisite]
```
GMAIL_BATCH_MODIFY_MESSAGES
```
- Bulk add/remove labels (up to 1000 messages) [Required]
```
GMAIL_ADD_LABEL_TO_EMAIL
```
- Single-message label changes [Fallback]

Key parameters:

```
messageIds
```
: Array of message IDs (max 1000)
```
addLabelIds
```
: Array of label IDs to add
```
removeLabelIds
```
: Array of label IDs to remove
```
message_id
```
: 15-16 char hex string for single operations

Pitfalls:

Max 1000 messageIds per BATCH call; chunk larger sets
Use 'CATEGORY_UPDATES' not 'UPDATES'; full prefix required for category labels
SENT, DRAFT, CHAT are immutable — cannot be added/removed
To mark as read: REMOVE 'UNREAD'. To archive: REMOVE 'INBOX'
```
message_id
```
must be 15-16 char hex, NOT UUIDs or web UI IDs

适用场景：用户需要为邮件添加标签、归档或标记为已读/未读

工具序列:

```
GMAIL_LIST_LABELS
```
- 获取自定义标签的ID（前提步骤）
```
GMAIL_FETCH_EMAILS
```
- 找到目标邮件（前提步骤）
```
GMAIL_BATCH_MODIFY_MESSAGES
```
- 批量添加/移除标签（最多1000条邮件）（必填）
```
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. Handle Drafts and Attachments

6. 处理草稿与附件

When to use: User wants to create, edit, or send email drafts, possibly with attachments

Tool sequence:

```
GMAIL_CREATE_EMAIL_DRAFT
```
- Create a new draft [Required]
```
GMAIL_UPDATE_DRAFT
```
- Edit draft content [Optional]
```
GMAIL_LIST_DRAFTS
```
- List existing drafts [Optional]
```
GMAIL_SEND_DRAFT
```
- Send a draft (requires explicit user approval) [Optional]
```
GMAIL_GET_ATTACHMENT
```
- Download attachment from existing message [Optional]

Key parameters:

```
recipient_email
```
: Draft recipient
```
subject
```
: Draft subject (omit for reply drafts to stay in thread)
```
body
```
: Draft content
```
is_html
```
: Set
```
true
```
for HTML content
```
attachment
```
: Object with
```
{s3key, mimetype, name}
```
```
thread_id
```
: For reply drafts (leave subject empty to stay in thread)

Pitfalls:

Response includes
```
data.id
```
(draft_id) AND
```
data.message.id
```
; use
```
data.id
```
for draft operations
Setting subject on a thread reply draft creates a NEW thread instead
Attachment capped at ~25MB; base64 overhead can push near-limit files over
UPDATE_DRAFT replaces entire content, not patches; include all fields you want to keep
HTTP 429 on bulk draft creation; use exponential backoff

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

工具序列:

```
GMAIL_CREATE_EMAIL_DRAFT
```
- 创建新草稿（必填）
```
GMAIL_UPDATE_DRAFT
```
- 编辑草稿内容（可选）
```
GMAIL_LIST_DRAFTS
```
- 列出现有草稿（可选）
```
GMAIL_SEND_DRAFT
```
- 发送草稿（需要用户明确授权）（可选）
```
GMAIL_GET_ATTACHMENT
```
- 从现有邮件中下载附件（可选）

关键参数:

```
recipient_email
```
: 草稿收件人
```
subject
```
: 草稿主题（回复线程的草稿请留空，以保持在原线程内）
```
body
```
: 草稿内容
```
is_html
```
: 若为HTML内容则设为
```
true
```
```
attachment
```
: 包含
```
{s3key, mimetype, name}
```
的对象
```
thread_id
```
: 用于回复线程的草稿（留空subject以保持在原线程内）

注意事项:

响应包含
```
data.id
```
（draft_id）和
```
data.message.id
```
；草稿操作请使用
```
data.id
```
为线程回复草稿设置主题会创建新的线程
附件大小上限约为25MB；base64编码的额外开销可能导致接近上限的文件超出限制
UPDATE_DRAFT会替换整个内容，而非增量修改；请包含所有需要保留的字段
批量创建草稿会触发HTTP 429错误；请使用指数退避策略

Common Patterns

常见模式

ID Resolution

ID解析

Label name → Label ID:

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

Contact name → Email:

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

Thread ID from search:

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

标签名称 → 标签ID:

1. 调用GMAIL_LIST_LABELS
2. 在响应中按名称查找标签
3. 提取id字段（例如'Label_123'）

联系人姓名 → 邮箱:

1. 调用GMAIL_SEARCH_PEOPLE，参数query=contact_name
2. 从响应中提取emailAddresses

从搜索结果获取线程ID:

1. 调用GMAIL_FETCH_EMAILS或GMAIL_LIST_THREADS
2. 提取threadId（15-16位十六进制字符串）

Pagination

分页

Set
```
max_results
```
up to 500 per page
Check response for
```
nextPageToken
```
Pass token as
```
page_token
```
in next request
Continue until
```
nextPageToken
```
is absent or empty string
```
resultSizeEstimate
```
is approximate, not exact

设置
```
max_results
```
为每页最多500条
检查响应中的
```
nextPageToken
```
在下次请求中传递该token作为
```
page_token
```
持续请求直到
```
nextPageToken
```
不存在或为空字符串
```
resultSizeEstimate
```
为近似值，并非精确计数

Gmail Query Syntax

Gmail查询语法

Operators:

```
from:sender@example.com
```
- Emails from sender
```
to:recipient@example.com
```
- Emails to recipient
```
subject:"exact phrase"
```
- Subject contains exact phrase
```
is:unread
```
- Unread messages
```
is:starred
```
- Starred messages
```
is:snoozed
```
- Snoozed messages
```
has:attachment
```
- Has attachments
```
after:2024/01/01
```
- After date (YYYY/MM/DD)
```
before:2024/12/31
```
- Before date
```
label:custom_label
```
- User-created label (use label ID)
```
in:sent
```
- In sent folder
```
category:primary
```
- Primary category

Combinators:

```
AND
```
- Both conditions (default)
```
OR
```
- Either condition
```
NOT
```
- Exclude condition
```
()
```
- Group conditions

Examples:

```
from:boss@company.com is:unread
```
- Unread emails from boss

subject:invoice has:attachment after:2024/01/01

- Invoices with attachments this year

```
(from:alice OR from:bob) is:starred
```
- Starred emails from Alice or Bob

操作符:

```
from:sender@example.com
```
- 来自指定发件人的邮件
```
to:recipient@example.com
```
- 发送给指定收件人的邮件
```
subject:"exact phrase"
```
- 主题包含精确短语的邮件
```
is:unread
```
- 未读邮件
```
is:starred
```
- 已加星标的邮件
```
is:snoozed
```
- 已延后的邮件
```
has:attachment
```
- 包含附件的邮件
```
after:2024/01/01
```
- 指定日期之后的邮件
```
before:2024/12/31
```
- 指定日期之前的邮件
```
label:custom_label
```
- 带有用户创建标签的邮件（需使用标签ID）
```
in:sent
```
- 已发送文件夹中的邮件
```
category:primary
```
- 主要分类的邮件

组合符:

```
AND
```
- 同时满足两个条件（默认逻辑）
```
OR
```
- 满足任一条件
```
NOT
```
- 排除满足条件的邮件
```
()
```
- 分组条件

示例:

```
from:boss@company.com is:unread
```
- 来自老板的未读邮件

subject:invoice has:attachment after:2024/01/01

- 今年以来包含附件的发票邮件

```
(from:alice OR from:bob) is:starred
```
- 来自Alice或Bob的已加星标邮件

Known Pitfalls

已知注意事项

ID Formats:

Custom label operations require label IDs (e.g., 'Label_123'), not display names
Always call LIST_LABELS first to resolve names to IDs
Message IDs are 15-16 char hex strings
Do NOT use UUIDs, web UI IDs, or 'thread-f:' prefixes

Query Syntax:

Use 'is:' for states (unread, snoozed, starred)
Use 'label:' ONLY for user-created labels
System labels use 'is:' or 'in:' (e.g., 'is:sent', 'in:inbox')

Rate Limits:

BATCH_MODIFY_MESSAGES max 1000 messages per call
Heavy use triggers 403/429 rate limits
Implement exponential backoff for bulk operations

Response Parsing:

Response data may be nested under
```
data_preview
```
or
```
data.messages
```
Parse defensively with fallbacks
Timestamp
```
messageTimestamp
```
uses RFC3339 with 'Z' suffix
Normalize to '+00:00' for parsing if needed

Attachments:

Attachment
```
s3key
```
from prior download may expire
Use promptly after retrieval
Mimetype must include '/' separator

ID格式:

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

查询语法:

状态类条件使用'is:'（unread, snoozed, starred）
'label:'仅适用于用户创建的标签
系统标签使用'is:'或'in:'（例如'is:sent', 'in:inbox'）

速率限制:

BATCH_MODIFY_MESSAGES每次调用最多支持1000条消息
高频使用会触发403/429速率限制
批量操作请实现指数退避策略

响应解析:

响应数据可能嵌套在
```
data_preview
```
或
```
data.messages
```
下
请使用防御式解析并设置回退方案
时间戳
```
messageTimestamp
```
采用带'Z'后缀的RFC3339格式
若需要，可将其标准化为'+00:00'后再解析

附件:

来自之前下载操作的附件
```
s3key
```
可能会过期
请在获取后立即使用
Mimetype必须包含'/'分隔符

Quick Reference

快速参考

Task	Tool Slug	Key Params
Send email	GMAIL_SEND_EMAIL	recipient_email, subject, body, is_html
Reply to thread	GMAIL_REPLY_TO_THREAD	thread_id, message_body, recipient_email
Search emails	GMAIL_FETCH_EMAILS	query, max_results, label_ids, page_token
Get message details	GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID	message_id
List labels	GMAIL_LIST_LABELS	(none)
Create label	GMAIL_CREATE_LABEL	label_name, background_color, text_color
Modify labels bulk	GMAIL_BATCH_MODIFY_MESSAGES	messageIds, addLabelIds, removeLabelIds
Create draft	GMAIL_CREATE_EMAIL_DRAFT	recipient_email, subject, body, thread_id
Send draft	GMAIL_SEND_DRAFT	draft_id
Get attachment	GMAIL_GET_ATTACHMENT	message_id, attachment_id
Search contacts	GMAIL_SEARCH_PEOPLE	query
Get profile	GMAIL_GET_PROFILE	(none)

Powered by Composio

任务	工具标识	关键参数
发送邮件	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	无
创建标签	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	无

由Composio提供支持