只读邮件 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
将凭据解析到对应邮箱,并返回邮箱状态:
curl -H "Authorization: Bearer $JWT" https://spare.email/api/settings{
"address": "[email protected]",
"send_balance": 0,
"new_address_token": null,
"expire_at": null
}| 字段 | 类型 | 说明 |
|---|---|---|
address | string | 该凭据对应的邮箱地址 |
send_balance | number | 出站发送余额(只收不发实例恒为 0) |
new_address_token | string | null | 部署下发轮换令牌时的替换凭据;null 表示继续使用当前 JWT |
expire_at | number | null | 用户设置的到期时间(Unix 秒级时间戳);null = 无自定义到期 |
GET /api/parsed_mails
分页返回已解析的收件箱,按时间倒序:
curl -H "Authorization: Bearer $JWT" "https://spare.email/api/parsed_mails?limit=20&offset=0"| 参数 | 范围 | 说明 |
|---|---|---|
limit | 1–100 | 整数;超出范围返回 400 文本错误(Invalid limit) |
offset | ≥ 0 | 整数;负数或缺失返回 400 文本错误(Invalid offset) |
{
"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
单封已解析邮件,行结构相同(无分页包装):
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-auth | 401 附带消息 |
limit/offset 超出范围 | 400 附带翻译后的文本错误 |
| 邮件不存在(或凭据不匹配) | 200,body 为 null |
| Cloudflare 区域级限流 | 429 —— 退避并逐步加大间隔重试 |
worker 本身对这些读端点没有专门的速率限制;上游的速率限制仅作用于创建/发送端点。轮询客户端仍应保持礼貌:几秒的轮询间隔已绰绰有余。
等待 OTP 验证码(客户端模式)
没有专门的等待/OTP 端点——等待是对列表/读取端点的轮询机制,这正是 spare-email-mcp 中 wait_for_otp 的实现方式:
- 记录你已见过的最大邮件
id。 - 每 3–30 秒轮询一次
GET /api/parsed_mails(遵守你自己的超时设置,如 10 分钟)。 - 将任何
429视为退避信号。 - 用你的过滤条件匹配新邮件(如主题包含 "code"),从
subject或去除标签后的text/html中提取验证码。
明确不属于此接口范围的功能
POST /api/new_address(创建邮箱)、POST /api/send_mail(部署启用时)、POST /api/expire、DELETE 流程以及 /admin/* 下的所有内容均不对外部 API 使用者开放,可能随时变更且不另行通知。请通过网页界面创建邮箱;滥用行为请举报至 [email protected]。
另请参阅
- AI Agent 使用邮箱 —— Agent 使用模式与授权注意事项
- 邮箱到期时间 API —— Spare.Email 的邮箱到期扩展
- spare-email-mcp(GitHub) —— 本 API 的参考 MCP 客户端