{
  "name": "MailOps Multi-Platform Reuse API",
  "version": "0.5-reuse",
  "route_family": "multi_platform_reuse",
  "base_url": "http://ops.nanlizz.top",
  "separate_from": {
    "gpt_openai_docs": "/api-docs-gpt.html",
    "gpt_openai_spec": "/api-spec-gpt.json",
    "rule": "Non-OpenAI platform workers use /api/reuse/v1/* with an explicit platform. GPT/OpenAI workers stay on /api/mailboxes/*."
  },
  "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",
    "platform": "cursor",
    "lease_seconds": 1800,
    "keyword": "code,验证码,verification code,{platform}",
    "folders": "inbox,junk"
  },
  "recommended_flow": [
    "GET /api/reuse/v1/platforms if the client needs platform metadata.",
    "POST /api/reuse/v1/mail/reserve with platform, request_id, and lease_seconds.",
    "If email is empty, stop or switch platform strategy.",
    "Submit the returned email to the target platform and poll only that email with /api/mail/code.",
    "On success or possible target-side occupation, POST /api/reuse/v1/mail/mark-used with platform, email, lease_token, and account/detail data.",
    "Only when the target platform definitely did not occupy the email, POST /api/reuse/v1/mail/release with platform, email, and lease_token."
  ],
  "endpoints": [
    {
      "id": "reuse_platforms",
      "method": "GET",
      "path": "/api/reuse/v1/platforms",
      "purpose": "List configured reuse platforms for the current API key/user.",
      "recommended_for_allocation": false
    },
    {
      "id": "reuse_summary",
      "method": "GET",
      "path": "/api/reuse/v1/summary",
      "purpose": "Visual/debug summary of platform reuse availability and mailbox platform status.",
      "recommended_for_allocation": false,
      "warning": "Do not use summary to allocate mailboxes."
    },
    {
      "id": "reuse_reserve_mailbox",
      "method": "POST",
      "path": "/api/reuse/v1/mail/reserve",
      "purpose": "Reserve one mailbox for a target platform.",
      "recommended_for_multi_platform_allocation": true,
      "body": {
        "platform": {"type": "string", "required": true, "examples": ["cursor", "claude", "poe"]},
        "request_id": {"type": "string", "recommended": true},
        "lease_seconds": {"type": "integer", "default": 1800, "min": 60, "max": 86400},
        "search": {"type": "string", "required": false}
      },
      "success_response": {
        "ok": true,
        "platform": "cursor",
        "email": "legacy-used@outlook.com",
        "lease_token": "lease_xxx",
        "lease_expires_at": "2026-06-25T10:30:00.000Z",
        "consumed": false
      },
      "empty_response": {
        "ok": true,
        "platform": "cursor",
        "mailbox": null,
        "email": "",
        "reason": "no_available"
      }
    },
    {
      "id": "reuse_mark_used",
      "method": "POST",
      "path": "/api/reuse/v1/mail/mark-used",
      "purpose": "Confirm that the target platform consumed/registered the reserved mailbox.",
      "body": {
        "platform": {"type": "string", "required": true},
        "email": {"type": "string", "required": true},
        "lease_token": {"type": "string", "required": true},
        "login_email": {"type": "string", "required": false},
        "login_password": {"type": "string", "required": false},
        "status": {"type": "string", "default": "available"},
        "account": {"type": "object", "required": false},
        "detail": {"type": "object or string", "required": false}
      },
      "success_response": {
        "ok": true,
        "email": "legacy-used@outlook.com",
        "platform": "cursor",
        "status": "success"
      }
    },
    {
      "id": "reuse_release_mailbox",
      "method": "POST",
      "path": "/api/reuse/v1/mail/release",
      "purpose": "Release a reservation only when the target platform definitely did not occupy the mailbox.",
      "body": {
        "platform": {"type": "string", "required": true},
        "email": {"type": "string", "required": true},
        "lease_token": {"type": "string", "required": true},
        "reason": {"type": "string", "required": false}
      },
      "success_response": {
        "ok": true,
        "email": "legacy-used@outlook.com",
        "platform": "cursor",
        "released": true
      }
    },
    {
      "id": "get_mail_code",
      "method": "GET",
      "path": "/api/mail/code",
      "purpose": "Read the verification code for the reserved mailbox. Shared mail-reading endpoint, not a mailbox allocation endpoint."
    }
  ],
  "selection_rules": [
    "Skips unhealthy/no_code/invalid/error mailboxes.",
    "Requires refresh_token so /api/mail/code can read mail.",
    "Skips the same email/platform when status is reserved or success.",
    "Skips mailboxes that already reached the max successful platform count.",
    "For non-openai platforms, healthy legacy OpenAI-used mailboxes may be reused.",
    "OpenAI/GPT registration should use the GPT/OpenAI route instead of this route."
  ],
  "python_client": "import time, requests\nBASE='http://ops.nanlizz.top'\nKEY='mak_xxx'\nPLATFORM='cursor'\nH={'Authorization':f'Bearer {KEY}','Content-Type':'application/json'}\nr=requests.post(f'{BASE}/api/reuse/v1/mail/reserve',headers=H,json={'platform':PLATFORM,'request_id':'batch-001-worker-01-attempt-001','lease_seconds':1800},timeout=30).json()\nif not r.get('email'): raise RuntimeError(f'{PLATFORM} pool exhausted')\nemail=r['email']; lease=r['lease_token']\ndeadline=time.time()+180\nwhile time.time()<deadline:\n    code=requests.get(f'{BASE}/api/mail/code',headers=H,params={'email':email,'keyword':f'code,验证码,verification code,{PLATFORM}','limit':10,'folders':'inbox,junk'},timeout=30).json()\n    if code.get('found'):\n        break\n    time.sleep(8)\nelse:\n    requests.post(f'{BASE}/api/reuse/v1/mail/release',headers=H,json={'platform':PLATFORM,'email':email,'lease_token':lease,'reason':'code timeout before account created'},timeout=30)\n    raise RuntimeError('verification code timeout')\nrequests.post(f'{BASE}/api/reuse/v1/mail/mark-used',headers=H,json={'platform':PLATFORM,'email':email,'lease_token':lease,'login_email':'cursor-login@example.com','status':'available','account':{'batch_id':'batch-001'}},timeout=30).raise_for_status()"
}