MailOps API 文档入口

先选路线

GPT/OpenAI 注册路线

最开始的 GPT 注册机链路。用 safe/new 邮箱池，领取后读验证码，并可上报 GPT 账号仓库。

领取邮箱：POST /api/mailboxes/reserve
读验证码：GET /api/mail/code
收不到码隔离：POST /api/mailboxes/report-code
GPT 账号上报：POST /api/gpt-accounts/report

打开 GPT 路线文档 GPT spec

多平台复用路线

Cursor/Claude/Poe 等非 OpenAI 平台使用。必须显式传 platform，通过 lease_token 防串号。

平台列表：GET /api/reuse/v1/platforms
状态汇总：GET /api/reuse/v1/summary
按平台预留：POST /api/reuse/v1/mail/reserve
确认/释放：mark-used / release

打开多平台文档多平台 spec

生产邮箱资产自动导入

此路线只导入可读邮箱资产到 API Key 所属用户的邮箱池，不写入 GPT 账号仓库。

POST /api/accounts/import
Authorization: Bearer mak_xxx
Content-Type: application/json

{
  "format": "gmail_api_v1",
  "text": "user@gmail.com----https://your-approved-receiver.example/show/abc----production-batch",
  "auto_scan": false,
  "limit": 20,
  "concurrency": 3
}

管理端导入窗口默认勾选自动扫描；API 仍按兼容规则使用 auto_scan=false 时，新增邮箱固定进入 category=new、status=new。
Outlook OAuth 格式：email----password----client_id----refresh_token----tag；密码和 tag 可选。
iCloud/Gmail URL 收信格式：email----receiving_url----tag，可显式传 format=icloud_api_v1 或 format=gmail_api_v1；未传 format 时系统会按邮箱域名和 HTTPS URL 自动识别。Gmail 仅接受 gmail.com/googlemail.com，并进入独立 gmail_api 池。iCloud 支持 icloud-api.top 和 mail.sayt.cloud/api/v1/access/.../mailboxes/.../view；sayt.cloud 会通过 refresh=1 JSON 接口读取邮件。
邮箱列表的“导出当前筛选”和“导出选中”会保持可回导格式：iCloud/Gmail 导出为 email----receiving_url----tag，Outlook 保持原有 email----password----client_id----refresh_token 格式。导出 URL 仅从加密收件配置临时读取，不会明文存入数据库。
接码 URL 必须使用 HTTPS、可公开解析，并且其域名已配置进服务器 MAILOPS_EXTERNAL_RECEIVER_ALLOWED_HOSTS。URL 收信邮箱会先健康检测，检测成功前不会进入可领取库存。sayt.cloud 返回的 iframe 正文会自动展开解析，页面中的空邮件占位不会计入邮件列表；历史版本写入的空占位会在下次刷新时自动清理。健康检测在 PostgreSQL 下使用绑定参数，不会把 URL 或正文中的百分号误当作 SQL 占位符。
同一 API Key 只会导入到该 Key 所属用户的邮箱池；跨用户重复邮箱会被拦截。
不要发送 GPT 的 id_token、access_token、chatgpt_account_id，也不要调用 /api/gpt-accounts/report。

查看机器规格

关键边界

控制台顶部的邮箱池选择会同时作用于概览统计、邮箱列表和复检任务。对接扫描接口时传同一个 pool_key，例如 icloud_api、gmail_api 或 outlook_oauth，即可保证任务不会跨池扫描。

项目	GPT/OpenAI 路线	多平台路线
主要用途	OpenAI/GPT 注册机领邮箱和读码	Cursor/Claude/Poe 等平台复用已有健康邮箱
领取接口	`/api/mailboxes/reserve`	`/api/reuse/v1/mail/reserve`
平台参数	不需要 `platform`	必须显式传 `platform`
状态语义	`accounts.used` 是 GPT 旧链路已用	`mailbox_platform_usages` 记录各平台使用历史
防重复	领取时直接把邮箱移出 safe 池	同平台 `reserved/success` 不再重复发
禁止事项	不要接 `/api/reuse/v1/*`	不要用 `GET /api/mailboxes` 分配邮箱

兼容保留：/api-spec.json 仍是合并规格，给旧工具兼容用；新接入建议直接使用上面的两份独立 spec。

控制台查看 category=待确认（或 status=review）时会同时返回已用和未用的人工复核邮箱，确保分类数字与列表一致。

控制台扫描可调用 POST /api/scan/stop 协作停止：停止后不再派发新邮箱，已经开始的收信请求结束后会显示停止结果。

iCloud URL 收信邮箱扫描会同时检查收件箱和垃圾箱，并保留已缓存的验证码证据，不会被后续欢迎邮件覆盖；支持中文、英文和日文的 ChatGPT/OpenAI 验证码提示，命中 6 位验证码会标记为已用。