一次性邮箱 API：开发者实战指南

网页收件箱对人来说很好用，但测试和自动化需要的是一次性邮箱 API：一种全程用代码就能完成“开一个抛弃式地址、读取里面收到的任何邮件、再把它销毁”的方式。本指南会逐一拆解其中的组成部分，并演示如何用 MoeMail 临时邮箱的 OpenAPI 把它们串起来。

为什么用 API，而不是网页收件箱？

注册、邮箱验证、找回密码这几类流程是最难做端到端测试的，因为验证那一步会跳出你的应用、落到某个收件箱里。一次性邮箱 API 把这个闭环补上：测试先开出一个全新收件箱，触发流程，再轮询 API 拿到验证邮件、从中提取链接或验证码——结果是确定的，也不会去污染某个多人共用的人工邮箱。

用 API 密钥鉴权

MoeMail 对程序化请求的鉴权，靠的是放在 X-API-Key 请求头里的 API 密钥。登录后在个人资料里生成一个密钥，然后给每个请求都带上它。密钥的作用范围限定在邮件和配置相关的端点，并受你账户每月配额的约束，所以请把它当作机密对待，一旦泄露就立刻轮换。

几个核心操作

• 创建邮箱——申请一个新的随机或自定义地址，并选定有效期。
• 列出邮件——轮询邮箱，查有没有新收到的邮件。
• 读取邮件——取出单封邮件的头信息、纯文本和 HTML 正文。
• 任其到期——什么都不用做；邮箱和里面的邮件会被自动清理掉。

最简单的一次轮询调用，就是把你的密钥作为请求头发给邮件端点，例如：curl -H "X-API-Key: YOUR_KEY" https://moemail.app/api/emails。请求与响应的具体结构都记录在 OpenAPI 定义里。

Webhook：别再轮询了

轮询能用，但它会拉高延迟、白白浪费请求。MoeMail 可以在邮件到达的瞬间触发一个 Webhook，于是你的测试或后端能立刻响应，而不是干等着循环。把 Webhook 指向一个由你的测试框架掌控的端点，校验载荷，邮件一落地就解除那个等待中的步骤。处理逻辑要保持轻快——几秒内就要响应，因为响应慢或返回非 2xx 都会触发重试。

速率限制与配额

API 用量会计入你账户每月的 OpenAPI 配额。对于大型测试套件，能复用就在多个断言间复用同一个邮箱、把轮询批量化，并优先用 Webhook 而不是紧凑的轮询循环。如果你需要更大余量，更高的角色等级和商店配额能抬高上限——或者干脆自建一个实例（见自托管 vs 托管临时邮箱）。

在测试里把它们串起来

无论你用 Playwright、Cypress 还是 Selenium，套路都一样：把创建/轮询/读取这几个调用包进一个小助手里（一个 fixture 或自定义命令），在测试开头开出一个收件箱，驱动你的界面走到验证那一步，再通过这个助手等待邮件到来。因为每次运行都拿到自己专属的地址，测试之间互不干扰，并行也安全。

下一步

读一读完整 API 文档，从个人资料里取一个密钥，先跑通一次“创建并轮询”的来回。然后把它端到端自动化：参见如何自动化邮箱验证测试和用 Webhook 接收来信。还不熟悉这套概念？从什么是临时邮箱开始，或者干脆在控制台里创建一个邮箱，亲眼看看 API 会返回什么。