API 文档

基础 URL

所有 API 端点基于基础 URL。公共服务的基础 URL 为 https://api.m2u.io。

GET /v1/domains

返回可用的邮箱域名列表。无需身份验证。

• 响应: { domains: string[] }
• 示例: GET /v1/domains → { "domains": ["cpu.edu.kg", "do4.tech", ...] }

POST /v1/mailboxes/auto

自动创建一个随机临时邮箱。无需身份验证。有速率限制。

• 请求体（可选）: { token?: string } — 传入已有 token 可复用邮箱
• 响应: { mailbox: { token, view_token, local_part, domain, expires_at } }
• 速率限制: 每分钟 5 次，每天 20 次（按 IP）

POST /v1/mailboxes/custom

使用自定义前缀和域名创建邮箱。需要 Turnstile 人机验证。

• 请求体: { localPart: string, domain: string, turnstileToken: string }
• 响应: { mailbox: { token, view_token, local_part, domain, expires_at } }
• 错误: address_taken, invalid_domain, turnstile_failed, daily_limit_exceeded

GET /v1/mailboxes/:token/messages?view=VIEW_TOKEN

列出邮箱中的所有邮件。需要邮箱 token 和 view_token 双重验证。

• 响应: { messages: [{ id, from_addr, subject, received_at }] }
• 按接收时间倒序排列，最多 50 条

GET /v1/mailboxes/:token/messages/:id?view=VIEW_TOKEN

获取单封邮件的完整内容，包括 HTML 和纯文本。

• 响应: { message: { id, from_addr, subject, text_body, html_body, received_at } }

GET /v1/mailboxes/:token/stream?view=VIEW_TOKEN

SSE（Server-Sent Events）实时通知端点。连接后新邮件到达时会即时推送。

• connected 事件 — 连接成功时发送
• mail 事件 — 新邮件到达时发送，包含 { id, from, subject, receivedAt }
• 每 20 秒发送 keep-alive 心跳

数据保留

邮箱有效期 7 天。邮件在 24 小时后自动删除。过期后所有数据永久清除。

速率限制

API 端点按 IP 地址限速。超过限制时会返回 { error: "rate_limited" }。

• 自动创建邮箱: 5次/分钟, 20次/天
• 自定义邮箱: 5次/分钟, 3次/天
• 读取邮件: 100次/分钟