邮件在自动化中是一个顽固的依赖项。它到达缓慢、可能重复、HTML模板会变化，MIME边缘情况会悄悄地破坏解析器。临时邮箱API通过按需提供一次性收件箱解决了基础设施问题，并通过将每条消息作为结构化JSON交付解决了集成问题，让您的测试和AI智能体像处理数据一样处理邮件，而不是像处理网页一样。
本指南涵盖了”接收和解析邮件为JSON格式”在实践中应该如何实现、如何选择webhook与轮询交付方式，以及如何安全地提取OTP和魔法链接。
什么是临时邮箱API（以及它应该做什么）
临时邮箱API是一种自动化友好的方式，可以通过编程方式配置收件箱、接收这些收件箱的入站邮件，并通过代码使用消息。
对于QA和智能体工作流，获胜的模式是收件箱优先：
- 您为每次运行或每次尝试创建一个新的收件箱。
- 您获得一个可路由的电子邮件地址以及一个收件箱句柄（通常是
inbox_id）。 - 您确定性地等待消息（webhook优先，轮询备用）。
- 您将消息解析为JSON并提取最小的工件（OTP、验证URL）。
- 您丢弃或轮换收件箱。
最后一点很重要：短生命周期的收件箱减少了跨测试冲突，并限制了泄漏时的影响范围。
“接收邮件为JSON格式”意味着稳定的契约，而非尽力而为的解析
邮件由RFC 5322和MIME（RFC 2045）等标准定义，但现实世界的邮件通常包含：
- 重复或折叠的标头
- 既有
text/plain又有text/html的多部分正文 - 奇怪的编码
- 附件和内联资源
- 存在、缺失或格式错误的线程标头
返回JSON的提供商应该将这些细节规范化为您可以依赖的契约。当您评估任何临时邮箱API时，请询问JSON输出是否足够稳定，以便您可以针对它编写断言。
自动化和智能体推荐的JSON字段
实用的JSON有效负载通常需要：
| JSON字段（概念） | 为什么重要 | 可靠性注意事项 |
|---|---|---|
message_id（提供商ID） |
幂等性的稳定标识符 | 不要仅依赖Subject或From
|
received_at |
确定性时间预算 | 优先使用服务器接收时间而非客户端猜测 |
to、from
|
路由和关联 | 规范化地址大小写和格式 |
subject |
调试和松散匹配 | 有用，但对严格匹配不可信任 |
headers（规范化） |
取证和关联 | 处理重复和折叠的标头 |
text（纯文本） |
安全、稳定的解析目标 | 优先使用text/plain进行提取 |
html（可选） |
人工检查、后备选项 | 作为不受信任的输入处理 |
attachments（元数据+获取） |
通过邮件发送文件的工作流 | 保持附件处理明确 |
raw（可选） |
调试和重新处理 | 在模板更改时有帮助 |
如果您正在构建LLM工具，请考虑向模型暴露最小化视图（例如：from、to、subject、received_at、text以及一小组提取的工件），并且除非您确实需要，否则将raw或HTML排除在智能体上下文之外。
交付模式：webhook与轮询（以及为什么大多数团队两者都需要）
从临时邮箱API接收消息有两种方式：
Webhook（推送）
Webhook是事件驱动的：当消息到达时，提供商会调用您的端点。
它们非常适合：
- 您希望低延迟
- 您希望减少API调用
- 您运行许多并行收件箱并希望事件流
在运营上，webhook要求您考虑重试、签名验证和幂等处理。
轮询（拉取）
轮询更容易部署：您的代码重复询问API是否有消息到达。
它在以下情况下有用：
- 您的环境无法接受入站web请求（某些CI设置）
- 您首先需要简单的实现
- 当webhook延迟或被阻止时，您需要后备路径
轮询必须仔细设计，以避免固定休眠、丢失消息和重复处理。
推荐的混合方式
在生产级自动化中，最可靠的方法是：
- Webhook优先以实现快速交付
- 轮询备用以实现恢复（如果您的webhook端点宕机、部署发生或通知被丢弃）
这里是快速比较：
| 机制 | 优势 | 常见陷阱 | 修复 |
|---|---|---|---|
| Webhook | 快速、可扩展 | 重放、欺骗、重试 | 验证签名、强制幂等性 |
| 轮询 | 简单、防火墙友好 | 速率限制、固定休眠、重复 | 退避、游标、已见ID |
| 混合 | 最健壮 | 更多活动部件 | 保持单一”等待消息”契约 |
如何安全地将邮件解析为JSON（特别是对于LLM智能体）
即使提供商给您JSON，邮件内容仍然是不受信任的输入。JSON格式只是让应用一致的规则变得更容易。
优先使用text/plain进行确定性提取
对于OTP和验证流程，text/plain通常比HTML变化较少，并且避免了与标记相关的解析失败。
如果您必须退回到HTML，请使用明确的保护措施：
- 不要在智能体工具中渲染HTML
- 在搜索之前去除标签并解码实体
- 避免自动”点击”链接
提取最小工件，而非”含义”
对于自动化，您通常需要以下工件之一：
- 数字OTP
- 验证URL（魔法链接）
- 密码重置链接
目标是最小确定性提取，而非摘要。
简单的提取策略：
- 最多接受一个与您格式匹配的OTP候选
- 最多接受一个与允许列表域名和预期路径前缀匹配的URL候选
- 如果有多个候选，则用可解释的错误失败并记录消息ID
在使用链接之前验证它们（SSRF和开放重定向卫生）
如果您的自动化跟踪来自邮件的URL，请将其视为安全边界：
- 允许列表您控制的域名
- 拒绝IP文字和私有网络目标
- 不要跟踪无界重定向链
OWASP SSRF预防备忘单是链接跟踪安全的有用基线。
CI和智能体工作流的确定性规则
大多数不稳定的邮件测试因为可预测的原因而失败：共享收件箱冲突、简单休眠和弱匹配。
使用每次尝试一个收件箱的模式
如果您在运行之间重用收件箱，您最终会读取错误的邮件。干净的修复是：为每次尝试（或至少每次运行）创建一个一次性收件箱，并将其inbox_id视为您的范围。
添加您控制的关联
使匹配变得狭窄且可解释：
- 在触发邮件的操作中包含运行标识符（例如：每次运行唯一的注册邮件地址，或您的系统回显的元数据中的关联令牌）
- 优先使用JSON有效负载中的稳定标识符而非模糊的主题匹配
预先设计幂等性
假设重复会发生：
- Webhook可以重试
- 轮询可以多次返回相同的消息
- 您自己的作业运行器可以重启
使用稳定的键，如inbox_id + message_id（有时还有提取的工件哈希）来确保您只处理相同的逻辑邮件一次。
规模化的批处理
如果您摄取大量邮件（负载测试、大型QA套件或智能体集群），批量检索和处理可减少开销并使您的管道更可预测。
最小集成示例（与提供商无关的伪代码）
下面是一个适用于QA工具和LLM工具的参考形状。
创建收件箱
// 伪代码，请参阅您的提供商文档以获取确切端点
const inbox = await emailApi.createInbox({
// 可选：域策略、webhook URL、元数据
});
// 在注册、创建用户或触发工作流时使用inbox.email
等待消息（混合）
async function waitForMessage({ inboxId, timeoutMs }) {
const deadline = Date.now() + timeoutMs;
// 在真实系统中优先使用webhook，但保留轮询作为后备。
// 此函数表示单一契约："返回第一个匹配的消息或超时"。
while (Date.now() < deadline) {
const messages = await emailApi.listMessages({ inboxId });
const candidate = pickBestCandidate(messages);
if (candidate) return candidate;
await sleep(backoffMs());
}
throw new Error(`等待收件箱${inboxId}的邮件超时`);
}
从JSON中提取OTP或魔法链接
function extractArtifact(messageJson) {
const text = messageJson.text ?? "";
const otp = text.match(/\b\d{6}\b/)?.[0];
if (otp) return { type: "otp", value: otp };
const url = findFirstAllowlistedUrl(text, {
allowlistDomains: ["example.com"],
});
if (url) return { type: "url", value: url };
throw new Error(`在消息${messageJson.message_id}中未找到OTP或允许列表URL`);
}
重要的部分不是正则表达式，而是契约：确定性等待、解析JSON、最小提取、在模糊时大声失败。
使用Mailhook实现这一点
Mailhook正是围绕这种确切的自动化模式构建的：
- 通过API创建一次性收件箱
- 接收邮件为结构化JSON
- 实时webhook通知（带有签名有效负载）
- 用于后备的轮询API
- 即时设置的共享域名和自定义域名支持
- 批量邮件处理
对于规范的、机器可读的集成详细信息（端点、有效负载形状、签名验证细节），请使用Mailhook的llms.txt参考：Mailhook llms.txt。
您也可以在Mailhook探索该产品。
临时邮箱API的评估清单（快速理智测试）
使用这个来比较提供商而不会迷失在营销中：
- 您能否通过编程方式创建收件箱并为每次运行隔离它们？
- 消息是否作为规范化JSON到达，带有稳定的ID和时间戳？
- 是否支持webhook，有效负载是否已签名？
- 轮询是否可用作后备，语义是否避免重复？
- 您能否在共享域名和自定义域名之间选择？
- 如果您需要吞吐量，是否支持批处理？
- 您能否保留原始源用于调试而不强制智能体读取原始HTML？
常见问题解答
什么是临时邮箱API？ 临时邮箱API让您通过API创建一次性收件箱，接收这些收件箱的入站邮件，并从代码中检索消息（通常为JSON）。
为什么我应该将邮件解析为JSON而不是抓取HTML？ JSON使邮件有效负载稳定且机器可读。抓取HTML是脆弱的，对智能体不安全，并且在模板更改时会中断。
我应该使用webhook还是轮询来接收邮件？ 使用webhook实现低延迟和扩展，保留轮询作为可靠性的后备。混合”webhook优先，轮询后备”模式是最健壮的。
我如何安全地从邮件中提取OTP或验证链接？ 优先使用text/plain，确定性地提取最小工件（一个OTP或一个允许列表URL），并在跟踪链接之前验证它们。
如何在webhook和轮询流程中防止重复？ 将邮件视为至少一次事件流。使用稳定键（如inbox_id + message_id）去重，并使处理程序幂等。
尝试Mailhook进行JSON优先的邮件自动化
如果您想要适合LLM智能体和QA自动化的临时邮箱API，Mailhook通过API提供一次性收件箱并将入站消息作为结构化JSON交付，支持webhook（签名有效负载）和轮询后备。
在此处获取确切的集成契约：Mailhook llms.txt，然后从mailhook.co开始（无需信用卡）。
