文档

四步即可让你的智能体
拥有一个收件箱。

连接任意电子邮件账户，把一个 URL 粘贴到支持 OAuth 的 MCP 客户端中并授权。不支持 OAuth 的客户端则改用 API 密钥。下方提供完整的工具参考和连接指南。

快速开始 OAuth（claude.ai）工具参考服务商支持

快速开始

几分钟内即可上手运行。

无需 SDK。MCPEmails 通过 HTTP 讲标准 MCP，因此可接入任何兼容 MCP 的智能体。

01注册并连接收件箱

创建账户并连接 Gmail

在 mcpemails.com 注册，然后前往仪表盘 → 收件箱 → 连接收件箱。选择 Gmail、iCloud、Fastmail 或任何 IMAP 收件箱，然后完成 OAuth 流程或粘贴一个应用密码。你的收件箱在一分钟内即可就绪。

连接你的收件箱 →

02创建 API 密钥

为你的智能体生成一个 bearer 令牌

在仪表板 → API 密钥中，点击「创建密钥」。为其命名，选择你的智能体所需的范围——read:email、search:email、send:email、manage:folders、delete:email、manage:drafts、manage:contacts 和 schedule:email——并复制该密钥。它只显示一次。

# Your key looks like this:
mcpe_live_AbCdEfGhIjKlMnOpQrStUvWxYz123456

03将 MCPEmails 添加到你的智能体

把 MCP 端点粘贴到你的客户端中

在下方选择你的客户端对应的标签页。支持 OAuth 2.0 的 MCP 客户端（claude.ai、Claude Desktop、Cursor 等）只需粘贴 URL 并授权，无需 API 密钥。不支持 OAuth 的客户端以及脚本化访问，则使用第 02 步中的 API 密钥。

json

# OAuth-capable clients (claude.ai, Claude Desktop, Cursor…)
# No API key required. Paste the URL, click Connect, authorize.
#
# Example: claude.ai
#   1. Go to claude.ai → Customize → Connectors
#   2. Click "Add connector" and paste this URL:
#
#        https://mcpemails.com/api/mcp
#
#   3. Click Connect and sign in with your mcpemails account.
#   4. Every tool your approved scopes allow is live immediately.
#
# Claude Desktop and Cursor follow the same OAuth flow when
# the server URL is configured in their MCP settings.

04发起你的第一次调用

让你的智能体检查你的收件箱

无需复制粘贴收件箱 UUID。你的智能体会先调用 inbox_list 来发现每一个已连接的收件箱及其 UUID，然后你只需说：“检查我的收件箱并总结最近 5 封未读邮件。”

# The agent calls inbox_list first, so no hardcoded UUIDs.
# System prompt (optional, for multi-inbox setups):
You have access to email via MCPEmails.
Start by calling inbox_list to discover available inboxes.

端点

一个 URL，标准 MCP。

所有流量都发往单个 Streamable HTTP 端点。使用来自仪表盘的 bearer 令牌进行身份验证。

POSThttps://mcpemails.com/api/mcp

发送一个 JSON-RPC 2.0 请求体。支持的方法：initialize、tools/list、tools/call。

传输：Streamable HTTP（MCP 2025-06-18）

认证：Authorization: Bearer <api-key>

速率限制：每个密钥 100 次/分钟 · 1,000 次/小时 · 10,000 次/天

响应格式：JSON-RPC 2.0——成功的结果还会携带一个带类型的 structuredContent 对象

初始化握手

bash

curl -X POST https://mcpemails.com/api/mcp \
  -H "Authorization: Bearer mcpe_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "clientInfo": { "name": "my-agent", "version": "1.0" },
      "capabilities": {}
    }
  }'

轮询，而非推送

MCPEmails 仅采用请求/响应模式：每个结果都来自你的智能体发起的工具调用。没有 webhook、推送通知或由服务器发起的事件——收到新邮件本身绝不会触发智能体调用。要对新邮件作出响应，请让你的智能体按计划轮询，例如按工作流所需的间隔调用 email_read 并设置 action: "list" 和 unread_only: true（注意上面的速率限制）。

OAuth 连接

对支持 OAuth 的客户端零配置。

支持 OAuth 2.0 的 MCP 客户端（claude.ai、Claude Desktop、Cursor 等）会通过授权码 + PKCE 自动连接。无需 API 密钥，无需配置文件。粘贴 URL 并点击连接。

第 1 步：前往 claude.ai → 自定义 → 连接器 → 添加连接器

第 2 步：把 https://mcpemails.com/api/mcp 粘贴为服务器 URL

第 3 步：点击连接。MCPEmails 会打开一个授权界面

第 4 步：用你的 mcpemails 账户登录并批准访问

完成：你所批准的权限范围允许的每一个工具均已上线。claude.ai 会自动刷新令牌

底层工作原理

claude.ai 通过 RFC 7591 动态客户端注册自行注册，因此你永远不必预先注册客户端 ID。

授权使用 OAuth 2.0 授权码 + PKCE（RFC 7636），因此从不传输任何客户端密钥。

令牌的范围严格限定为你批准的权限——read:email、search:email、send:email、manage:folders、delete:email、manage:drafts、manage:contacts 和 schedule:email。

使用不支持 OAuth 的客户端？在仪表盘 → API 密钥中创建一个 API 密钥，并将其作为 bearer 令牌传递。API 密钥连接和 OAuth 连接使用同一个 MCP 端点和同样的工具目录。

工具参考

10 个工具。满足你智能体所需的每一项邮件操作。

指定收件箱是可选的。当你的密钥只有一个收件箱时，每个按收件箱的工具都会自动解析它——无需 inbox_id。有多个收件箱时，传入 inbox_id（来自 inbox_list 的 UUID）或 inbox（收件箱的邮箱地址）。大多数工具接受一个 action 参数来选择操作；徽章显示每个工具所需的权限范围，而 tools/list 只返回你的密钥（或 OAuth 令牌）有权限的工具。点击“显示示例”查看完整的请求与响应。

inbox_listread:email email_readread:emailsearch:email email_organizemanage:folderssend:email email_deletedelete:email email_composesend:email folderread:emailmanage:folders draftmanage:drafts scheduleschedule:email contact_searchmanage:contacts signatureread:emailsend:email

inbox_listread:email

返回当前 API 密钥或 OAuth 令牌可访问的所有收件箱。先调用它来发现 inbox_id 值，这样你就无需从仪表板复制粘贴 UUID。每个结果都包含邮箱地址、提供商、可选的服务品牌（icloud/yahoo/zoho/yandex/generic/fastmail），以及描述该收件箱支持哪些功能的 capabilities 对象。

参数	类型	必需	说明
`provider`	enum	可选	可选筛选——只返回由该提供商提供服务的收件箱。可选值之一：gmail、fastmail、imap。省略则列出密钥可访问的所有收件箱。
`include_capabilities`	boolean	可选	每个收件箱是否包含其 capabilities 对象（支持哪些功能）。默认 true；设为 false 可得到仅含 inbox_id、邮箱地址、显示名称、提供商和服务品牌的精简列表。

email_readread:emailsearch:email

在收件箱中读取、列出和搜索邮件。设置 action：'list' 获取最近邮件摘要（最新优先，可按文件夹/未读筛选并分页），'read' 获取单个 message_id 的完整内容（纯文本正文、可选的净化后 HTML 和附件），'read_batch' 在一次调用中获取最多 50 个 message_ids，'search' 进行结构化、与提供商无关的筛选（from、to、cc、subject、body、text、unread、has_attachment、flagged、since、before），或 'attachment' 将单个附件（按 attachment_index 或 filename）下载为 base64 数据——最大 25 MB。只读——从不更改任何内容。'search' 操作也可由更窄的 search:email 权限单独解锁。

参数	类型	必需	说明
`action`	enum	必需	要执行的操作："list"（最近邮件摘要）、"read"（单个 message_id 的完整内容）、"read_batch"（多个 message_ids）、"search"（结构化筛选）或 "attachment"（将单个附件下载为 base64）。决定其他哪些参数适用。
`inbox_id`	string (uuid)	可选	要读取的收件箱的 UUID。可选——当密钥仅有一个收件箱时自动解析；否则传入此项或 inbox。调用 inbox_list 以发现收件箱 ID。
`inbox`	string	可选	要使用的收件箱的邮箱地址，作为 inbox_id 的便捷替代。可选；若已提供 inbox_id 则忽略。
`message_id`	string	可选	要读取的提供商邮件 ID（action 'read' 或 'attachment'），来自先前的 list 或 search。
`message_ids`	array[string]	可选	要读取的提供商邮件 ID（action 'read_batch'），来自先前的 list 或 search。每次调用最多 50 个。
`folder`	string	可选	要列出的文件夹（action 'list'）。默认 "INBOX"。其他值："SENT"、"DRAFTS"、"TRASH"。
`unread_only`	boolean	可选	仅返回未读邮件（action 'list'）。默认 false。
`limit`	integer	可选	要返回的最大结果数（action 'list' 或 'search'）。默认 20，最大 100。
`offset`	integer	可选	从零开始的分页偏移量（action 'list' 或 'search'）。默认 0。
`include_html`	boolean	可选	包含净化后的 HTML 正文（action 'read'/'read_batch'）。默认 false。
`include_attachments`	boolean	可选	包含 base64 附件数据（action 'read'/'read_batch'）。在 'read_batch' 中，10 MB 总额度在调用内所有邮件间共享。默认 false。
`mark_as_read`	boolean	可选	获取后将邮件标记为已读（action 'read'/'read_batch'）。默认 false。
`from`	string	可选	要匹配的发件人（action 'search'）：邮箱地址、显示名称或片段（例如 "alice@example.com" 或 "Alice"）。
`to`	string	可选	要匹配的主收件人（To）（action 'search'）：邮箱地址、显示名称或片段。
`cc`	string	可选	要匹配的抄送人（Cc）（action 'search'）：邮箱地址、显示名称或片段。
`subject`	string	可选	要在主题行中匹配的文本（action 'search'）。多词短语按原样匹配。
`body`	string	可选	要在邮件正文中查找的自由文本（action 'search'）。（在 Gmail 上，这会匹配整封邮件，而不仅是正文。）
`text`	string	可选	要在邮件任意位置匹配的自由文本——标头和正文（action 'search'）。
`unread`	boolean	可选	action 'search'：true = 仅未读邮件；false = 仅已读邮件；省略则两者皆可。
`has_attachment`	boolean	可选	action 'search'：true = 仅含附件的邮件。通用 IMAP 不支持（在那里被忽略）。
`flagged`	boolean	可选	action 'search'：true = 仅已标记/加星的邮件。Outlook/Graph 不支持（在那里被忽略）。
`since`	string (ISO date)	可选	ISO 8601 日期或日期时间（action 'search'）；返回在该时刻当时或之后（>=）收到的邮件。例如 "2026-06-01"。
`before`	string (ISO date)	可选	ISO 8601 日期或日期时间（action 'search'）；返回严格早于（<）该时刻收到的邮件。
`query`	string	可选	提供商原生查询字符串（action 'search'，应急手段）。优先使用上面的结构化字段。在受支持处与它们组合使用；在 Fastmail 上被忽略。
`include_folders`	array	可选	将搜索限制在这些文件夹名称内（action 'search'）。默认：搜索所有文件夹。

email_organizemanage:folderssend:email

移动、复制、标记或归档邮件。设置 action：'move'/'move_batch'（移动到某个 destination_folder_id）、'copy'/'copy_batch'（复制到某个 destination_folder_id，同时保留原件；仅支持 IMAP、Outlook 和 Fastmail）、'flag'（通过 message_ids 上的 flag_action 设置已读/未读/标记）、'archive'（移出收件箱，非破坏性），或 'search_and_move'（应用于匹配某个结构化搜索的每封邮件，避免过期的邮件 ID）。每个操作都需要与之匹配的权限：移动和复制需要 manage:folders，flag/archive 需要 send:email。删除邮件由独立的 email_delete 工具负责。

参数	类型	必需	说明
`action`	enum	必需	要执行的操作："move"、"move_batch"、"copy"、"copy_batch"、"flag"、"archive" 或 "search_and_move"。决定其他哪些参数适用以及需要哪种权限。
`inbox_id`	string (uuid)	可选	拥有这些邮件的收件箱的 UUID。可选——当密钥仅有一个收件箱时自动解析；否则传入此项或 inbox。调用 inbox_list 以获取可用的收件箱 ID。
`inbox`	string	可选	要使用的收件箱的邮箱地址，作为 inbox_id 的便捷替代。可选；若已提供 inbox_id 则忽略。
`message_id`	string	可选	单封邮件操作（move、copy、archive）的提供商邮件 ID，来自先前的 list、read 或 search。
`message_ids`	array[string]	可选	批量操作（move_batch、copy_batch、flag）的提供商邮件 ID。每次调用最多 500 个。
`destination_folder_id`	string	可选	目标文件夹（move、move_batch、copy、copy_batch、search_and_move）：规范别名（inbox、sent、drafts、trash、archive、spam）、文件夹/标签名称（例如 'Receipts'），或来自 folder 的 list 操作的提供商原生文件夹 ID。名称和别名会自动解析。
`flag_action`	enum	可选	对于 action 'flag'：要应用到每封邮件的更改——"read" 或 "unread" 设置已读状态，或 "flag"/"unflag" 添加或移除星标/跟进标记。
`from`	string	可选	要匹配的发件人（search_and_move）：邮箱地址、显示名称或片段。
`to`	string	可选	要匹配的主收件人（To）（search_and_move）：邮箱地址、显示名称或片段。
`cc`	string	可选	要匹配的抄送人（Cc）（search_and_move）：邮箱地址、显示名称或片段。
`subject`	string	可选	要在主题行中匹配的文本（search_and_move）。
`body`	string	可选	要在邮件正文中查找的自由文本（search_and_move）。（在 Gmail 上，这会匹配整封邮件。）
`text`	string	可选	要在邮件任意位置匹配的自由文本——标头和正文（search_and_move）。
`unread`	boolean	可选	搜索操作：true = 仅未读；false = 仅已读；省略则两者皆可。
`has_attachment`	boolean	可选	搜索操作：true = 仅含附件的邮件。通用 IMAP 不支持（在那里被忽略）。
`flagged`	boolean	可选	搜索操作：true = 仅已标记/加星的邮件。Outlook/Graph 不支持（在那里被忽略）。
`since`	string (ISO date)	可选	ISO 8601 日期或日期时间（搜索操作）；匹配在该时刻当时或之后（>=）收到的邮件。
`before`	string (ISO date)	可选	ISO 8601 日期或日期时间（搜索操作）；匹配严格早于（<）该时刻收到的邮件。
`query`	string	可选	提供商原生查询字符串（搜索操作，应急手段）。优先使用上面的结构化字段。在 Fastmail 上被忽略。
`include_folders`	array	可选	将搜索限制在这些文件夹名称内（搜索操作）。默认：所有文件夹。
`limit`	integer	可选	对于 search_and_move：要处理的最大匹配数。默认 500，最大 500。

email_deletedelete:email

删除邮件——独立工具，与 email_organize 分开，因为删除是破坏性操作。设置 action：'delete'/'delete_batch'（默认进回收站，或永久删除），或 'search_and_delete'（删除匹配某个结构化搜索的每封邮件——避免过期的邮件 ID）。删除默认进回收站，除非你传入 permanent: true，那将不可逆。每个操作都需要 delete:email 权限，整个工具都会向你的 MCP 客户端标记为破坏性操作，在删除任何内容之前由客户端处理用户确认。

参数	类型	必需	说明
`action`	enum	必需	要执行的操作："delete"、"delete_batch" 或 "search_and_delete"。决定其他哪些参数适用。
`inbox_id`	string (uuid)	可选	拥有这些邮件的收件箱的 UUID。可选——当密钥仅有一个收件箱时自动解析；否则传入此项或 inbox。调用 inbox_list 以获取可用的收件箱 ID。
`inbox`	string	可选	要使用的收件箱的邮箱地址，作为 inbox_id 的便捷替代。可选；若已提供 inbox_id 则忽略。
`message_id`	string	可选	单封删除（action 'delete'）的提供商邮件 ID，来自先前的 list、read 或 search。
`message_ids`	array[string]	可选	批量删除（action 'delete_batch'）的提供商邮件 ID。每次调用最多 500 个。
`permanent`	boolean	可选	为 true 时永久删除（绕过回收站；可能不可逆）；为 false 或省略时移至回收站。永久删除在 IMAP 和 Fastmail 上可用；Gmail 和 Outlook 仅支持回收站。默认 false。
`from`	string	可选	要匹配的发件人（search_and_delete）：邮箱地址、显示名称或片段。
`to`	string	可选	要匹配的主收件人（To）（search_and_delete）：邮箱地址、显示名称或片段。
`cc`	string	可选	要匹配的抄送人（Cc）（search_and_delete）：邮箱地址、显示名称或片段。
`subject`	string	可选	要在主题行中匹配的文本（search_and_delete）。
`body`	string	可选	要在邮件正文中查找的自由文本（search_and_delete）。（在 Gmail 上，这会匹配整封邮件。）
`text`	string	可选	要在邮件任意位置匹配的自由文本——标头和正文（search_and_delete）。
`unread`	boolean	可选	搜索操作：true = 仅未读；false = 仅已读；省略则两者皆可。
`has_attachment`	boolean	可选	搜索操作：true = 仅含附件的邮件。通用 IMAP 不支持（在那里被忽略）。
`flagged`	boolean	可选	搜索操作：true = 仅已标记/加星的邮件。Outlook/Graph 不支持（在那里被忽略）。
`since`	string (ISO date)	可选	ISO 8601 日期或日期时间（搜索操作）；匹配在该时刻当时或之后（>=）收到的邮件。
`before`	string (ISO date)	可选	ISO 8601 日期或日期时间（搜索操作）；匹配严格早于（<）该时刻收到的邮件。
`query`	string	可选	提供商原生查询字符串（搜索操作，应急手段）。优先使用上面的结构化字段。在 Fastmail 上被忽略。
`include_folders`	array	可选	将搜索限制在这些文件夹名称内（搜索操作）。默认：所有文件夹。
`limit`	integer	可选	对于 search_and_delete：要处理的最大匹配数。默认 500，最大 500。

email_composesend:email

发送新邮件或回复现有邮件。设置 action：'send' 发送新邮件（to/subject/body，可选 cc/bcc/html_body/reply_to/attachments）、'reply' 回复某个 message_id（线程标头自动设置；可选 reply_all），或 'forward' 将某个 message_id 转发给新收件人（可选择重新附加原始文件）。收件箱的签名会自动追加——在回复和转发时，它位于你的文本之后、引用块之前，由签名的回复模式控制；传入 include_signature: false 可在单封简短邮件中抑制它。三者一经发送均不可撤销。

参数	类型	必需	说明
`action`	enum	必需	要执行的操作："send"、"reply" 或 "forward"。决定其他哪些参数适用。
`inbox_id`	string (uuid)	可选	要从中发送的收件箱的 UUID。可选——当密钥仅有一个收件箱时自动解析；否则传入此项或 inbox。调用 inbox_list 以获取可用的收件箱 ID。
`inbox`	string	可选	要使用的收件箱的邮箱地址，作为 inbox_id 的便捷替代。可选；若已提供 inbox_id 则忽略。
`message_id`	string	可选	原始邮件的提供商邮件 ID（action 'reply' 或 'forward'），来自先前的 list、read 或 search。
`to`	array[string]	可选	收件人邮箱地址（'send' 和 'forward' 必填）。最多 50 个。
`subject`	string	可选	邮件主题行（action 'send'）。最多 998 个字符。在 reply/forward 时由原邮件派生。
`body`	string	可选	纯文本正文。对于 'reply' 是你的回复内容；对于 'forward' 是置于转发邮件上方的可选备注。
`cc`	array[string]	可选	抄送收件人（send、forward）。默认 []。
`bcc`	array[string]	可选	密送收件人（send、forward）。默认 []。
`html_body`	string	可选	正文的 HTML 版本（multipart/alternative）。调用方负责确保 HTML 安全。
`reply_to`	string	可选	Reply-To 标头地址（action 'send'）。
`reply_all`	boolean	可选	回复所有原始收件人——To + Cc（action 'reply'）。默认 false。
`include_attachments`	boolean	可选	重新附加原始邮件的附件（action 'forward'）。超出 10 MB 额度的文件将被省略。默认 false。
`include_signature`	boolean	可选	是否将收件箱已配置的签名追加到这封邮件。默认 true；设为 false 可发送这一封不带签名的邮件。
`attachments`	array	可选	文件附件。每项：{ filename、mime_type、data（base64）}。最多 20 项，共 10 MB。

folderread:emailmanage:folders

管理邮箱文件夹（在 Gmail 上为标签）。设置 action：'list'（每个文件夹及其提供商原生 ID、显示名称、类型和邮件计数——列出邮件时将这些 ID 用作 folder 参数，并用作移动目标）、'create'（name）、'rename'（folder_id、new_name），或 'delete'（folder_id——不可逆；其中的邮件可能因提供商而丢失）。'list' 需要 read:email；create/rename/delete 需要 manage:folders，且 delete 会向你的 MCP 客户端标记为破坏性操作。

参数	类型	必需	说明
`action`	enum	必需	要执行的操作："list"、"create"、"rename" 或 "delete"。决定其他哪些参数适用以及需要哪种权限。
`inbox_id`	string (uuid)	可选	要管理其文件夹的收件箱的 UUID。可选——当密钥仅有一个收件箱时自动解析；否则传入此项或 inbox。调用 inbox_list 以获取可用的收件箱 ID。
`inbox`	string	可选	要使用的收件箱的邮箱地址，作为 inbox_id 的便捷替代。可选；若已提供 inbox_id 则忽略。
`name`	string	可选	新文件夹或标签的名称（action 'create'）。1–255 个字符。
`folder_id`	string	可选	提供商原生的文件夹/标签 ID（action 'rename' 或 'delete'），来自 folder 的 list 操作。
`new_name`	string	可选	新的显示名称（action 'rename'）。1–255 个字符。

draftmanage:drafts

管理收件箱 Drafts 文件夹中的草稿。设置 action：'list'（已保存的草稿，每个都含 draft_id、主题、收件人和创建时间）、'create'（subject/body 必填，可选 to/cc/bcc/html_body）、'update'（draft_id 加上要覆盖的字段），或 'send'（draft_id——移除草稿并发送，不可逆）。收件箱的签名会在草稿创建或更新时嵌入，因此它已经存在于 Drafts 文件夹中，发送时不会再次追加；传入 include_signature: false 可创建不带签名的草稿。在基于 IMAP 的收件箱上，draft_id 在每次更新后都会改变，因此始终使用最新的；Gmail 和 Outlook 保持 draft_id 稳定。

参数	类型	必需	说明
`action`	enum	必需	要执行的操作："list"、"create"、"update" 或 "send"。决定其他哪些参数适用。
`inbox_id`	string (uuid)	可选	拥有这些草稿的收件箱的 UUID。可选——当密钥仅有一个收件箱时自动解析；否则传入此项或 inbox。调用 inbox_list 以获取可用的收件箱 ID。
`inbox`	string	可选	要使用的收件箱的邮箱地址，作为 inbox_id 的便捷替代。可选；若已提供 inbox_id 则忽略。
`draft_id`	string	可选	提供商草稿 ID（action 'update' 或 'send'），来自最近的 create、update 或 list 操作。在 IMAP 收件箱上，它在每次更新后都会改变，因此始终使用最新的。
`subject`	string	可选	草稿主题行（action 'create'/'update'）。
`body`	string	可选	草稿的纯文本正文（action 'create'/'update'）。
`to`	array[string]	可选	收件人地址（action 'create'/'update'）。默认 []。
`cc`	array[string]	可选	抄送收件人（action 'create'/'update'）。默认 []。
`bcc`	array[string]	可选	密送收件人（action 'create'/'update'）。默认 []。
`html_body`	string	可选	可选的 HTML 正文（action 'create'/'update'）。
`include_signature`	boolean	可选	是否在草稿中嵌入收件箱已配置的签名（action 'create'/'update'）。默认 true；设为 false 可保存不带签名的草稿。
`limit`	integer	可选	要返回的最大草稿数（action 'list'）。默认 20，最大 50。

scheduleschedule:email

通过服务器端队列安排邮件在未来发送。设置 action：'create'（to/subject/body 加上 ISO 8601 格式的 send_at 时间戳——收件人和正文会立即校验，无效的发送不会入队）、'list'（待发送的定时任务，最近的优先，可按收件箱筛选），或 'cancel'（scheduled_send_id——只能取消仍为 'pending' 的发送）。调度器每分钟运行一次，因此实际投递可能在 send_at 之后最多 60 秒。

参数	类型	必需	说明
`action`	enum	必需	要执行的操作："create"、"list" 或 "cancel"。决定其他哪些参数适用。
`inbox_id`	string (uuid)	可选	要从中发送（action 'create'）或用于筛选（action 'list'）的收件箱的 UUID。可选——当密钥仅有一个收件箱时自动解析；否则传入此项或 inbox。调用 inbox_list 以获取可用的收件箱 ID。
`inbox`	string	可选	要使用的收件箱的邮箱地址，作为 inbox_id 的便捷替代。可选；若已提供 inbox_id 则忽略。
`to`	array[string]	可选	收件人邮箱地址（action 'create'）。最多 50 个。
`subject`	string	可选	邮件主题行（action 'create'）。最多 998 个字符。
`body`	string	可选	邮件的纯文本正文（action 'create'）。
`send_at`	string (ISO 8601)	可选	带时区的 ISO 8601 日期时间，指定发送时刻（action 'create'）。必须是将来时间，例如 "2026-06-02T09:00:00Z"。
`cc`	array[string]	可选	抄送收件人（action 'create'）。默认 []。
`bcc`	array[string]	可选	密送收件人（action 'create'）。默认 []。
`html_body`	string	可选	正文的可选 HTML 版本（action 'create'）。
`reply_to`	string	可选	可选的 Reply-To 标头地址（action 'create'）。
`attachments`	array	可选	文件附件（action 'create'）。与 send 操作的结构相同。最多 20 项，共 10 MB。
`scheduled_send_id`	string (uuid)	可选	要取消的定时发送的 UUID（action 'cancel'）。
`limit`	integer	可选	最大结果数（action 'list'）。默认 20，最大 100。

contact_searchmanage:contacts

通过对你邮箱的实时扫描按姓名或邮箱查找通信人——没有存储的联系人列表。每次调用都会扫描最近的一段匹配邮件窗口，并返回匹配的人员，按最近联系排序，每个都含显示名称、邮箱、匹配邮件数量和最后联系时间戳。计数反映该窗口内的匹配邮件，而非你的完整历史，且调用之间不存储任何内容。

参数	类型	必需	说明
`query`	string	必需	姓名或邮箱片段，对显示名称和地址进行不区分大小写的匹配。至少 1 个字符。
`inbox_id`	string (uuid)	可选	可选。将实时扫描限制在一个收件箱。省略则扫描密钥可访问的收件箱（数量有限）。
`inbox`	string	可选	要限制到的收件箱的邮箱地址，作为 inbox_id 的便捷替代。可选；若已提供 inbox_id 则忽略。
`limit`	integer	可选	要返回的最大联系人数。默认 20，最大 50。

signatureread:emailsend:email

读取或配置收件箱的电子邮件签名，该签名会在每次发送、回复、转发、草稿和定时邮件时由服务器端追加。设置 action：'get'（返回当前签名的文本和 HTML、是否启用、回复/转发模式，以及其来源——'manual'、'gmail_import' 或 null），或 'set'（写入 signature_text 和/或 signature_html，以及可选的 signature_enabled 和 signature_reply_mode）。签名支持富文本 HTML：粗体、斜体、标题、列表、颜色、对齐、链接，以及以 https URL 引用的托管徽标/图片，因此代理可以通过传入 signature_html 设置完整格式化的签名。仪表盘中也提供相同的富文本编辑器。设置签名会将其来源标记为 'manual'，这将永久覆盖该收件箱的 Gmail 自动导入。'get' 需要 read:email；'set' 需要 send:email。

参数	类型	必需	说明
`action`	enum	必需	要执行的操作："get"（读取当前签名）或 "set"（写入签名）。决定其他哪些参数适用以及需要哪种权限。
`inbox_id`	string (uuid)	可选	要读取或设置其签名的收件箱的 UUID。可选——当密钥仅有一个收件箱时自动解析；否则传入此项或 inbox。调用 inbox_list 以获取可用的收件箱 ID。
`inbox`	string	可选	要使用的收件箱的邮箱地址，作为 inbox_id 的便捷替代。可选；若已提供 inbox_id 则忽略。
`signature_text`	string	可选	纯文本签名正文（action 'set'）。省略则保持不变；传入空字符串可清除它。若仅提供文本，发送时会自动派生出 HTML 版本。
`signature_html`	string	可选	可选的富文本 HTML 签名正文（action 'set'）。支持格式（粗体、斜体、下划线、标题、列表、颜色、对齐、链接）以及通过 src 为 https URL 的 <img> 标签引用的托管图片（不支持 base64 或 CID）；保存时会进行净化。省略则保持不变；传入空字符串可清除它。
`signature_enabled`	boolean	可选	签名是否追加到外发邮件（action 'set'）。默认 true；设为 false 可在不删除文本的情况下停止追加。
`signature_reply_mode`	enum	可选	何时在回复和转发中包含签名（action 'set'）："always"（每次回复/转发）、"first_only"（默认——仅线程中的第一封邮件，避免重复署名）或 "never"。

错误代码

错误代码与重试指南。

认证、权限范围和速率限制失败会返回一个带有数字代码的 JSON-RPC error 对象。工具执行失败（收件箱未找到、服务商错误等）会返回一个正常的 result，其中 isError: true，并在 content[0].text 中提供人类可读的消息。

代码	类型	发生时机	可重试
`-32001`	JSON-RPC error	API 密钥缺失、格式错误、已撤销或已过期。当 API 密钥缺少所调用工具所需的权限范围时也会返回。	否
`-32601`	JSON-RPC error	未知的 JSON-RPC 方法（例如调用 initialize、tools/list、tools/call 以外的方法）	否
`-32602`	JSON-RPC error	未知的工具名称，或 tools/call 中缺少 / 无效的参数	否
`-32029`	JSON-RPC error	超出每密钥速率限制或套餐每日配额。检查 data.error_code："rate_limit_exceeded" 还是 "quota_exceeded"。重试前检查 data.retry_after（秒）。
`isError: true`	Tool result	工具已执行但遇到错误（收件箱未找到、邮件未找到、服务商认证失败、收件人无效、附件过大、服务商 5xx）。错误描述在 content[0].text 中。	否

执行错误响应示例

json

// Tool execution error: inbox not found
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "Inbox not found or not accessible." }],
    "isError": true
  }
}

// Rate limit error: JSON-RPC error object with data
{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32029,
    "message": "Rate limit exceeded",
    "data": {
      "error_code": "rate_limit_exceeded",
      "window": "per_minute",
      "limit": 100,
      "used": 100,
      "retry_after": 34
    }
  }
}

速率限制

速率限制与配额。

每密钥滚动窗口

100 次/分钟 · 1,000 次/小时 · 10,000 次/天

无论套餐如何，均按每个 API 密钥强制执行。超出时，服务器返回错误代码 -32029，并附带 data.error_code: "rate_limit_exceeded" 和一个 data.retry_after 字段（秒）。重试前请遵守该值。

套餐每分钟上限

免费 60 次/分钟 · Solo 300 次/分钟 · Team 1,000 次/分钟

用量是无限量的；这是一个每工作区的合理使用突发限制（在你所有 API 密钥间汇总）。超出时，调用会返回 data.error_code: "rate_limit_exceeded"，并附带 data.window: "per_minute" 和一个 data.retry_after 倒计时（秒）。升级你的套餐可获得更高的上限。

安全重试

始终遵守 retry_after；切勿盲目重试发送

对于 rate_limit_exceeded 错误，请在重试前等待 data.retry_after 秒。对于 provider_error 请使用指数退避。请勿在 provider_error 时自动重试 email_compose 发送，因为该邮件可能已被服务商接受。

准备好连接你的收件箱了吗？

从免费套餐开始：无限量，无需信用卡。升级到 Solo 或 Team 可获得更高的突发限额和团队功能。

免费开始使用查看价格

四步即可让你的智能体拥有一个收件箱。