GPT/OpenAI 注册路线 API

AI 快速接入

你要接入 MailOps 的 GPT/OpenAI 注册路线 API。

BASE_URL = "https://gptmail.passkissyou.online"
API_KEY = "mak_xxx"
CATEGORY = "safe"
CODE_KEYWORD = "code,验证码,verification code,OpenAI,ChatGPT,gpt"

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

固定流程:
1. 启动时可查询可用邮箱类型:
   GET {BASE_URL}/api/mailboxes/capabilities
2. 旧注册机领取邮箱，只能用:
   POST {BASE_URL}/api/mailboxes/reserve
   body: {"category":CATEGORY,"consume":true}
   新注册机如需租约，传 {"category":CATEGORY,"consume":false} 并保存 lease_token。
3. 若选择 iCloud/Gmail URL 池、Outlook 或自定义域名，额外传 provider/domain/domains/domain_policy=strict；需要强制 URL 池时再传 pool_key=icloud_api 或 pool_key=gmail_api；没有匹配库存绝不切换到其它域名。
4. 如果旧请求返回 email 为空，或筛选请求返回 reason=no_available，表示该库存耗尽，停止本轮注册。
5. 使用返回的 email 去 OpenAI/GPT 注册页面提交。
6. 等待 10-20 秒后查询验证码:
   GET {BASE_URL}/api/mail/code?email={email}&lease_token={lease_token}&keyword={CODE_KEYWORD}&limit=10&folders=inbox,junk
   旧注册机不带 lease_token 仍可按 email 查询。
7. found=false 时继续轮询同一个 email，不要重新领取新邮箱。
8. 最终超时无验证码:
   POST {BASE_URL}/api/mailboxes/report-code
   body: {"email":email,"lease_token":lease_token,"result":"timeout","detail":"180s no verification code"}
9. 注册结束后按需上报 GPT 账号:
   POST {BASE_URL}/api/gpt-accounts/report

禁止事项:
- 不要用 GET /api/mailboxes 分配邮箱，它只是查看列表。
- GPT/OpenAI 旧注册机不要接 /api/reuse/v1/*。
- 每个并发 worker 一次注册只领取一次邮箱，不能共享 email。
- 默认 consume=true，邮箱返回前已被服务器标记 used，不会再次从 safe 池发出。

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

生产邮箱导入

这是邮箱资产池导入，不是 GPT 账号导入。接口只把邮箱写入当前 API Key 所属用户的 new 分类；后续扫描或人工操作后再进入 safe。

导入 Gmail URL 收信邮箱:
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----batch-001",
  "auto_scan": false,
  "limit": 20,
  "concurrency": 3
}

Gmail URL 格式固定为 email----receiving_url----tag，仅接受 gmail.com/googlemail.com。系统会写入独立 gmail_api 池和 gmail_api_html_v1 驱动，不会修改现有 Gmail OAuth 或 Outlook/iCloud 数据。URL 必须是 HTTPS、可公开解析，且域名已经加入服务器 MAILOPS_EXTERNAL_RECEIVER_ALLOWED_HOSTS；健康检测通过前不会被领取。

iCloud URL 格式仍使用相同三段文本，但 format=icloud_api_v1。除 icloud-api.top 外，也支持 mail.sayt.cloud/api/v1/access/.../mailboxes/.../view；该地址会自动请求 refresh=1 JSON 并按邮件卡片解析。完整机器规格见 /api-spec-gpt.json。

接口明细

方法	路径	用途	是否用于分配
POST	`/api/accounts/import`	导入 Outlook OAuth、iCloud/Gmail URL 收信邮箱到 new 池	否
POST	`/api/mailboxes/reserve`	并发安全领取一个邮箱	是，推荐
GET	`/api/mailboxes/capabilities`	查询邮箱类型、域名与当前可用库存	否，给 WebUI 配置用
GET	`/api/mail/code`	读取指定邮箱验证码	否
GET	`/api/mail/{email}`	兼容旧 MailManage 读码路径	否
POST	`/api/mailboxes/report-code`	上报 timeout/no_code；连续失败才隔离	否
POST	`/api/mailboxes/mark-used`	`consume=false` 模式下手动确认邮箱已用	否
POST	`/api/mailboxes/release`	`consume=false` 模式下释放未占用邮箱	否
GET	`/api/mailboxes`	列表/排查/导出	否，禁止用它分配
POST	`/api/gpt-accounts/report`	注册结束后上报 GPT 账号仓库	否

领取邮箱

先查询注册机可选择的类型:
GET /api/mailboxes/capabilities
Authorization: Bearer mak_xxx

领取任意旧版兼容邮箱:
POST /api/mailboxes/reserve
Authorization: Bearer mak_xxx
Content-Type: application/json

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

严格领取 Gmail URL 池:
POST /api/mailboxes/reserve

{
  "category": "safe",
  "consume": true,
  "lease_seconds": 1800,
  "provider": "gmail",
  "domains": ["gmail.com", "googlemail.com"],
  "pool_key": "gmail_api",
  "domain_policy": "strict",
  "request_id": "openai-register-thread-1"
}

成功:
{
  "ok": true,
  "email": "example@gmail.com",
  "lease_token": "",
  "request_id": "openai-register-thread-1",
  "mailbox": {
    "email": "example@gmail.com",
    "domain": "gmail.com",
    "provider": "gmail",
    "category": "safe",
    "status": "safe",
    "code_health": "unknown"
  }
}

严格筛选无库存:
{
  "ok": false,
  "reason": "no_available",
  "message": "no available mailbox matched filters",
  "filters": {"category":"safe","provider":"gmail","domain":"","domains":["gmail.com","googlemail.com"],"domain_policy":"strict"}
}

新增 provider、domain、domains、domain_policy 全部可选。不传时完全沿用旧版领取逻辑和空库存响应；传任意筛选条件时固定为 strict，无匹配不会自动回退到其它邮箱类型。该能力仅作用于 POST /api/mailboxes/reserve，不改变 /api/reuse/v1/*。

读取验证码

GET /api/mail/code?email=example@outlook.com&lease_token=领取时返回的lease_token&keyword=code,验证码,verification code,OpenAI,ChatGPT,gpt&limit=10&folders=inbox,junk

找到:
{
  "ok": true,
  "found": true,
  "email": "example@outlook.com",
  "code": "123456"
}

暂未找到:
{
  "ok": true,
  "found": false,
  "email": "example@outlook.com"
}

轮询时只轮询本次领取的邮箱。lease_token 是可选兼容参数：旧注册机仅传 email 仍可查询；新注册机使用 consume=false 时应携带 reserve 返回的 token。不要因为一次 found=false 就重新领取新邮箱。

iCloud/Gmail URL receiver 不可读取时，接口仍返回兼容的 ok=true/found=false，并额外返回 reason=receiver_unavailable、code_health=receiver_unavailable。该邮箱会自动隔离，后续 reserve 不会再返回它。

验证码失败上报

POST /api/mailboxes/report-code
Authorization: Bearer mak_xxx
Content-Type: application/json

{
  "email": "example@outlook.com",
  "result": "timeout",
  "lease_token": "consume=false 时 reserve 返回的 token",
  "detail": "180s no verification code"
}

第一次 timeout 只记录 suspect，不会永久隔离；达到连续失败阈值后才进入 no_code。轮询未命中也要求达到次数和持续时间两个条件才隔离。

GPT 账号上报

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

{
  "result": "success",
  "dedupe_key": "batch-001:login@example.com",
  "login_email": "login@example.com",
  "login_password": "optional",
  "mailbox_email": "example@outlook.com",
  "detail": {
    "batch_id": "batch-001",
    "worker": "worker-01"
  }
}

dedupe_key 建议用批次 + 登录邮箱，重复上报会更新同一条记录，不会创建重复账号。

Python 示例

import time
import requests

BASE = "https://gptmail.passkissyou.online"
KEY = "mak_xxx"
KEYWORD = "code,验证码,verification code,OpenAI,ChatGPT,gpt"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

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

if not reserved.get("email"):
    raise RuntimeError("GPT 邮箱池耗尽")

email = reserved["email"]

# 把 email 提交给 OpenAI/GPT 注册页面后，只轮询这个 email。
deadline = time.time() + 180
while time.time() < deadline:
    code = requests.get(
        f"{BASE}/api/mail/code",
        headers=HEADERS,
        params={"email": email, "keyword": KEYWORD, "limit": 10, "folders": "inbox,junk"},
        timeout=30,
    ).json()
    if code.get("found"):
        print(email, code.get("code"))
        break
    time.sleep(8)
else:
    requests.post(
        f"{BASE}/api/mailboxes/report-code",
        headers=HEADERS,
        json={"email": email, "result": "timeout", "detail": "180s no verification code"},
        timeout=30,
    )
    raise RuntimeError("验证码超时")