邮件自动化最常在无聊的地方失败：解析。如果您正在构建QA流程、注册验证或阅读邮件的LLM代理，通常可以忽略视觉HTML，但仍会被其周围的元数据绊倒。这份邮件头指南专注于哪些头部字段值得解析、如何信任它们，以及如何将它们转化为可靠的信号。
邮件头部的简单解释（以及为什么它们很棘手）
邮件消息不仅仅是主题和正文。它是一个结构化对象，包含：
- 信封数据（SMTP级别路由，通常在消息内部不完全可见）
- 消息头（RFC定义的字段加上供应商特定字段）
- 正文（通常是包含HTML、文本、附件的MIME多部分）
有两个因素使头部对自动化来说很脆弱：
- 头部很容易添加、重新排序、重复或跨行折叠，不同的提供商会采用不同方式。
- 某些头部是权威的，某些是尽力而为的，某些完全由攻击者控制。 您的解析器需要一个信任模型。
如果您想要标准参考，消息格式的规范是RFC 5322。
可靠性优先的解析思维
在列出具体头部字段之前，采用一些保持代理和测试工具确定性的规则会很有帮助。
1) 将头部视为不可信输入
即使在内部系统中，邮件也可能被转发、被网关处理或由第三方生成。在数据库查询、命令或模板中直接使用头部值之前，务必进行清理。
2) 优先使用稳定标识符而非展示字段
人类查看Subject和显示名称。自动化应该优先使用Message-ID、您自己的关联头部和提供商验证的身份验证结果等标识符。
3) 预期重复和重试
系统可以合法地多次传递相同的逻辑消息（重试、转发、别名、列表扩展）。您的管道应该是幂等的。
4) 带规范化的解析
至少要：
- 展开头部行（处理延续空白）
- 规范化空白字符
- 解码编码词（RFC 2047）
- 支持重复头部（存储为数组）
对可靠自动化最重要的头部字段
下面是当您希望获得确定性行为时通常提供最高价值的头部字段。
消息身份和去重
**Message-ID**是邮件最接近全局消息标识符的东西。它由发送方（或发送基础设施）生成，应该是唯一的。
如何使用：
- 使用
Message-ID作为主要去重键，可选地与收件箱ID和时间窗口结合。 - 在各处记录它，以便可以跨系统跟踪传递问题。
注意：它仍然由发送方控制，所以不要将唯一性视为保证。使用带有后备的幂等性。
**Date**对排序有用，但不适用于身份识别。
- 适用于：近似排序和SLA测量。
- 不适用于：严格排序或去重（时钟漂移，时区变化）。
路由和邮件实际去向
**Received**头部形成逐跳跟踪，每个跳点都会预添加一个新的Received行。当某些东西看起来不对时，这通常是最有用的”现实检查”。
如何使用：
- 使用最后几个Received跳点来了解哪个提供商处理了传递以及何时处理。
- 在自动化中，提取一个简单的
received_chain_count，可选地提取最顶部和最底部的时间戳用于调试。
注意：Received链可能很长，某些跳点可能是内部的或已编辑。
Return-Path（有时是X-Envelope-From）反映退信地址（信封发送方）。当您需要关联退信或理解转发时，这可能很重要。
注意：转发和网关可以重写它。
**Delivered-To**或提供商特定的等效字段可以在涉及别名时帮助确认实际收件人邮箱。
身份验证和信任信号
如果您的代理基于”谁发送了这个”做出决定，请解析身份验证结果。
**Authentication-Results**通常由接收基础设施添加，总结SPF和DKIM等检查。
如何使用：
- 如果您的流程需要发送方信任，要求
dkim=pass或spf=pass（依赖于策略）。 - 存储原始字符串，并将其解析为结构化布尔值以用于代理规则。
**DKIM-Signature**包含签名、选择器和域。它本身不是”通过/失败”，但是有用的上下文。
提示：除非您真的需要，否则不要尝试从头验证DKIM，大多数系统依赖接收方的Authentication-Results。
如果您想要标准上下文，请参阅RFC 6376 (DKIM)。
内容处理（MIME和编码）
大多数脆弱的邮件自动化错误发生在正文不是您认为的那样时。
**Content-Type**告诉您正文是纯文本、HTML、多部分还是包含附件。
- 解析它以检测
multipart/alternative（文本加HTML的常见情况）。 - 当您必须解析原始MIME时提取边界。
**MIME-Version**通常是1.0。这主要是一个合理性检查。
**Content-Transfer-Encoding**告诉您正文是如何编码的（base64、quoted-printable）。如果您忽略这个，您的代理可能会”看到”乱码文本或损坏的链接。
经验法则：将正文视为树（多部分），而不是单个字符串。
线程和对话上下文
对于响应邮件线程的代理，这些至关重要：
-
In-Reply-To：指向先前的Message-ID -
References：线程上下文的Message-ID链
这些比主题前缀启发式（如”Re:“或”Fwd:”）更好。
批量邮件和自动化信号
如果您需要检测新闻通讯与事务邮件：
-
List-Unsubscribe：列表邮件的强信号 -
Precedence或Auto-Submitted：可能表明自动生成的消息
如果您的收件箱在多个工作流程间共享且您想忽略噪音，这特别有用。
不应依赖的内容（常见的不稳定来源）
许多”在我的机器上工作”的邮件解析器失败是因为它们将弱字段视为强字段。
-
不要使用
Subject进行唯一性判断。 主题会重复，随本地化更改，并被重写。 -
不要假设头部只出现一次。 多个
Received、多个To、多个Authentication-Results可能发生。 - 不要假设头部顺序。 解析器应该与顺序无关。
- 不要假设显示名称稳定。 使用地址规范，而不是”友好名称 x@y”。
-
不要仅信任
From进行授权。 当安全性重要时使用身份验证结果。
实用的”信任度和有用性”表格
使用这样的表格来决定解析、存储和验证什么。
| 头部 | 自动化中的最佳用途 | 信任级别（典型） | 注释 |
|---|---|---|---|
Message-ID |
幂等键、关联 | 中等 | 发送方生成，但非常有用 |
Received |
传递跟踪、调试时间 | 中等到高 | 每跳添加，可能包含内部详情 |
Authentication-Results |
通过/失败门控、反欺骗 | 高（当由您的接收方添加时） | 接收方生成的摘要 |
Content-Type |
选择正文部分、解析MIME | 中等 | 发送方控制但结构上必需 |
Content-Transfer-Encoding |
正确解码 | 中等 | 解释正文字节所需 |
In-Reply-To / References
|
线程重建 | 中等 | 比主题启发式更好 |
Return-Path |
退信关联 | 中等 | 可能被转发重写 |
Subject |
UI显示、次要提示 | 低 | 经常变化，不要断言 |
关联：在可能时添加您自己的头部
最可靠的头部是您控制的头部。
如果您的系统发送邮件（验证、OTP、魔法链接），添加类似于：
X-Correlation-Id: <uuid>X-Test-Run-Id: <ci-run>X-Agent-Task-Id: <task-id>
然后您的代理可以确定性地选择正确的消息，即使多个邮件并行到达。
如果您无法控制发送方（第三方SaaS），回退到复合策略：Message-ID（当已知时），加上时间窗口，加上收件人和发送方域的受限匹配，加上正文提取规则。
LLM代理的最小解析约定
LLM在您给它们小而稳定的模式而不是原始头部块时表现更好。一个好的方法是生成一个”解析信封”对象和一个”原始头部”对象。
一个实用的约定看起来像：
{
"message_id": "<...>",
"from": {"address": "[email protected]", "name": "Sender"},
"to": [{"address": "[email protected]"}],
"subject": "...",
"date": "2026-01-23T20:10:00Z",
"auth": {"dkim": "pass", "spf": "pass", "dmarc": "pass"},
"received_hops": 5,
"content": {"mime_type": "multipart/alternative"}
}
然后单独存储原始头部用于取证。
示例：使验证链接提取可靠
一个强大的验证提取器通常遵循这个顺序：
- 识别正确的邮件（如果可用则使用关联头部，否则过滤）。
- 确认它对您的风险级别足够真实（身份验证结果）。
- 选择正确的正文部分（当可用时优先使用text/plain，回退到HTML）。
- 使用保守规则提取链接（域允许列表、路径模式）。
- 应用幂等性：每个关联ID只点击一次。
注意步骤3直接依赖于Content-Type和Content-Transfer-Encoding。许多不稳定来自意外解析附件部分或错误的替代。
当您需要头部作为数据时Mailhook的作用
如果您的工作流程需要按需创建收件箱并可靠地解析头部，当邮箱产品将邮件视为结构化输入时会很有帮助。
Mailhook通过API创建一次性收件箱，并将收到的邮件作为结构化JSON返回，这使得以下操作变得简单：
- 解析和存储头部字段，无需编写脆弱的原始MIME解析器
- 通过webhooks触发实时处理或回退到轮询
- 使用签名载荷验证载荷完整性
- 通过批量邮件处理处理更高吞吐量
有关功能的权威、最新描述，请参阅Mailhook的llms.txt。
真实世界集成示例（超越QA）
头部解析不仅仅用于测试。任何依赖入站邮件的B2B工作流程都可以受益，例如接收预订确认、文档请求或来自合作伙伴系统的状态通知的旅行运营。
如果您正在构建旅行软件并需要简化管理流程，像SimpleVisa的电子签证处理平台这样的提供商是API优先方法的好例子，其中可靠的解析和确定性自动化很重要。
常见问题
我应该首先解析哪些邮件头部以确保可靠性？ 从Message-ID、Received、Authentication-Results、Content-Type和Content-Transfer-Encoding开始。这些涵盖了身份、可追溯性、信任和正确的正文解码。
我可以信任From头部来识别发送方吗？ 不能单独信任。当发送方信任很重要时，使用来自您接收基础设施的Authentication-Results（SPF、DKIM、DMARC）。
为什么我的自动化在Gmail中看起来正常的邮件上会崩溃？ 邮件客户端隐藏了复杂性。自动化经常在MIME结构（多部分正文）、传输编码和UI无缝呈现的重复或折叠头部上崩溃。
将邮件关联到特定代理任务或测试运行的最佳方式是什么？ 发送邮件时添加您自己的关联头部（例如X-Correlation-Id）。如果不能，使用带有严格约束和时间窗口的复合过滤器。
使用Mailhook构建更可靠的收件箱自动化
如果您正在构建依赖邮件的LLM代理或QA自动化，减少不稳定性的最快方法是将消息视为结构化事件，而不是HTML块。Mailhook让您通过API创建一次性收件箱并将消息作为JSON接收，这样您的代码可以确定性地解析头部并对正确的邮件采取行动。
在mailhook.co探索Mailhook，并在llms.txt中保持功能参考便于查阅。
