AutoGPT Platform AgentMail 消息块详解：邮件发送、接收、回复、转发与标签状态管理

本文以 AutoGPT Platform 的 AgentMail Messages 文档为主体，完整讲解 6 个消息块（发送、列表、获取、回复、转发、更新标签）的输入输出参数、校验规则与典型用法，并结合 messages.py 与 _config.py 源码揭示凭证管理、计费与错误处理的实际实现，帮助你在 Agent 工作流中构建可轮询、可去重、可多轮对话的自动化邮件系统。

1. 什么是 Message，六块功能总览

在 AgentMail 的数据模型中，Thread（线程）是一次会话，Message（消息）是线程内的一封独立邮件。Messages 文档覆盖的就是对这封"单封邮件"的全部操作能力：

块	文档标题	源码类	块 ID	敏感操作
发送邮件	Agent Mail Send Message	AgentMailSendMessageBlock	b67469b2-7748-4d81-a223-4ebd332cca89	是
列出消息	Agent Mail List Messages	AgentMailListMessagesBlock	721234df-c7a2-4927-b205-744badbd5844	否
获取单条	Agent Mail Get Message	AgentMailGetMessageBlock	2788bdfa-1527-4603-a5e4-a455c05c032f	否
回复邮件	Agent Mail Reply To Message	AgentMailReplyToMessageBlock	b9fe53fa-5026-4547-9570-b54ccb487229	是
转发邮件	Agent Mail Forward Message	AgentMailForwardMessageBlock	b70c7e33-5d66-4f8e-897f-ac73a7bfce82	是
更新标签	Agent Mail Update Message	AgentMailUpdateMessageBlock	694ff816-4c89-4a5e-a552-8c31be187735	否

1.1 凭证与计费前提

所有消息块都通过 credentials 输入引用一个 AgentMail API Key（提供方为 agent_mail）。从源码结构看，凭证有两种获取路径：

1. 手动凭证：在凭证管理中自行创建 AGENTMAIL_API_KEY。_config.py 中的 ProviderBuilder("agent_mail").with_api_key("AGENTMAIL_API_KEY", "AgentMail API Key") 定义了该凭证字段，运行时由 _client() 用密钥构造 AsyncAgentMail 异步客户端（pyproject.toml 中依赖 agentmail = "^0.4.5"）。
2. 托管凭证：当平台侧配置了组织级密钥（settings.py 中的 agentmail_api_key 字段）时，agentmail.py 中的 AgentMailManagedProvider 会为每个用户自动创建一个 Pod 并签发 Pod 级 API Key，标记为 is_managed=True 后自动出现在块的凭证下拉框中，无需用户手动配置。

计费方面，_config.py 中的注释说明了现状：AgentMail 目前处于 beta 阶段且未公布正式计价，因此平台为这批块设置了 1 credit/次运行 的保守底价（with_base_cost(1, BlockCostType.RUN)），避免 AgentMail 的工作量绕过计费体系。

另外，发送、回复、转发这三个会"对外发出邮件"的块在源码中均标记了 is_sensitive_action=True，意味着执行时会被平台当作敏感动作对待；而列表、获取、更新标签属于只读或站内状态操作，不做此标记。

2. 发送新邮件（Agent Mail Send Message）

2.1 功能与工作机制

从指定邮箱（Inbox）发出一封新邮件，自动创建一个新会话线程。支持纯文本 + HTML 双正文、CC/BCC 收件人，以及用于出站邮件追踪的标签。

从源码看，run() 的执行顺序为：

1. 收件人总量校验：to + cc + bcc 合计不得超过 50 人，否则抛出 ValueError: Max 50 combined recipients across to, cc, and bcc (got N)（messages.py）。
2. 按需组装参数：html、cc、bcc、labels 仅在非空时才加入请求参数，避免向 API 传空字段。
3. 调用 client.inboxes.messages.send(inbox_id, **params)，随后输出 message_id、thread_id（为空时输出空串）和完整的 model_dump() 结果对象。

2.2 输入参数

输入	说明	类型	必填	源码细节
inbox_id	发件邮箱 ID 或地址（如 '[e-mail]'）	str	是	—
to	收件人地址列表（如 ['[e-mail]']）	List[str]	是	—
subject	邮件主题	str	是	—
text	纯文本正文。始终提供，作为不渲染 HTML 的邮件客户端的兜底	str	是	—
html	HTML 富文本正文。兼容性最佳的做法是把 CSS 内嵌在 <style> 标签中	str	否	默认空串，标记为 advanced（高级选项）
cc	CC 收件人，用于人类监督（human-in-the-loop）	List[str]	否	默认空列表，advanced
bcc	BCC 收件人（对其他收件人隐藏）	List[str]	否	默认空列表，advanced
labels	标签，用于过滤与状态管理（如 ['outreach', 'q4-campaign']）	List[str]	否	默认空列表，advanced

2.3 输出参数

输出	说明	类型
error	操作失败时的错误信息	str
message_id	已发送邮件的唯一标识	str
thread_id	归组本邮件及其后续回复的线程 ID	str
result	包含全部元数据的完整邮件对象	Dict[str, Any]

2.4 典型用例

• 外联营销活动（Outreach Campaigns）：向潜客列表发送个性化冷邮件，附带活动标签用于追踪，HTML 模板保证专业排版。
• 告警通知（Alert Notifications）：监控指标越界时自动发告警邮件，CC 人类操作员以实现监督。
• 报表投递（Report Delivery）：定期向利益相关方发送汇总报表，BCC 到归档邮箱留档。

3. 列出邮箱中的消息（Agent Mail List Messages）

3.1 功能与工作机制

分页列出指定邮箱中的消息，支持按标签过滤——这是"轮询收件箱"类工作流的入口。labels 过滤的语义是 AND 匹配：只返回同时拥有所给全部标签的消息（如 ['q4-campaign', 'follow-up']）。

从源码看（messages.py），分页参数 page_token 与 labels 同样按需附加；输出的 count 有一个兜底逻辑：优先取 API 返回的 response.count，若为 None 则退化为当前页 len(messages)。当 next_page_token 为空串时表示已无更多结果，循环翻页即可终止。

3.2 输入参数

输入	说明	类型	必填	源码细节
inbox_id	要列出消息的邮箱 ID 或地址	str	是	—
limit	每页返回的最大消息数（1-100）	int	否	默认 20，advanced 选项
page_token	上一次响应返回的翻页令牌	str	否	默认空串
labels	仅返回同时具备所有这些标签的消息（如 ['unread'] 或 ['q4-campaign', 'follow-up']）	List[str]	否	默认空列表

3.3 输出参数

输出	说明	类型
error	操作失败时的错误信息	str
messages	消息对象列表（含主题、发件人、text、html、labels 等）	List[Dict[str, Any]]
count	本页返回的消息数量	int
next_page_token	下一页令牌；无更多结果时为空	str

3.4 典型用例

• 收件箱轮询（Inbox Polling）：定期列出标记为 unread 的消息，触发对新邮件的自动化处理。
• 活动监控（Campaign Monitoring）：按活动专属标签过滤消息，追踪外联序列的回复率与参与度。
• 批处理（Batch Processing）：翻页遍历整个邮箱，执行摘要、归档、数据抽取等批量操作。

4. 获取单条消息（Agent Mail Get Message）

4.1 功能与工作机制

通过 inbox_id + message_id 从 AgentMail 拉取单封邮件，返回主题、纯文本正文、HTML 正文及全部元数据。

本块最有价值的输出是 extracted_text：它只包含"新增回复内容"，已剥离引用历史（quoted history）。相比 text（可能包含整段邮件往来的引用文本），把 extracted_text 喂给 LLM 可以显著减少冗余上下文、降低 token 消耗，是多轮邮件对话中"读取上一封"的标准做法。

从源码看，块对 thread_id、subject、text、extracted_text、html 均做了 or "" 的空值兜底（messages.py），保证 API 未返回某字段时输出仍是稳定的空字符串而非失败。

4.2 输入参数

输入	说明	类型	必填
inbox_id	消息所属的邮箱 ID 或地址	str	是
message_id	要获取的消息 ID（如 '[e-mail]'）	str	是

4.3 输出参数

输出	说明	类型
error	操作失败时的错误信息	str
message_id	消息唯一标识	str
thread_id	消息所属线程	str
subject	邮件主题	str
text	完整纯文本正文（可能包含引用的回复历史）	str
extracted_text	仅新增回复内容，已剥离引用历史，最适合 AI 处理	str
html	邮件 HTML 正文	str
result	完整消息对象（含发件人、收件人、附件、标签等全部字段）	Dict[str, Any]

4.4 典型用例

• 意图分类（Intent Classification）：取消息的 extracted_text 交给 LLM 分类发件人意图，再路由到对应工作流。
• 会话上下文加载（Conversation Context Loading）：在多轮邮件对话中拉取特定消息，为生成上下文相关的回复构建依据。
• 附件处理（Attachment Processing）：读取 result 中的完整元数据，提取附件 URL 供下游文档解析或图像分析。

5. 回复邮件（Agent Mail Reply To Message）

5.1 功能与工作机制

对现有消息进行回复，API 会自动把回复挂到原消息所在的同一线程，无需手动维护 thread 关联——这是构建多轮 Agent 邮件对话的核心机制。

从源码看（messages.py），块总是传 text，仅在 html 非空时附加 HTML 正文；成功后输出新回复的 message_id、所在 thread_id 与完整消息对象。由于标记为敏感操作，执行前会受到平台的敏感动作管控。

5.2 输入参数

输入	说明	类型	必填	源码细节
inbox_id	发出回复的邮箱 ID 或地址	str	是	—
message_id	要回复的消息 ID（如 '[e-mail]'）	str	是	—
text	回复的纯文本正文	str	是	—
html	回复的 HTML 富文本正文	str	否	默认空串，advanced

5.3 输出参数

输出	说明	类型
error	操作失败时的错误信息	str
message_id	回复消息的唯一标识	str
thread_id	回复被加入的线程 ID	str
result	包含全部元数据的完整回复消息对象	Dict[str, Any]

5.4 典型用例

• 客服 Agent（Customer Support Agent）：基于消息内容与知识库，用 LLM 生成答案并自动回复支持类邮件。
• 面试安排（Interview Scheduling）：查完日历可用时间后，回复候选人邮件给出候选面试时间。
• 会话式工作流（Conversational Workflow）：与用户保持持续的邮件往返，每一轮回复都基于上一轮交互推进多步骤任务。

6. 转发邮件（Agent Mail Forward Message）

6.1 功能与工作机制

把指定消息转发给一个或多个新收件人，支持 CC/BCC，可选主题覆盖或附加前置文本。与 Send 块相同，to + cc + bcc 合计上限为 50 人（messages.py）。

不传 subject 时，API 默认使用 'Fwd: <原主题>'；text 与 html 是追加在原转发内容之前的附加内容，而非替换原正文——原邮件内容由 API 在构造转发邮件时自动包含。

6.2 输入参数

输入	说明	类型	必填	源码细节
inbox_id	转发来源的邮箱 ID 或地址	str	是	—
message_id	要转发的消息 ID	str	是	—
to	转发目标收件人（如 ['[e-mail]']）	List[str]	是	—
cc	CC 收件人	List[str]	否	默认空列表，advanced
bcc	BCC 收件人（对其他收件人隐藏）	List[str]	否	默认空列表，advanced
subject	覆盖主题行（默认为 'Fwd: <原主题>'）	str	否	默认空串
text	附加在转发内容之前的纯文本	str	否	默认空串
html	附加在转发内容之前的 HTML	str	否	默认空串

6.3 输出参数

输出	说明	类型
error	操作失败时的错误信息	str
message_id	转发消息的唯一标识	str
thread_id	转发所在线程 ID	str
result	包含全部元数据的完整转发消息对象	Dict[str, Any]

6.4 典型用例

• 升级路由（Escalation Routing）：把匹配特定关键词或优先级级别的消息转发给人类主管邮箱复核。
• 多 Agent 协作（Multi-Agent Collaboration）：把收到的请求转发给专职 Agent 的邮箱，让正确的 Agent 处理对应任务。
• 摘要分发（Digest Distribution）：把聚合邮箱中的每日摘要报告转发给干系人分发列表。

7. 更新消息标签（Agent Mail Update Message）

7.1 功能与工作机制

对指定消息增删标签，用于读/未读跟踪、活动打标与流水线状态管理。标签是自由定义的字符串，可表示"已处理"、"情感已分析"、"高优先级"等任意状态。

从源码看，本块有一条文档表格未体现的前置校验：add_labels 与 remove_labels 不能同时为空，否则直接报错 Must specify at least one label operation: add_labels or remove_labels（messages.py）——空更新请求会在本地被拦截，不会到达 API。成功后返回更新后的 message_id 与携带当前标签状态的完整消息对象。

7.2 输入参数

输入	说明	类型	必填	源码细节
inbox_id	消息所属的邮箱 ID 或地址	str	是	—
message_id	要更新标签的消息 ID	str	是	—
add_labels	要添加的标签（如 ['read', 'processed', 'high-priority']）	List[str]	否	默认空列表；与 remove_labels 至少填一项
remove_labels	要移除的标签（如 ['unread', 'pending']）	List[str]	否	默认空列表；与 add_labels 至少填一项

7.3 输出参数

输出	说明	类型
error	操作失败时的错误信息	str
message_id	更新后的消息 ID	str
result	携带当前标签状态的完整更新消息对象	Dict[str, Any]

7.4 典型用例

• 读/未读跟踪（Read/Unread Tracking）：Agent 处理完消息后移除 unread、添加 read，防止下一轮轮询重复处理。
• 流水线状态管理（Pipeline State Management）：消息在多级处理中流转时依次打上 sentiment-analyzed、response-drafted 等标签，让每个阶段清楚哪些消息还有待办。
• 优先级打标（Priority Tagging）：为 VIP 发件人或含紧急关键词的消息添加 high-priority，让下游块优先过滤处理。

8. 错误处理与组合工作流

8.1 错误处理的实际行为

虽然各块在文档中都声明了 error 输出，源码层面值得确认的是：每个块的 run() 都把"校验 + API 调用 + 结果解析"整体包在 try/except 中，异常（包括收件人超限的 ValueError、API 抛出的错误、以及更新块的空操作校验）统一被捕获并以 yield "error", str(e) 的形式输出。因此在工作流中，判断操作成败应以 error 输出是否为空为准，失败时不会中断整个图执行。

8.2 去重轮询模式（List → Get → Update）

标签机制让"新邮件处理一次且仅一次"变得可靠，推荐组合如下：

1. List Messages：labels=['unread'] 周期性拉取未处理消息（配合 limit 控制批量大小）；
2. Get Message：对每封消息取 extracted_text 作为 LLM 输入，完成分类、摘要或答复生成；
3. Update Message：add_labels=['read', 'processed'] + remove_labels=['unread']，一次性完成状态迁移；
4. 需要对外答复时用 Reply To Message 保持线程连续；需要人工介入或转交时用 Forward Message 升级。

8.3 多轮客服对话

List（unread 过滤）→ Get（extracted_text 供 LLM 生成答复）→ Reply（自动回挂原线程）→ Update（打 response-sent 标签），四步即可闭环一封支持类邮件的处理，且全程无需手动拼接 thread 信息。

8.4 开发自测

每个块在源码中都内嵌了 test_credentials、test_input、test_output 与 test_mock（例如 Send 块的 mock 返回 mock-msg-id / mock-thread-id），可在不消耗真实 AgentMail 配额的 mock 凭证下运行单元级测试，验证块的输入输出契约。

9. 参考资料

• 本文对应文档：Agent Mail Messages
• 消息块实现：messages.py
• 共享凭证与计费配置：_config.py
• 托管凭证提供方：agentmail.py
• 同系列文档：Inbox、Threads、Drafts、Attachments、Lists、Pods