API 文档

基础 URL

https://api.mail.cx/v1

所有接口都位于 /v1 前缀下，必须使用 HTTPS。每个请求的基础 URL 都相同。

认证

每个请求都必须通过 x-api-token 请求头携带 API 令牌。令牌类型决定调用者的权限：

• 用户令牌（tm_live_…） — 在控制台 → 令牌中创建，用于 SDK / 自动化场景。受单用户速率限制 + 月度 Ops 配额约束。免费版 1 个，专业版 10 个。
• 网页会话（tm_live_…） — 由登录 / 注册 / OAuth 颁发，7 天 TTL。用于浏览器 UI；不占用用户令牌配额，也不扣 Ops。
• 匿名令牌（tm_anon_…） — 通过 POST /v1/sessions/anon 颁发（启用 Cloudflare Turnstile 时仅限浏览器）。默认 24 小时 TTL。仅能访问系统域名邮箱 — 无法访问自定义域名、/me、/tokens、/domains 或管理员接口。

curl https://api.mail.cx/v1/inbox \
  -X POST \
  -H "x-api-token: tm_live_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{}'

快速开始

1. 创建临时邮箱。请求体为空时服务器会在默认系统域名上生成随机 local_part。返回邮箱地址和以 Unix 毫秒时间戳表示的过期时间。

curl -X POST https://api.mail.cx/v1/inbox \
  -H "x-api-token: tm_live_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{}'

// → 201
{
  "address": "ab12cd@qabq.com",
  "expires_at": 1715706000000
}

2. 使用长轮询等待邮件。服务器会保持连接最长 25 秒。200 表示有新邮件；204 表示等待超时未收到邮件，使用返回的 next_since 游标重新发起请求即可。

curl "https://api.mail.cx/v1/inbox/ab12cd@qabq.com?since=0" \
  -H "x-api-token: tm_live_your_token_here"

// → 200
{
  "emails": [
    { "id": "uuid", "from_email": "sender@example.com", "subject": "...", "preview_text": "...", "created_at": "2026-05-14T12:00:00Z" }
  ],
  "next_since": "1715706012"
}

3. 通过邮件 id 读取完整邮件（纯文本正文、HTML 正文、附件元数据）。

curl https://api.mail.cx/v1/email/{email_id} \
  -H "x-api-token: tm_live_your_token_here"

速率限制与 Ops 配额

每次已认证请求都会在一次 Redis 往返内原子地跑两层校验：单用户滑动窗口速率限制 + 月度 Ops 计数。匿名令牌没有应用层速率限制 — IP 限速在网络边缘进行。

已认证响应包含 X-Ops-Limit 与 X-Ops-Remaining 响应头。响应体为 {"error":"rate_limit_exceeded"} 的 429 同时附带 Retry-After（秒）；响应体为 {"error":"ops_quota_exceeded"} 的 429 在 UTC 次月 1 日重置。

什么算作一个 Op？

只有控制台创建的用户令牌（kind=user）会扣 Ops。网页会话令牌（UI 登录用）和匿名令牌不计入月度配额。

• POST /v1/inbox 和 POST /v1/mailboxes — 创建地址
• GET /v1/email/:id 和 GET /v1/emails/:id — 读取解析后的邮件
• GET /v1/emails/:id/raw 与 /attachments/:index — 下载原始 EML 或附件
• 列表收件、SSE 推送、/me、/ops、/config、登录注册和管理员接口均不计入 Ops

接口列表

Inbox（v1 AI 友好接口）

为 AI Agent 和 SDK 设计的简洁资源结构。GET 接口采用长轮询 — 服务器保持连接最长 25 秒（config wait_seconds，由服务端固定，客户端无法修改）。新邮件到达或等待结束时返回。204 = 等待超时无新邮件；200 = 至少匹配到一封；429 = 触发并发上限（响应中带 Retry-After 头）。

POST /v1/inbox 接受可选 JSON 请求体。所有字段均为可选。

Mailboxes（按地址访问的兼容接口）

Web UI 使用的原始按地址寻址接口。数据模型与 v1 完全一致，区别在于返回分页列表而非长轮询。

邮件内容

API 令牌

管理用户令牌（kind=user）。网页会话令牌（登录产生）不会出现在列表中也无法在此接口吊销 — 退出登录即可。免费版 1 个；专业版 10 个。

自定义域名（专业版）

添加你拥有的域名，即可在该域名下任意地址收信。验证需要两条 DNS 记录：TXT 记录 _tempmail.<domain> 值为 tempmail-verify=<token>，MX 记录指向 smtp.mail.cx。后台校验每 5 分钟轮询一次；72 小时未验证将标记为失败。

账户与用量

实时推送（SSE）

实时邮件事件使用 HTTP 上的 Server-Sent Events（SSE）。浏览器的 EventSource API 会自动带 Last-Event-ID 头重连，服务端用它作为 Redis Stream 游标回放断连期间丢失的事件。由于 EventSource 不支持自定义请求头，令牌通过查询参数传递。

每封新邮件以 SSE 事件形式推送。每 30 秒发送一次心跳注释行（:ka <id>），防止反向代理断开连接。

const es = new EventSource(
  "https://api.mail.cx/v1/sse/user?token=tm_live_your_token_here"
);

es.addEventListener("email", (e) => {
  const data = JSON.parse(e.data);
  // { id, address, from, subject, preview }
});

// Heartbeat lines (":ka <last-id>") are surfaced as comments — no handler needed.
// On disconnect EventSource auto-reconnects and sends Last-Event-ID;
// the server replays any missed events from the Redis Stream.

错误处理

错误返回 JSON 对象，包含机器可读的 "error" 字段。HTTP 状态码表示错误类别。

{ "error": "rate_limit_exceeded" }