Skip to content

只读邮件 API(Parsed) ​

认可的稳定接口

下面三个端点是 Spare.Email 认可的、只读的 API 接口。它们与官方 MCP 服务器 spare-email-mcp 所使用的端点完全相同,此处的响应结构均已对照 Spare.Email 实际验证。不在本页面范围内的任何内容均明确不对外部使用者开放:创建邮箱、发送、删除及管理端点可能随时变更,或要求通过网页界面操作,请勿基于它们进行开发。

这些端点返回已解析的邮件(可直接读取 subject、text、html、附件元数据),与查看邮件 API 中的原始端点不同。它们适用于任何保持更新的 cloudflare_temp_email 部署——自部署实例可以将请求指向自己的 worker URL。撰写本文时,相关处理器与上游 main 分支完全一致;上游可能继续演进解析格式,因此请以 Spare.Email 作为参考部署,并在同步上游后重新验证。

身份验证 ​

请求头是否必需说明
Authorization是Bearer <address_jwt> —— 邮箱凭据(Address JWT)
x-custom-auth启用时必需当部署设置了 PASSWORDS 时所需的站点访问密码
x-lang否错误消息首选语言(en / zh)

Address JWT 即打开某个邮箱的完整钥匙:持有者只能读取该邮箱的邮件,无其他权限。没有其他身份层——请妥善保管凭据。

GET /api/settings ​

将凭据解析到对应邮箱,并返回邮箱状态:

bash
curl -H "Authorization: Bearer $JWT" https://spare.email/api/settings
json
{
  "address": "[email protected]",
  "send_balance": 0,
  "new_address_token": null,
  "expire_at": null
}
字段类型说明
addressstring该凭据对应的邮箱地址
send_balancenumber出站发送余额(只收不发实例恒为 0)
new_address_tokenstring | null部署下发轮换令牌时的替换凭据;null 表示继续使用当前 JWT
expire_atnumber | null用户设置的到期时间(Unix 秒级时间戳);null = 无自定义到期

GET /api/parsed_mails ​

分页返回已解析的收件箱,按时间倒序:

bash
curl -H "Authorization: Bearer $JWT" "https://spare.email/api/parsed_mails?limit=20&offset=0"
参数范围说明
limit1–100整数;超出范围返回 400 文本错误(Invalid limit)
offset≥ 0整数;负数或缺失返回 400 文本错误(Invalid offset)
json
{
  "results": [
    {
      "id": 1,
      "message_id": "<[email protected]>",
      "source": "[email protected]",
      "address": "[email protected]",
      "metadata": null,
      "is_unread": null,
      "created_at": "2026-11-16 08:26:37",
      "sender": "Example Sender <[email protected]>",
      "subject": "Your verification code",
      "text": "Your verification code is 123456",
      "html": "<html>…</html>",
      "attachments": [
        { "filename": "invoice.pdf", "mimeType": "application/pdf", "disposition": "attachment", "size": 27412 }
      ]
    }
  ],
  "count": 1
}

行字段是增量式的:在未应用相应数据库补丁的旧部署上,metadata、is_unread 和附件的 disposition 可能为 null 或缺失。解析端点不会返回 raw 原始源字段。

分页提示:count 仅在第一页计算

count(邮箱内邮件总数)仅在 offset=0 时查询。后续页面返回 count: 0——翻页时请保留第一页获取的总数。

GET /api/parsed_mail/:id ​

单封已解析邮件,行结构相同(无分页包装):

bash
curl -H "Authorization: Bearer $JWT" https://spare.email/api/parsed_mail/1
  • 属于其他地址(或不存在)的邮件返回 HTTP 200 且 body 为 null——这是有意设计:不会向未知凭据确认邮件 ID 的存在性。应检查 body 是否为 null,而不是 404。
  • 响应不包含 RFC822 原始源;如需自行解析,请使用查看邮件 API 中的原始端点。

错误语义 ​

情况响应
JWT 缺失/无效,或启用 PASSWORDS 时缺少 x-custom-auth401 附带消息
limit/offset 超出范围400 附带翻译后的文本错误
邮件不存在(或凭据不匹配)200,body 为 null
Cloudflare 区域级限流429 —— 退避并逐步加大间隔重试

worker 本身对这些读端点没有专门的速率限制;上游的速率限制仅作用于创建/发送端点。轮询客户端仍应保持礼貌:几秒的轮询间隔已绰绰有余。

等待 OTP 验证码(客户端模式) ​

没有专门的等待/OTP 端点——等待是对列表/读取端点的轮询机制,这正是 spare-email-mcp 中 wait_for_otp 的实现方式:

  1. 记录你已见过的最大邮件 id。
  2. 每 3–30 秒轮询一次 GET /api/parsed_mails(遵守你自己的超时设置,如 10 分钟)。
  3. 将任何 429 视为退避信号。
  4. 用你的过滤条件匹配新邮件(如主题包含 "code"),从 subject 或去除标签后的 text/html 中提取验证码。

明确不属于此接口范围的功能 ​

POST /api/new_address(创建邮箱)、POST /api/send_mail(部署启用时)、POST /api/expire、DELETE 流程以及 /admin/* 下的所有内容均不对外部 API 使用者开放,可能随时变更且不另行通知。请通过网页界面创建邮箱;滥用行为请举报至 [email protected]。

另请参阅 ​

文档改编自 MIT 许可的 cloudflare_temp_email 项目 — 许可与致谢