{
  "name": "MailOps GPT/OpenAI Registration API",
  "version": "0.5-gpt",
  "route_family": "gpt_openai_legacy",
  "base_url": "http://ops.nanlizz.top",
  "separate_from": {
    "multi_platform_docs": "/api-docs-reuse.html",
    "multi_platform_spec": "/api-spec-reuse.json",
    "rule": "GPT/OpenAI registration workers keep using /api/mailboxes/* and must not switch to /api/reuse/v1/*."
  },
  "auth": {
    "type": "bearer",
    "header": "Authorization",
    "format": "Bearer mak_xxx",
    "content_type": "application/json"
  },
  "recommended_config": {
    "base_url": "http://ops.nanlizz.top",
    "api_key": "mak_xxx",
    "category": "safe",
    "consume": true,
    "keyword": "code,验证码,verification code,OpenAI,ChatGPT,gpt",
    "folders": "inbox,junk",
    "poll_interval_seconds": 8,
    "poll_timeout_seconds": 180
  },
  "recommended_flow": [
    "POST /api/mailboxes/reserve with category=safe and consume=true.",
    "If email is empty, stop the current batch or switch category.",
    "Submit the returned email to the GPT/OpenAI registration flow.",
    "Poll only that email with GET /api/mail/code until a code is found or the attempt times out.",
    "On final timeout, POST /api/mailboxes/report-code with result=timeout.",
    "After the registration attempt finishes, optionally POST /api/gpt-accounts/report."
  ],
  "endpoints": [
    {
      "id": "reserve_mailbox",
      "method": "POST",
      "path": "/api/mailboxes/reserve",
      "purpose": "Allocate one mailbox for a GPT/OpenAI registration worker with database-level duplicate prevention.",
      "recommended_for_allocation": true,
      "body": {
        "category": {"type": "string", "default": "safe"},
        "consume": {"type": "boolean", "default": true},
        "lease_seconds": {"type": "integer", "default": 1800}
      },
      "success_response": {
        "ok": true,
        "email": "example@outlook.com",
        "category": "used",
        "used": 1
      },
      "empty_response": {
        "ok": true,
        "email": "",
        "reason": "empty"
      }
    },
    {
      "id": "get_mail_code",
      "method": "GET",
      "path": "/api/mail/code",
      "purpose": "Read the cached verification code for the reserved mailbox.",
      "query": {
        "email": {"type": "string", "required": true},
        "keyword": {"type": "string", "default": "code,验证码,verification code,OpenAI,ChatGPT,gpt"},
        "limit": {"type": "integer", "default": 10},
        "folders": {"type": "string", "default": "inbox,junk"}
      },
      "success_response": {
        "ok": true,
        "found": true,
        "email": "example@outlook.com",
        "code": "123456"
      },
      "not_found_response": {
        "ok": true,
        "found": false,
        "email": "example@outlook.com"
      }
    },
    {
      "id": "get_mail_code_compat",
      "method": "GET",
      "path": "/api/mail/{email}",
      "purpose": "Compatibility alias for older MailManage clients. New clients should use /api/mail/code."
    },
    {
      "id": "report_code_result",
      "method": "POST",
      "path": "/api/mailboxes/report-code",
      "purpose": "Report final code timeout/no_code so unhealthy mailboxes are quarantined.",
      "body": {
        "email": {"type": "string", "required": true},
        "result": {"type": "string", "enum": ["timeout", "no_code", "found"]},
        "detail": {"type": "string", "required": false}
      }
    },
    {
      "id": "mark_used",
      "method": "POST",
      "path": "/api/mailboxes/mark-used",
      "purpose": "Manual confirmation for consume=false mode."
    },
    {
      "id": "release_mailbox",
      "method": "POST",
      "path": "/api/mailboxes/release",
      "purpose": "Release a consume=false reservation when the target did not occupy the email."
    },
    {
      "id": "list_mailboxes",
      "method": "GET",
      "path": "/api/mailboxes",
      "purpose": "List/search mailboxes for viewing and diagnostics only.",
      "recommended_for_allocation": false,
      "warning": "Never allocate registration workers from GET /api/mailboxes."
    },
    {
      "id": "report_gpt_account",
      "method": "POST",
      "path": "/api/gpt-accounts/report",
      "purpose": "Report GPT account results to the account warehouse after a registration attempt.",
      "body": {
        "result": {"type": "string", "enum": ["success", "partial", "failed"]},
        "dedupe_key": {"type": "string", "recommended": true},
        "login_email": {"type": "string", "required": false},
        "mailbox_email": {"type": "string", "required": false},
        "detail": {"type": "object", "required": false}
      }
    }
  ],
  "python_client": "import time, requests\nBASE='http://ops.nanlizz.top'\nKEY='mak_xxx'\nKEYWORD='code,验证码,verification code,OpenAI,ChatGPT,gpt'\nH={'Authorization':f'Bearer {KEY}','Content-Type':'application/json'}\nr=requests.post(f'{BASE}/api/mailboxes/reserve',headers=H,json={'category':'safe','consume':True},timeout=30).json()\nif not r.get('email'): raise RuntimeError('GPT mailbox pool exhausted')\nemail=r['email']\ndeadline=time.time()+180\nwhile time.time()<deadline:\n    code=requests.get(f'{BASE}/api/mail/code',headers=H,params={'email':email,'keyword':KEYWORD,'limit':10,'folders':'inbox,junk'},timeout=30).json()\n    if code.get('found'):\n        print(email, code.get('code'))\n        break\n    time.sleep(8)\nelse:\n    requests.post(f'{BASE}/api/mailboxes/report-code',headers=H,json={'email':email,'result':'timeout','detail':'180s no verification code'},timeout=30)\n    raise RuntimeError('verification code timeout')"
}