API 文档

把下面这段直接给 AI 或自动化脚本即可。它包含最小配置、固定调用顺序和禁止事项。

你要接入 MailOps 邮箱池 API。

BASE_URL = "https://gptmail.passkissyou.online"
API_KEY = "mak_xxx"
CATEGORY = "safe"
CONCURRENCY = 5  # 注册机并发数；每个 worker 都必须单独调用 reserve
CODE_KEYWORD = "code,验证码,verification code,OpenAI,ChatGPT,gpt"

所有请求都带:
Authorization: Bearer API_KEY
Content-Type: application/json

固定流程:
1. 领取邮箱，只能用:
   POST {BASE_URL}/api/mailboxes/reserve
   body: {"category":CATEGORY,"consume":true}
2. 如果返回 email 为空，表示邮箱池耗尽，停止本轮注册。
3. 使用返回的 email 去目标系统提交绑定邮箱。
4. 等待 10-20 秒后查询验证码:
   GET {BASE_URL}/api/mail/code?email={email}&keyword={CODE_KEYWORD}&limit=10&folders=inbox,junk
5. 如果 found=false，继续间隔轮询，不要重新领取新邮箱，除非本次注册流程已经判定失败。

重要限制:
- 不要用 GET /api/mailboxes 来分配邮箱，它只是查看列表。
- 并发注册必须用 reserve；并发数不通过 API 传，而是在注册机线程/任务数里配置。
- 每个并发 worker 一次注册只领取一次邮箱，不能多个 worker 共享同一个 email。
- 默认 consume=true，邮箱返回前已被服务器标记 used，不会再次从 safe 池发出。
- 验证码关键词优先填 code/验证码/verification code，其次才是 OpenAI/ChatGPT/gpt。
- 本地 used_emails.json 只能当日志，不是防重复主逻辑。

机器可读规格：/api-spec.json

1. 管理员登录控制台，导入 Outlook/Hotmail 资产，并完成可读性扫描分类。
2. 确认要消费的邮箱在目标分类里，默认推荐 safe。
3. 进入 API 中心生成 mak_... API Key。Key 只完整显示一次，必须立即保存到注册机配置里。
4. 注册机配置 base_url、api_key、category、keyword、并发数和验证码轮询参数。
5. 每个注册 worker 都通过 POST /api/mailboxes/reserve 领取唯一邮箱，不要用列表接口分配邮箱。
6. 提交绑定邮件后，只对刚领取的这个邮箱调用 GET /api/mail/code 轮询验证码。
7. 最终收不到码时，调用 POST /api/mailboxes/report-code 上报 timeout，后台会把邮箱隔离到 no_code。

先确定注册机在哪里运行，再选择 base_url。这个值最容易填错。

所有 API 请求都要携带：

Authorization: Bearer mak_xxx
Content-Type: application/json

浏览器控制台登录用账号密码；注册机和外部脚本只使用 Bearer API Key，不需要也不应该处理登录 Cookie。

注册机推荐配置模板：

{
  "email_provider": "mailmanage",
  "mailmanage": {
    "base_url": "https://gptmail.passkissyou.online",
    "api_key": "mak_xxx",
    "category": "safe",
    "keyword": "code,验证码,verification code,OpenAI,ChatGPT,gpt",
    "folders": "inbox,junk",
    "consume": true,
    "poll_interval_seconds": 8,
    "poll_timeout_seconds": 180
  },
  "concurrency": 5
}

按当前后台接入 MailManage 时，注册机只需要填写下面这些项。邮箱账号、client_id、refresh_token 只导入到本后台，不要填进注册机。

如果你之前按原 MailManage 页面配置过注册机，迁移到本地后台时主要差异如下。

并发注册时，用领取即消费模式。邮箱返回前，后台已经把它改成 used，所以页面不刷新、本地 used 文件写入失败、程序重启，都不会重复发出同一个 safe 邮箱。

POST /api/mailboxes/reserve

{"category":"safe","consume":true}

{
  "ok": true,
  "email": "user@hotmail.com",
  "consumed": true,
  "mailbox": {
    "email": "user@hotmail.com",
    "category": "used",
    "status": "used",
    "used": 1,
    "reserved": 0
  }
}

然后轮询验证码：

GET /api/mail/code?email=user@hotmail.com&keyword=code,验证码,verification code,OpenAI,ChatGPT,gpt&limit=10&folders=inbox,junk

只要注册机用 POST /api/mailboxes/reserve 且 consume=true，邮箱会在返回给注册机之前自动离开 safe 池。这个动作发生在数据库事务里，不依赖网页刷新，也不依赖本地 used_emails.json。

如果你开启 consume=false 租约模式，邮箱不会立刻变成 used，而是进入 reserved 状态；成功后必须调用 mark-used，失败后按策略调用 release。高并发注册默认不要用租约模式。

并发不是填给 MailOps API 的参数，而是注册机自己的 worker/线程/任务数量。MailOps 只负责保证每个 worker 通过 reserve 拿到的邮箱唯一。

worker_1 -> POST /api/mailboxes/reserve -> email A -> 只轮询 email A 的验证码
worker_2 -> POST /api/mailboxes/reserve -> email B -> 只轮询 email B 的验证码
worker_3 -> POST /api/mailboxes/reserve -> email C -> 只轮询 email C 的验证码

不要先 GET /api/mailboxes 拉一批邮箱再在本地分配；多进程、多机器或重启时很容易重复。所有并发 worker 都必须即时调用 POST /api/mailboxes/reserve。

关键词不是最终验证码，验证码仍然由系统从邮件正文里提取 4-8 位数字。关键词只是先筛选“哪封邮件可能是验证码邮件”。

推荐:
GET /api/mail/code?email=user@hotmail.com&keyword=code,验证码,verification code,OpenAI,ChatGPT,gpt&limit=10&folders=inbox,junk

兼容旧配置:
GET /api/mail/code?email=user@hotmail.com&keyword=gpt&limit=10

POST /api/mailboxes/reserve

curl -X POST "https://gptmail.passkissyou.online/api/mailboxes/reserve" ^
  -H "Authorization: Bearer mak_xxx" ^
  -H "Content-Type: application/json" ^
  -d "{\"category\":\"safe\",\"consume\":true}"

无可用邮箱时：

{"ok":true,"mailbox":null,"email":"","reason":"no_available","error":"no available mailbox"}

如果你想“失败后释放回池”，可以关闭领取即消费。这个模式会返回 lease_token，成功后 mark-used，失败后 release。高并发注册默认不建议用它，因为失败释放策略要由调用方管理。

POST /api/mailboxes/reserve

{"category":"safe","consume":false,"lease_seconds":1800}

POST /api/mailboxes/mark-used

{"email":"user@hotmail.com","lease_token":"returned_token"}

POST /api/mailboxes/release

{"email":"user@hotmail.com","lease_token":"returned_token"}

注册机如何知道失败：Phase2 绑定/上传结束后会得到 oauth_result.ok。成功时调用 mark-used；失败时如果开启“绑定失败释放回 safe 池”，注册机会调用 release。默认关闭失败回收，因为某些失败代表邮箱本身不可用或已经注册，回池后可能反复失败。若进程异常退出没有 release，租约到期后后台会自动释放，默认 1800 秒。

GET /api/mail/code?email=user@hotmail.com&keyword=code,验证码,verification code,OpenAI,ChatGPT,gpt&limit=10&folders=inbox,junk

兼容原站旧文档写法：GET /api/mail/user@hotmail.com&keyword=gpt&limit=10。新项目推荐继续使用上面的标准 query 写法。

curl -H "Authorization: Bearer mak_xxx" "https://gptmail.passkissyou.online/api/mail/code?email=user@hotmail.com&keyword=code,验证码,verification code,OpenAI,ChatGPT,gpt&limit=10&folders=inbox,junk"

每次 found=false 都会被后台记为一次真实收码未命中。默认 6 次未命中或连续 120 秒仍没有验证码时，后台自动把邮箱标记为 no_code，从后续 safe 领取池排除。

{
  "ok": true,
  "email": "user@hotmail.com",
  "code": "123456",
  "found": true,
  "category": "used",
  "refreshed": true,
  "refresh_error": "",
  "code_health": "healthy",
  "poll_count": 0,
  "quarantined": false,
  "message": {
    "subject": "...",
    "from_addr": "...",
    "body_preview": "..."
  }
}

扫描历史邮件不能证明邮箱未来一定能收到验证码。可靠判定来自真实注册发码：如果多次轮询收件箱和垃圾箱仍没有验证码，后台会自动隔离；注册机最终超时时仍应上报一次，便于立即写入失败原因。

POST /api/mailboxes/report-code
{"email":"user@hotmail.com","result":"timeout","detail":"300s 内未收到验证码"}

隔离后的邮箱会显示在 no_code 分类；普通 safe 查询和 reserve 领取会自动跳过。

GET /api/mailboxes 只用于查看，不用于并发分配。默认排除 used=1、reserved=1 和 no_code 收码异常邮箱。

GET /api/mailboxes?category=safe&page=1&limit=100
GET /api/mailboxes?category=used
GET /api/mailboxes?search=hotmail&include_used=1&include_reserved=1

import time
import requests

BASE_URL = "https://gptmail.passkissyou.online"
API_KEY = "mak_xxx"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

r = requests.post(
    f"{BASE_URL}/api/mailboxes/reserve",
    headers=HEADERS,
    json={"category": "safe", "consume": True},
    timeout=30,
).json()

if not r.get("email"):
    raise RuntimeError("没有可用邮箱")

email = r["email"]

# 这里提交绑定邮箱给目标系统，然后等待邮件进入缓存
time.sleep(15)

code = requests.get(
    f"{BASE_URL}/api/mail/code",
    headers=HEADERS,
    params={"email": email, "keyword": "code,验证码,verification code,OpenAI,ChatGPT,gpt", "limit": 10, "folders": "inbox,junk"},
    timeout=30,
).json()

print(email, code.get("code"))