MailToYou

API 文档

一个简单的 REST + SSE API，用于创建临时邮箱、接收验证码邮件、实时推送新邮件通知。无需注册，无需 API Key。

60 秒快速上手

理解这个 API 最快的方法，是把下面三个 curl 命令按顺序复制粘贴一遍。你会得到一个真正能收信的邮箱，并看到它收到第一封测试邮件。

  • 第一步 — 创建邮箱：curl -X POST https://api.m2u.io/v1/mailboxes/auto
  • 第二步 — 记下返回的 token 和 view_token，读邮件时两个都要用
  • 第三步 — 查看收件箱：curl "https://api.m2u.io/v1/mailboxes/TOKEN/messages?view=VIEW_TOKEN"
  • 第四步 — 向返回里的 LOCAL_PART@DOMAIN 发一封测试邮件，再查一次收件箱，就能看到它

API 是怎么设计的

整个 API 围绕一个对象：邮箱。创建邮箱后你会拿到两个密钥：token 用来标识这个邮箱是哪一个，view_token 用来证明你有权读取它的邮件。**每次读取都需要同时提供这两个**。之所以用双 token，是为了让别人知道你的邮箱地址后，无法直接看到你收到的邮件内容。

  • 无需注册、无需 API Key、无需 OAuth，直接调用即可
  • 限速按 IP 指纹计算，不按账号
  • 所有响应都是 JSON（SSE 流除外）
  • 错误格式统一为 { error: "错误码", reason?: "详情" }

基础 URL

本页所有示例都使用 https://api.m2u.io 作为基础 URL。如果你是自部署 MailToYou，替换成你自己的 API_BASE_URL 即可。

1. GET /v1/domains — 获取可用域名列表

返回创建自定义邮箱时可以使用的域名。如果你想让用户选域名，先调这个接口。

  • 鉴权：无
  • curl: curl https://api.m2u.io/v1/domains
  • 响应：{ "domains": ["cpu.edu.kg", "do4.tech", "tmail.bio", ...] }

2. POST /v1/mailboxes/auto — 创建随机邮箱

创建一个随机 local part、随机域名的邮箱。**这是脚本应该使用的主要接口**，不需要 Turnstile。

  • 鉴权：无
  • 请求体（可选）：{ "token": "已有 token" } — 传入已有 token 会返回同一个邮箱，用于轮询场景
  • curl: curl -X POST https://api.m2u.io/v1/mailboxes/auto -H 'Content-Type: application/json' -d '{}'
  • 响应：{ "mailbox": { "token", "view_token", "local_part", "domain", "expires_at" } }
  • 邮箱地址 = `${local_part}@${domain}`
  • token 和 view_token 都要保存好，读邮件时两个都需要

3. POST /v1/mailboxes/custom — 创建自定义前缀邮箱

创建一个带自定义前缀的邮箱，例如 `myname@cpu.edu.kg`。因为 local part 是有限资源，**这个接口需要 Cloudflare Turnstile 人机验证**（必须在浏览器里解）。脚本无法直接调用这个接口。

  • 鉴权：Turnstile token（仅浏览器能获取）
  • 请求体：{ "localPart": "myname", "domain": "cpu.edu.kg", "turnstileToken": "..." }
  • 响应：格式与 /auto 相同
  • 错误：address_taken（已被占用）、invalid_domain（不在域名列表）、turnstile_failed、daily_limit_exceeded

4. GET /v1/mailboxes/:token/messages?view=VIEW_TOKEN — 列出收件箱

按接收时间倒序返回最近 50 封邮件的列表，只含主题和元信息，不含正文。适合轮询场景。

  • 鉴权：token（路径参数）+ view_token（?view 查询参数），两个都必须
  • curl: curl "https://api.m2u.io/v1/mailboxes/TOKEN/messages?view=VIEW_TOKEN"
  • 响应：{ "messages": [{ "id", "from_addr", "subject", "received_at" }] }
  • 空收件箱返回 { "messages": [] }，不是错误

5. GET /v1/mailboxes/:token/messages/:id?view=VIEW_TOKEN — 读取单封邮件

获取一封邮件的完整内容，包含消毒后的 HTML 和纯文本。

  • 鉴权：与列表接口相同，token + view_token 双验证
  • curl: curl "https://api.m2u.io/v1/mailboxes/TOKEN/messages/MESSAGE_ID?view=VIEW_TOKEN"
  • 响应：{ "message": { "id", "from_addr", "subject", "text_body", "html_body", "received_at" } }
  • html_body 已经过消毒 — script、iframe、追踪像素都已剥离

6. GET /v1/mailboxes/:token/stream?view=VIEW_TOKEN — 实时推送（SSE）

Server-Sent Events 接口。建立一个长连接后，新邮件到达时会主动推送过来，**不需要轮询**。网站的实时收信功能就是用这个实现的。

  • 鉴权：与读取接口相同，token + view_token
  • connected 事件 — 连接成功时触发，内容 { "ok": true }
  • mail 事件 — 新邮件到达时触发，内容 { "id", "from", "subject", "receivedAt" }
  • 每 20 秒发送一次心跳，防止反向代理超时断连
  • 单个邮箱最多 5 个并发 SSE 连接，第 6 个会把最老的那个踢掉

完整示例（Node.js）

这是一个可以直接复制到任何 Node 脚本里运行的例子。它创建邮箱、轮询 2 分钟，打印收到的所有邮件。

  • const API = 'https://api.m2u.io';
  • const res = await fetch(`${API}/v1/mailboxes/auto`, { method: 'POST' });
  • const { mailbox } = await res.json();
  • console.log(`发送邮件到 ${mailbox.local_part}@${mailbox.domain}`);
  • const url = `${API}/v1/mailboxes/${mailbox.token}/messages?view=${mailbox.view_token}`;
  • for (let i = 0; i < 60; i++) {
  • const { messages } = await (await fetch(url)).json();
  • if (messages.length) { console.log(messages); break; }
  • await new Promise(r => setTimeout(r, 2000));
  • }

速率限制

限速按 IP 指纹计算（IP + User-Agent + Accept-Language 的组合）。**真实用户永远碰不到这些限制**。如果脚本收到 { "error": "rate_limited" }，退避 60 秒再重试即可。

  • POST /v1/mailboxes/auto — 60 次/分钟，200 次/天
  • POST /v1/mailboxes/custom — 10 次/分钟，10 次/天（还有 Turnstile 双重保护，脚本不能用）
  • GET /v1/mailboxes/:token/messages — 100 次/分钟
  • GET /v1/mailboxes/:token/messages/:id — 100 次/分钟
  • SSE 流 — 每个邮箱最多 5 个并发连接

错误码参考

所有错误响应格式统一为 { "error": "码", "reason"?: "详情" }。业务错误（rate_limited、daily_limit_exceeded、address_taken 等）HTTP 状态码是 200，只有协议错误才用 4xx/5xx。**使用 response.mailbox 或 response.messages 之前一定要先判断 response.error**。

  • rate_limited — 触发每分钟限制，等 60 秒
  • daily_limit_exceeded — 触发每日限制，等到第二天，或者改用 /auto 接口
  • address_taken — 自定义 local_part 已被占用，换一个
  • invalid_domain — 域名不在 /v1/domains 列表里
  • turnstile_failed — Turnstile token 缺失、过期或无效
  • access_denied — token 或 view_token 错误，或邮箱已过期
  • no_domains — 服务端没有启用任何域名（联系运维）
  • validation_failed — 请求体不符合 schema，详情在 details 字段

数据保留策略

邮箱从创建起保留 7 天，单封邮件从到达起保留 24 小时。清理任务每 30 分钟运行一次，永久删除所有过期数据 — **没有恢复机制，即便是运维也无法找回**。脚本应该在响应里立刻把需要的信息提取出来，不要依赖我们这边的长期存储。

有付费套餐吗？

暂时没有。MailToYou 目前完全免费且匿名。如果你希望有付费版本（更长的保留时间、Webhook 推送、自定义域名、更高的自动化配额等），欢迎在 GitHub 上提 issue 或直接联系我们 — 需求真实存在时我们才会开发。

API 文档 | MailToYou