Macro MCP 的会话与邮件四工具：读会话、发邮件、改标签各要什么参数

把一个 Agent 接到自己的邮箱上，读的部分怎么折腾都还好，真正让人手心出汗的是那一个写操作——它会替你把信发出去，发出去就收不回来。

Macro 的 MCP 工具集里，跟邮件会话相关的正好是四个：GetThread、ReadThread、SendEmail、UpdateThreadLabels。三个读、一个写，边界刚好卡在 SendEmail 上。这篇就按官方工具参考页逐个过一遍参数，顺带说清楚一件事：关于”发信前会不会让你确认”，官方文档到底写了什么、没写什么。

需要先讲明白文档本身的性质。这几页在页头都标了同一句话——“Generated from the Macro Rust tool registry”，也就是从 Macro 的 Rust 工具注册表自动生成的。整页内容只有一个参数表：参数名、类型、是否必填、描述。没有示例调用，没有返回值结构，没有错误码。你能从这几页拿到的确定信息，就是参数层面的这些，别的都得靠自己在沙箱里试。

四个工具的参数一览

先把四张表并成一张，方便对照：

工具	参数	类型	文档标注必填	描述要点
GetThread	threadId	string	是	要取的邮件会话 ID
GetThread	limit	integer	是	返回消息条数上限，默认 10
ReadThread	contentType	string	是	要读的内容类型，按你想取的内容来选
ReadThread	ids	array	是	内容 ID，可多可单，规则见下
ReadThread	messagesSince	string	是	ISO 8601 本地时间，最早纳入的消息，仅对频道生效
SendEmail	to	array	是	主收件人（To）
SendEmail	subject	string	是	主题行
SendEmail	body	string	是	纯文本正文
SendEmail	cc	array	是	抄送（描述里写 optional）
SendEmail	bcc	array	是	密送（描述里写 optional）
SendEmail	replyingToId	string	是	要回复的消息 ID（描述里写 optional），设了就作为同一会话内的回复发出
UpdateThreadLabels	thread_id	string	是	要改的邮件会话 ID
UpdateThreadLabels	label_id	string	是	要加或去掉的标签 ID
UpdateThreadLabels	add	boolean	是	true 是加、false 是去掉

表格拉出来之后，有几处细节值得单独说。

“必填”这一列不能照着信

四页文档的必填列全是 Yes，一个例外都没有。但描述文字里明明白白写着相反的话：cc 是”Carbon copy recipients (optional)“，bcc 是”(optional)“，replyingToId 也是”(optional)“；GetThread 的 limit 描述里带了”default 10”——既然有默认值，通常就意味着可以不传。

这种打架不是文档写错了字，更像是生成脚本把注册表里的字段一律按 required 输出了。落到实际工程上，安全的读法是：描述里带 “(optional)” 或带默认值的，以描述为准；描述没说可选的，按必填处理。 也就是 SendEmail 真正非给不可的是 to、subject、body 三个，GetThread 真正非给不可的是 threadId。

但”安全的读法”仍然只是读法。官方文档没有明说哪些可省，如果你在做参数校验或者写工具封装，最好三个可选参数都显式传空数组／空串跑一遍，看服务端认不认，不要凭这张表下结论。

SendEmail：文档写明的和没写明的

这是四个里唯一有外部副作用的工具，说清楚它的边界比多写几百字介绍更重要。

文档明确写了的：

• 它发的是纯文本正文（body 的描述就是 “The plain text body of the email”）。参数表里没有 HTML 正文字段，也没有附件字段。
• replyingToId 一旦设置，这封信会作为回复发在同一个会话里；不设就是新起一封。
• 收件人分 to / cc / bcc 三组，都是数组。

文档没有写、因此不能替它承诺的：

• 参数表里没有任何形如 confirm、dryRun、draftOnly 的开关。也就是说，从工具签名这一层看不出”发信前会先生成草稿等你点确认”这回事。官方这几页文档没有描述任何发送前确认环节。
• 没有写明是否有发送频率限制、单次收件人数量上限、失败重试行为。
• 没有写明发出的信用哪个身份、哪个已连接的邮箱账号——工具参数里没有 from 或账号选择字段。

这里要拿捏分寸：没写确认机制，不等于产品里一定没有确认机制——工具参数表只描述这一个工具的入参，客户端侧（比如你用的那个 MCP 客户端）完全可能在调用前弹一次确认，很多客户端对写类工具默认就是要人点一下的。反过来也一样，不能因为”应该会确认吧”就默认它安全。可核查的事实只有一条：这个工具的签名里不带确认开关，确认与否取决于调用它的客户端怎么处理写操作。

工程上的做法就跟着这条事实走：把 SendEmail 当成”一调就出去”的接口来设计。如果你的客户端支持按工具名设置需要人工批准，就把它单列出来；如果不支持，那就别把这个工具挂给一个无人值守的定时任务。相比之下另外三个工具（读会话、读内容、改标签）就宽松得多——改标签虽然也是写，但它改的是你自己收件箱里的归类状态，add: false 就能撤回来，损失面完全不同。

ReadThread 的 ids 有一条容易踩的规则

ids 的描述里有一段全大写强调：“channel-message、chat-message 和 content 这三类内容类型支持多个 id；其余类型（channel、chat-thread）只给一个 id。”

这意味着 ids 虽然统一是数组类型，但能不能塞多个取决于 contentType 的取值。写批量拉取逻辑的时候，得按 contentType 分支决定要不要切分成多次调用，不能一律 chunk 成 50 个一批扔进去。

另外两点：contentType 的描述只说”按你想取的内容类型来选”，文档里没有给出完整的枚举值列表，我们能从 ids 的描述反推出来的只有 channel-message、chat-message、content、channel、chat-thread 这五个字符串，是否还有别的取值，这几页没写。messagesSince 要 ISO 8601 格式的本地时间，且描述明说只对频道（channels）生效——读邮件会话时它是个摆设，但必填列又标着 Yes，同样属于上面那类需要自己试的地方。

顺带一提，GetThread 和 ReadThread 的分工也是从参数反推的：前者只认 threadId，是专门取邮件会话的；后者靠 contentType 分流，覆盖频道、聊天、文档等多种内容。两者的返回结构文档都没描述。

UpdateThreadLabels 指向了一个不在列表里的工具

label_id 的描述里有一句很实在的提示：“Use ListLabels to get valid label IDs.”（用 ListLabels 拿到合法的标签 ID。）

但翻回工具参考的总目录页，那份列表里列出的工具是 bash_code_execution、ContentSearch、CreateDocument、GetEntityProperties、GetThread、ListEntities、NameSearch、ReadContent、ReadMetadata、ReadThread、SendEmail、SetEntityProperty、text_editor_code_execution、UpdateThreadLabels、web_fetch、web_search——ListLabels 不在其中，也没有对应的生成页。

这个缺口怎么解释，文档没说。可能是注册表里有而生成脚本漏了页，也可能是描述文字沿用了别处的说法。能确定的只是：你没法从这份文档里查到怎么拿标签 ID。真要用 UpdateThreadLabels，先得解决”label_id 从哪来”这个前置问题——要么客户端连上之后直接看服务端实际暴露了哪些工具（以运行时列表为准，而不是以文档目录为准），要么走实体类工具那条路去列。

接入这一层的权限边界

关于访问控制，MCP 配置页写明的就三件事：端点是

https://mcp-server.macro.com/mcp

服务是远端的，不需要在本地跑进程；鉴权走 Macro 的 OAuth 流程，客户端连接时完成；MCP 访问在 Macro 的所有套餐上都可用，包括免费版。

也就是说，文档层面的权限边界只到”你这个账号登录了没有”。没有任何关于”给 MCP 会话单独限定只读／只允许某几个工具”的说明，也没有工具粒度的授权开关。你的 Agent 一旦完成 OAuth，工具列表里有什么就能调什么，SendEmail 也在其中。连接和登录本身的坑另说，可以看 MCP 连不上：动态客户端注册与鉴权头；整套 MCP 能力的全景在 Macro 的 MCP 服务能做什么。至于产品内部谁能看到什么，那是另一套东西，见 权限模型：谁能看到什么。

什么时候别用这四个工具，以及还剩哪些没解决

不适合的场景：需要发 HTML 富文本或带附件的邮件——参数表里没有这两样；需要指定发信身份或在多个已连账号之间切换——没有 from 字段；需要”生成草稿让人审再发”的人工闸门——工具签名里没有这个开关，只能靠客户端侧自己拦。把 SendEmail 接进无人值守的自动流程之前，这三条得先想清楚。

这几页没有覆盖、需要你自己验的：返回值长什么样（四个工具全都没写）；contentType 的完整取值；三个标着 “(optional)” 的参数到底能不能省；ListLabels 在运行时是否真的存在；GetThread 的 limit 上限是多少（只说了默认 10）。这些都属于连上去 list 一次工具、拿测试账号跑一遍就能确定的事，比在文档里反复找快得多。

内容类工具（读内容、读元数据、建文档）跟这四个是一路的用法，参数读法上的坑也类似，可以接着看 内容类工具：读内容、读元数据、建文档。

延伸阅读

• 从头读起：Macro 是什么：邮件、任务、文档、CRM 共用一个双向数据库的开源工作区
• 本专题共 40 篇，完整分组目录见专题页
• Macro 的 blocks 数据模型：十几类内容共用一份库，到底改变了什么
• Macro 的 @ 提及机制：一个 @ 同时决定引用、通知和访问权限

---

本文依据 Macro 官方仓库（github.com/macro-inc/macro，AGPL-3.0 协议）的 apps/docs/ 产品文档、 MCP 工具参考与自托管说明整理，核对日 2026-08-17。 我们没有注册或运行过 Macro，因此不涉及界面外观与操作手感； 官方标注为计划中的能力文中已如实标明，不代表当前可用。 价格与额度以官网 macro.com 最新页面为准；许可证相关问题请咨询专业人士并以官方许可证原文为准。