{ "name": "MailOps GPT/OpenAI Registration API", "version": "0.6-gpt", "route_family": "gpt_openai_legacy", "base_url": "https://gptmail.passkissyou.online", "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": "https://gptmail.passkissyou.online", "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": [ "GET /api/mailboxes/capabilities at startup when the UI needs provider/domain choices.", "POST /api/mailboxes/reserve with category=safe and consume=true. provider/domain/domains are optional strict GPT-only filters.", "If email is empty, stop the current batch or switch category.", "Submit the returned email to the GPT/OpenAI registration flow.", "Legacy workers may keep consume=true and query GET /api/mail/code by email only. New workers should use consume=false and retain the returned lease_token.", "Poll only that email with GET /api/mail/code until a code is found or the attempt times out. lease_token is optional for legacy compatibility and recommended for a current lease.", "On final timeout, POST /api/mailboxes/report-code with result=timeout and the lease_token when available. The first timeout records suspect status; repeated failures are required before isolation.", "After the registration attempt finishes, optionally POST /api/gpt-accounts/report." ], "endpoints": [ { "id": "mailbox_asset_import", "method": "POST", "path": "/api/accounts/import", "purpose": "Import production mailbox assets into the API key owner's mailbox pool. This endpoint never writes to the GPT account warehouse.", "auth": "Bearer API key", "body": { "text": {"type": "string", "required": true, "accepted_formats": [ "email----password----client_id----refresh_token----tag", "email----receiving_url----tag with format=icloud_api_v1", "email----receiving_url----tag with format=gmail_api_v1", "JSON Lines or JSON array with email/receiver.url/pool_key" ]}, "format": {"type": "string", "enum": ["", "icloud_api_v1", "gmail_api_v1"], "default": "", "required": false}, "auto_scan": {"type": "boolean", "default": false, "description": "false keeps new imports in category=new,status=new"}, "limit": {"type": "integer", "default": 20, "min": 1, "max": 200}, "concurrency": {"type": "integer", "default": 3, "min": 1, "max": 20} }, "url_receiver_rules": [ "gmail_api_v1 requires gmail.com or googlemail.com and stores pool_key=gmail_api with driver_key=gmail_api_html_v1.", "The receiving URL must be HTTPS, resolve publicly, and its hostname must be in MAILOPS_EXTERNAL_RECEIVER_ALLOWED_HOSTS. iCloud also supports mail.sayt.cloud/api/v1/access/{token}/mailboxes/{email}/view; the server requests refresh=1 JSON for that provider.", "The receiver starts pending and cannot be reserved until the background health check marks it verified." ], "success_response": {"ok": true, "parsed": 1, "added": 1, "updated": 0, "duplicates": 0, "errors": [], "auto_scan_started": false} }, { "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, "description": "true preserves the legacy immediate-consume flow. false creates a lease and returns lease_token for new workers."}, "lease_seconds": {"type": "integer", "default": 1800}, "pool_key": {"type": "string", "required": false, "description": "Optional exact pool: outlook_oauth, icloud_api, or gmail_api."}, "provider": {"type": "string", "required": false, "description": "Optional provider filter: icloud, outlook, hotmail, gmail, other. Future provider ids are accepted."}, "domain": {"type": "string", "required": false, "description": "Optional exact domain filter, for example icloud.com."}, "domains": {"type": "array", "items": {"type": "string"}, "required": false, "description": "Optional exact domain allow-list, for example [\"icloud.com\", \"me.com\", \"mac.com\"]."}, "domain_policy": {"type": "string", "enum": ["strict"], "default": "strict", "required": false, "description": "With any filter, no match returns no_available and never falls back to another provider/domain."} }, "success_response": { "ok": true, "email": "example@outlook.com", "lease_token": "", "request_id": "openai-register-thread-1", "consumed": true, "mailbox": {"email": "example@outlook.com", "domain": "outlook.com", "provider": "outlook", "category": "safe", "status": "safe", "code_health": "unknown"} }, "empty_response": { "ok": true, "email": "", "reason": "no_available" }, "filtered_empty_response": { "ok": false, "reason": "no_available", "message": "no available mailbox matched filters", "filters": {"category": "safe", "provider": "icloud", "domain": "", "domains": ["icloud.com", "me.com", "mac.com"], "domain_policy": "strict"} }, "compatibility": "All filter fields are optional. Omitting them preserves the prior allocation and empty response behavior. Filters apply only to this GPT/OpenAI reserve route; /api/reuse/v1/* is unchanged." }, { "id": "mailbox_capabilities", "method": "GET", "path": "/api/mailboxes/capabilities", "purpose": "Returns the GPT/OpenAI provider and domain catalog plus API-key scoped available counts for registration UIs.", "auth": "Bearer API key", "success_response": { "ok": true, "route_family": "gpt_openai", "filters_supported": {"provider": true, "domain": true, "domains": true, "pool_key": true, "strict_domain_policy": true}, "providers": [ {"id": "icloud", "label": "iCloud", "domains": ["icloud.com", "me.com", "mac.com"], "available": 120, "receiver_unavailable": 5, "needs_check": 2}, {"id": "gmail", "label": "Gmail", "domains": ["gmail.com", "googlemail.com"], "available": 20, "receiver_unavailable": 2, "needs_check": 1} ], "categories": [{"id": "safe", "label": "safe", "available": 120}] } }, { "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}, "lease_token": {"type": "string", "required": false, "description": "Optional. Legacy clients may query by email only. New clients should send the lease token returned by consume=false reserve; it authorizes miss accounting for that active lease."}, "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" }, "icloud_receiver_unavailable_response": { "ok": true, "found": false, "email": "example@icloud.com", "refreshed": false, "refresh_error": "receiver configuration unavailable", "reason": "receiver_unavailable", "code_health": "receiver_unavailable" } }, { "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 a final code timeout/no_code. A first timeout records suspect status; isolation requires repeated failures.", "body": { "email": {"type": "string", "required": true}, "result": {"type": "string", "enum": ["timeout", "no_code", "found"]}, "lease_token": {"type": "string", "required": false, "description": "Send the consume=false reservation token when available."}, "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='https://gptmail.passkissyou.online'\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()