API 文档入口

此路线只导入可读邮箱资产到 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 可选。兼容部分批量导出器插入的 第1000条、第2000条账号、第3000行数据 等纯序号分隔行，系统会忽略这些分隔行，不计为失败账号；真实字段不完整的账号仍会明确报错。
• iCloud/Gmail URL 收信格式：email----receiving_url----tag，可显式传 format=icloud_api_v1 或 format=gmail_api_v1；未传 format 时系统会按邮箱域名和 HTTPS URL 自动识别。已知来源继续走专用驱动；未知公网 HTTPS 来源自动进入“通用 URL”驱动，支持常见 JSON 邮件列表、单封邮件 JSON 与静态 HTML 邮箱页，并保留 URL 编码参数。Gmail 仅接受 gmail.com/googlemail.com，并进入独立 gmail_api 池。iCloud 已知来源包括 icloud-api.top、mail.sayt.cloud/api/v1/access/.../mailboxes/.../view、ipm.yx66.email/api/v1/mailboxes/.../code?key=... 和 191006.xyz/mailbox/{token}；这些继续使用原专用解析。
• 邮箱列表的“导出当前筛选”和“导出选中”会保持可回导格式：iCloud/Gmail 导出为 email----receiving_url----tag，Outlook 导出为 email----password----client_id----refresh_token----tag，自有域名邮箱导出为 email----https://gptmail.passkissyou.online/mail/receiver?... 。域名邮箱 URL 默认按收件时间倒序只显示最新一封邮件，并每 5 秒自动刷新并重新收取邮件，可切换“查看全部邮件 / 只看最新一封”；显示完整主题、发件人、正文和链接。自动化项目需要 JSON 时，在同一参数后把路径改为 /api/mail/receiver，并按 3-5 秒间隔轮询同一 URL；每次请求都会刷新 IMAP 后再返回最新内容。传 auto_refresh=0 可关闭浏览器页面自动刷新。同一行用 format=managed_domain_v1 回导时会从 URL 的 domain 参数绑定当前用户已配置的同名域名池，不再附带内部 domain-generated 标记。历史的 managed_domain://domain 三段格式仍兼容。
• 通用 URL 必须使用 HTTPS 标准 443 端口、可解析到公网地址，且不得携带 URL 登录凭证；私网、回环、Docker 网段和每次重定向目标都会被拦截复检。新来源先健康检测并验证邮箱归属，成功后才进入可领取库存；失败会显示“通用 URL 不可用”，不会影响现有邮箱池。系统只在导入健康检测、人工查看或已领取邮箱 refresh=1 时抓取，响应体有大小上限，只缓存标准化的最近邮件。需要登录、验证码或 JavaScript 执行才能展示邮件的页面会被隔离，不会进入可领取库存。
• “邮件查看”默认刷新当前邮箱，并以缩略列表展示邮件。点击“查看完整邮件”会读取缓存的完整可读正文；HTML 中的样式脚本不会显示，HTTP/HTTPS 链接会保留为可点击链接。完整正文默认最多缓存 120000 个字符，可通过 MAILOPS_MESSAGE_BODY_TEXT_MAX 调整。
• 同一 API Key 只会导入到该 Key 所属用户的邮箱池；跨用户重复邮箱会被拦截。
• 自有域名邮箱在“域名邮箱”页面独立管理：先添加域名并配置 DNS，再验证邮件主机，最后填写 Catch-all 汇总邮箱的 IMAP 配置。生成的域名邮箱进入独立 domain_* 邮箱池，收件验证通过前不会进入可领取库存。同一域名的历史前缀会永久占用，删除邮箱不会让旧前缀再次生成；不同域名之间可以使用相同前缀。
• 不要发送 GPT 的 id_token、access_token、chatgpt_account_id，也不要调用 /api/gpt-accounts/report。

GET /api/export?pool_key=icloud_api&include_used=true
Authorization: Bearer mak_xxx

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

{"ids":[101,102,103]}

自有域名邮箱长期接码地址

域名邮箱导出行中的第二段就是可视化接码 URL，默认每 5 秒自动刷新并从 IMAP 重新取最新邮件，浏览器页面会显示最新一封完整邮件。其他注册项目需要结构化数据时，把路径 /mail/receiver 改为 /api/mail/receiver，按 3-5 秒轮询同一 URL；服务每次收到请求都会刷新收件箱后返回，不需要 GPTMail API Key。JSON 的 messages[] 每项包含 subject、from、body、body_text、folder 和 received_at。

性能配置：GPTMail 域名邮箱默认通过 Docker 内部 host.docker.internal:993 连接 Stalwart，TLS SNI 仍使用每个域名的 mail.<domain>。内部连接失败会自动回退到已配置的公网 IMAP 主机，因此不会因内部网络异常导致旧邮箱无法接码。新增域名不需要改代码，只需完成 DNS、证书、Catch-all 和 GPTMail 域名配置。

GET https://gptmail.passkissyou.online/api/mail/receiver?email=xxx%40wenas.online&receiver_token=...&domain=wenas.online&folders=inbox%2Cjunk&limit=20

{
  "ok": true,
  "email": "xxx@wenas.online",
  "count": 1,
  "messages": [{"subject":"Your verification code","from":"noreply@example.com","body":"完整邮件正文（链接保留）","folder":"inbox"}]
}

两个导出接口均返回 UTF-8 文本文件。API Key 仅能导出其所属用户、且已授权邮箱池中的原始导入格式；不会返回 /api/mail/code 临时租约链接。

域名邮箱领取仍使用兼容的 POST /api/mailboxes/reserve，传入对应的 pool_key（例如 domain_wenasmail_com）即可；旧客户端不传该字段时，原有邮箱池行为不变。

查看机器规格

pool_key = domain_<规范化域名>
category = new
POST /api/mailboxes/reserve
{
  "pool_key": "domain_wenasmail_com",
  "category": "new",
  "consume": false,
  "lease_seconds": 1800
}

curl -sk -u "$STALWART_AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"type":"domain","name":"wenas.online"}' \
  https://admin.passkissyou.online/api/principal

# 上一步成功后，才执行下面的账号请求

curl -sk -u "$STALWART_AUTH" \
  -H 'Content-Type: application/json' \
  -d '{
    "type":"individual",
    "name":"mailops-wenas-online",
    "description":"GPTMail wenas.online catch-all",
    "secrets":["生成的随机密码"],
    "emails":["mailops-wenas-online@wenas.online","@wenas.online"],
    "roles":["user"]
  }' https://admin.passkissyou.online/api/principal

POST /api/managed-domains/{id}/verify
POST /api/managed-domains/{id}/catchall
{
  "enabled": true,
  "imap_host": "mail.example.com",
  "imap_port": 993,
  "imap_username": "mailops-example-catchall",
  "imap_password": "同一个 Catch-all 密码",
  "imap_ssl": true
}
POST /api/managed-domains/{id}/generate
{"count":1000,"prefix_length":10,"prefix_charset":"lower_alnum"}

固定项不要改：IMAPS 端口 993、SSL、Catch-all 逻辑、状态要求。红色项每新增一个域名都要换成该域名自己的值。新增域名不需要改 Outlook、iCloud、Gmail 或多平台复用配置。

同一域名的历史前缀永久占用，删除后不会复用；不同域名可使用同名此前缀。

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

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

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

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

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