{"components":{"parameters":{"address":{"description":"Inbox address to operate on. Required for JWT / API key callers; ignored for temp tokens (the token is bound to one inbox).\n","in":"query","name":"address","schema":{"format":"email","type":"string"}},"limit":{"description":"Page size (handler-specific default and max apply).","in":"query","name":"limit","schema":{"minimum":1,"type":"integer"}},"messageId":{"description":"Inbucket message ID.","in":"path","name":"id","required":true,"schema":{"type":"string"}},"offset":{"description":"Zero-based item offset for pagination.","in":"query","name":"offset","schema":{"minimum":0,"type":"integer"}},"shareToken":{"description":"Public mailbox share token from the share link.","in":"path","name":"token","required":true,"schema":{"type":"string"}}},"responses":{"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Invalid input."},"Conflict":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Resource state conflict (e.g. address already in use)."},"Created":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Resource created; data described in the endpoint summary."},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Authenticated but not allowed."},"NoContent":{"description":"Success with no body."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Resource not found."},"OK":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Success envelope. See the endpoint summary/description for the data shape."},"RateLimited":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"$ref":"#/components/schemas/QuotaExhaustedEnvelope"}]}}},"description":"Too many requests. `Retry-After` header included. Two variants share this status: (1) transient rate limiting (token bucket / burst guard) — back off for `Retry-After` seconds and retry; (2) quota exhaustion (`errorCode: quota_exhausted`, see QuotaExhaustedEnvelope) — the plan API call quota is used up; retrying before `resetAt` will keep returning 429. Purchase a call pack or upgrade the plan to resume immediately.\n"},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Missing or invalid credentials."}},"schemas":{"Attachment":{"properties":{"contentId":{"type":"string"},"contentType":{"type":"string"},"disposition":{"type":"string"},"downloadUrl":{"description":"Relative /serve/... URL. For temp tokens a ?token= query is appended.","type":"string"},"filename":{"type":"string"},"id":{"type":"string"},"size":{"type":"integer"}},"type":"object"},"CreateAccountRequest":{"description":"All fields optional; server picks a public domain and generates a prefix when omitted.","properties":{"address":{"deprecated":true,"description":"Legacy prefix field; may include a domain (`user@domain`) which must match `domain`.","type":"string"},"autoDomainStrategy":{"description":"Domain auto-pick strategy hint for API keys.","type":"string"},"domain":{"description":"Target domain. Mutually exclusive with wildcardRuleId.","type":"string"},"localPart":{"description":"Preferred prefix field (1-64 chars, alphanumeric/dot/underscore/hyphen).","type":"string"},"password":{"description":"Accepted for DuckMail compatibility; ignored (temp inboxes are passwordless).","type":"string"},"subdomain":{"description":"Wildcard child-domain label; requires domain or wildcardRuleId (or the /accounts/wildcard endpoint).","type":"string"},"subdomainLabel":{"description":"Alias of subdomain.","type":"string"},"wildcardRuleId":{"description":"Create under a wildcard rule (owner/API-key scoped).","type":"string"}},"type":"object"},"CreateAccountResponse":{"properties":{"address":{"type":"string"},"anonQuota":{"description":"Anonymous-creation quota hint (only for anonymous web-bridge callers).","type":"object"},"createdAt":{"format":"date-time","type":"string"},"domain":{"type":"string"},"expiresAt":{"format":"date-time","type":["string","null"]},"id":{"type":"string"},"inboxType":{"type":"string"},"isActive":{"type":"boolean"},"mode":{"enum":["fixed","wildcard"],"type":"string"},"source":{"type":"string"},"subdomain":{"type":"string"},"token":{"description":"Temp-inbox bearer token for the temp-token auth scheme.","type":"string"}},"type":"object"},"Domain":{"properties":{"createdAt":{"format":"date-time","type":"string"},"dnsLastSyncAt":{"format":"date-time","type":"string"},"dnsLastSyncStatus":{"type":"string"},"dnsRecords":{"description":"Raw DNS record JSON blob."},"dnsServiceConnectionId":{"type":"string"},"dnsSyncMode":{"type":"string"},"domain":{"type":"string"},"id":{"type":"string"},"isCnameValid":{"type":"boolean"},"isMxValid":{"type":"boolean"},"isPublic":{"type":"boolean"},"isVerified":{"type":"boolean"},"lastDnsCheckAt":{"format":"date-time","type":"string"},"ownerId":{"type":"string"},"sourceType":{"type":"string"},"sourceZoneName":{"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"verificationToken":{"type":"string"},"verifiedAt":{"format":"date-time","type":"string"}},"type":"object"},"EmailAddress":{"properties":{"address":{"type":"string"},"name":{"type":"string"}},"type":"object"},"Envelope":{"description":"Standard response envelope shared by every JSON endpoint.","properties":{"data":{"description":"Payload; omitted on most errors."},"error":{"description":"Localized human-readable error (zh/en via Accept-Language / X-Locale). Empty on success.","type":"string"},"errorCode":{"description":"Stable machine-readable error code (see GET /error-codes). Empty on success.","type":"string"},"success":{"type":"boolean"}},"required":["success"],"type":"object"},"ErrorEnvelope":{"description":"Error variant of the envelope.","properties":{"error":{"type":"string"},"errorCode":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error"],"type":"object"},"MessageDetail":{"description":"Full message content (GET /messages/{id}).","properties":{"attachments":{"items":{"$ref":"#/components/schemas/Attachment"},"type":"array"},"bcc":{"items":{"type":"string"},"type":"array"},"cc":{"items":{"type":"string"},"type":"array"},"createdAt":{"format":"date-time","type":"string"},"from":{"$ref":"#/components/schemas/EmailAddress"},"hasAttachments":{"type":"boolean"},"html":{"items":{"type":"string"},"type":"array"},"id":{"type":"string"},"inboxId":{"type":"string"},"intro":{"type":"string"},"messageId":{"description":"Raw RFC 5322 Message-ID header (with angle brackets).","type":"string"},"seen":{"type":"boolean"},"size":{"type":"integer"},"subject":{"type":"string"},"text":{"type":"string"},"to":{"items":{"$ref":"#/components/schemas/EmailAddress"},"type":"array"}},"type":"object"},"MessageListItem":{"description":"Header-level message summary (list view; attachments not parsed).","properties":{"createdAt":{"format":"date-time","type":"string"},"from":{"$ref":"#/components/schemas/EmailAddress"},"hasAttachments":{"description":"Always false in list view (bodies are not parsed).","type":"boolean"},"id":{"type":"string"},"inboxId":{"description":"Compat duplicate of inbox_id.","type":"string"},"inbox_id":{"type":"string"},"seen":{"type":"boolean"},"size":{"type":"integer"},"subject":{"type":"string"},"to":{"items":{"$ref":"#/components/schemas/EmailAddress"},"type":"array"}},"type":"object"},"Plan":{"properties":{"description":{"type":"string"},"features":{"items":{"type":"string"},"type":"array"},"id":{"type":"string"},"isActive":{"type":"boolean"},"maxApiCallsDaily":{"type":"integer"},"maxApiCallsMonthly":{"type":"integer"},"maxApiCallsWeekly":{"type":"integer"},"maxApiKeys":{"type":"integer"},"maxAttachmentBytes":{"type":"integer"},"maxDomains":{"type":"integer"},"maxExternalSyncMessages":{"description":"Envelope retention cap PER linked external mailbox (封/账号). The sync engine keeps the newest N envelopes per account and evicts older index rows automatically.\n","type":"integer"},"maxInboxes":{"type":"integer"},"maxMessagesPerDay":{"type":"integer"},"maxRps":{"type":"integer"},"maxSubdomainDepth":{"type":"integer"},"maxWebhooks":{"type":"integer"},"maxWildcardRules":{"type":"integer"},"name":{"type":"string"},"priceMonthly":{"type":"number"},"retentionDays":{"type":"integer"},"sortOrder":{"type":"integer"},"storageBytes":{"type":"integer"}},"type":"object"},"QuotaExhaustedEnvelope":{"description":"Quota circuit breaker 429 variant (errorCode `quota_exhausted`): returned when the account's plan API call quota (daily / weekly / monthly) is confirmed exhausted and no purchased call-pack credits remain. Further API-usage requests are rejected immediately until the quota period resets or a purchase restores capacity. Response headers: `Retry-After` (seconds until reset) and `X-RateLimit-Reset` (reset unix timestamp). Web console (JWT) requests are never circuit-broken, so users can always sign in to upgrade or buy packs.\n","properties":{"error":{"description":"Localized message (zh/en via Accept-Language / X-Locale).","type":"string"},"errorCode":{"const":"quota_exhausted","type":"string"},"resetAt":{"description":"When the quota resets, ISO 8601 in business timezone (Asia/Shanghai, +08:00).","format":"date-time","type":"string"},"success":{"const":false,"type":"boolean"},"upgrade":{"description":"Absolute URLs to restore capacity immediately.","properties":{"callPacks":{"description":"Call pack purchase page.","format":"uri","type":"string"},"pricing":{"description":"Plan upgrade page.","format":"uri","type":"string"}},"type":"object"}},"required":["success","error","errorCode","resetAt","upgrade"],"type":"object"},"TempAccount":{"description":"Temp inbox profile (GET /accounts/me, GET /accounts/{id}).","properties":{"address":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"expiresAt":{"format":"date-time","type":["string","null"]},"id":{"type":"string"},"inboxType":{"enum":["temp","persistent"],"type":"string"},"isActive":{"type":"boolean"},"messageCount":{"type":"integer"},"source":{"enum":["web","api"],"type":"string"}},"type":"object"}},"securitySchemes":{"apiKey":{"description":"API key (`AC-` prefix) created from the dashboard. Also accepted as `Authorization: Bearer AC-...`.","in":"header","name":"X-API-Key","type":"apiKey"},"bearerAuth":{"description":"JWT access token via `Authorization: Bearer \u003caccess_token\u003e`.","scheme":"bearer","type":"http"},"cookieAuth":{"description":"HttpOnly JWT cookie set by /auth/login (web console sessions).","in":"cookie","name":"yyds_access_token","type":"apiKey"},"tempToken":{"description":"Short-lived temp-inbox token returned by POST /accounts and POST /token. Only valid for the temp-inbox surface (/accounts/me, /accounts/{id}, /messages*, /sources/{id}).","scheme":"bearer","type":"http"}}},"info":{"contact":{"email":"xiaolajiaoyyds@gmail.com","name":"YYDS Mail"},"description":"YYDS Mail is a receive-only email asset platform: temporary inboxes,\ncustom domains, wildcard subdomains, API keys, webhooks and billing.\n\nAll JSON endpoints share one envelope:\n`{ \"success\": bool, \"data\": ..., \"error\": \"...\", \"errorCode\": \"...\" }`.\nPrefer `errorCode` (stable, machine-readable) over the localized `error`\ntext. The full errorCode catalog is served at `GET /v1/error-codes`.\n\nRate limits: anonymous requests are IP rate-limited; authenticated\nrequests are limited by plan tier. 429 responses include `Retry-After`.\nWhen the plan API call quota is exhausted, 429 carries\n`errorCode: quota_exhausted` plus `resetAt` and `upgrade` links —\ndo not retry before `resetAt` (see QuotaExhaustedEnvelope).\n","title":"YYDS Mail API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/accounts":{"post":{"description":"DuckMail-compatible creation endpoint. Anonymous browser creation is restricted to the official web bridge; API callers authenticate with an API key or JWT. Response includes a temp token bound to the inbox.\n","operationId":"createAccount","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccountRequest"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/CreateAccountResponse"}},"type":"object"}]}}},"description":"data = created temp inbox + token."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Create a temporary inbox","tags":["Accounts"]}},"/accounts/me":{"get":{"description":"Temp-token only; returns the inbox bound to the presented token.","operationId":"getAccountMe","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/TempAccount"}},"type":"object"}]}}},"description":"data = TempAccount."},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"tempToken":[]}],"summary":"Current temp inbox profile","tags":["Accounts"]}},"/accounts/wildcard":{"post":{"description":"Forces wildcard mode. Requires authentication (JWT / API key). When subdomain is omitted, the server uses the key default or allocates a random child domain.\n","operationId":"createWildcardAccount","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccountRequest"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/CreateAccountResponse"}},"type":"object"}]}}},"description":"data = created inbox (mode = wildcard) + token."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Create a temp inbox under a wildcard child domain","tags":["Accounts"]}},"/accounts/{id}":{"delete":{"description":"Temp tokens may only delete their own inbox; JWT / API key (write) callers may delete temp inboxes they own. Persistent inboxes use DELETE /me/inboxes/{id}.","operationId":"deleteAccount","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Inbox deactivated (no body)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"tempToken":[]},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Deactivate a temp inbox","tags":["Accounts"]},"get":{"deprecated":true,"description":"Deprecated read alias — use the canonical GET /inboxes/{id} instead (same handler, identical response). Responses carry Deprecation and Link successor-version headers. The alias remains available for a 12-month transition window.\n","operationId":"getAccountById","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/TempAccount"}},"type":"object"}]}}},"description":"data = TempAccount."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"tempToken":[]},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Get temp inbox by ID (legacy alias of GET /inboxes/{id})","tags":["Accounts"]}},"/admin/access-blocks":{"post":{"operationId":"adminUpsertAccessBlock","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Upsert Access Block (internal)","tags":["Admin"],"x-internal":true}},"/admin/access-blocks/{id}":{"patch":{"operationId":"adminUpdateAccessBlock","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Update Access Block (internal)","tags":["Admin"],"x-internal":true}},"/admin/access-blocks/{id}/release":{"post":{"operationId":"adminReleaseAccessBlock","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Release Access Block (internal)","tags":["Admin"],"x-internal":true}},"/admin/announcements":{"get":{"operationId":"adminListAnnouncements","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Announcements (internal)","tags":["Admin"],"x-internal":true},"post":{"operationId":"adminCreateAnnouncement","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Create Announcement (internal)","tags":["Admin"],"x-internal":true}},"/admin/announcements/{id}":{"delete":{"operationId":"adminDeleteAnnouncement","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Delete Announcement (internal)","tags":["Admin"],"x-internal":true},"patch":{"operationId":"adminUpdateAnnouncement","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Update Announcement (internal)","tags":["Admin"],"x-internal":true}},"/admin/articles":{"get":{"operationId":"adminListArticles","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Articles (internal)","tags":["Admin"],"x-internal":true},"post":{"operationId":"adminCreateArticle","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Create Article (internal)","tags":["Admin"],"x-internal":true}},"/admin/articles/upload-image":{"post":{"operationId":"adminUploadArticleImage","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Upload Article Image (internal)","tags":["Admin"],"x-internal":true}},"/admin/articles/{id}":{"delete":{"operationId":"adminDeleteArticle","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Delete Article (internal)","tags":["Admin"],"x-internal":true},"patch":{"operationId":"adminUpdateArticle","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Update Article (internal)","tags":["Admin"],"x-internal":true}},"/admin/attention-counts":{"get":{"operationId":"adminAttentionCounts","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Attention Counts (internal)","tags":["Admin"],"x-internal":true}},"/admin/balance/{userId}":{"get":{"operationId":"adminGetUserBalance","parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Get User Balance (internal)","tags":["Admin"],"x-internal":true}},"/admin/balance/{userId}/deduct":{"post":{"operationId":"adminDeductBalance","parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Deduct Balance (internal)","tags":["Admin"],"x-internal":true}},"/admin/balance/{userId}/grant":{"post":{"operationId":"adminGrantBalance","parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Grant Balance (internal)","tags":["Admin"],"x-internal":true}},"/admin/cleanup/execute":{"post":{"operationId":"adminCleanupExecute","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Cleanup Execute (internal)","tags":["Admin"],"x-internal":true}},"/admin/cleanup/preview":{"get":{"operationId":"adminCleanupPreview","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Cleanup Preview (internal)","tags":["Admin"],"x-internal":true}},"/admin/cleanup/status":{"get":{"operationId":"adminCleanupStatus","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Cleanup Status (internal)","tags":["Admin"],"x-internal":true}},"/admin/cleanup/trigger":{"post":{"operationId":"adminCleanupTrigger","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Cleanup Trigger (internal)","tags":["Admin"],"x-internal":true}},"/admin/config":{"get":{"operationId":"adminListConfig","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Config (internal)","tags":["Admin"],"x-internal":true}},"/admin/config/notification/bark-status":{"get":{"operationId":"adminBarkStatus","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Bark Status (internal)","tags":["Admin"],"x-internal":true}},"/admin/config/notification/bark-test":{"post":{"operationId":"adminTestBark","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Test Bark (internal)","tags":["Admin"],"x-internal":true}},"/admin/config/telegram/verify-bot":{"post":{"operationId":"adminVerifyTelegramBot","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Verify Telegram Bot (internal)","tags":["Admin"],"x-internal":true}},"/admin/config/{key}":{"get":{"operationId":"adminGetConfig","parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Get Config (internal)","tags":["Admin"],"x-internal":true},"put":{"operationId":"adminSetConfig","parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Set Config (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains":{"get":{"operationId":"adminListDomains","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Domains (internal)","tags":["Admin"],"x-internal":true},"post":{"operationId":"adminCreatePublicDomain","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Create Public Domain (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/batch-delete":{"post":{"operationId":"adminBatchDeleteDomains","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Batch Delete Domains (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/cleanup-unverified":{"post":{"operationId":"adminCleanupUnverifiedDomains","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Cleanup Unverified Domains (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/dedicated-usage":{"get":{"description":"D3: dedicated-tier cap configuration and live sliding-window usage per domain, aggregated per isolation group (label + statistics only), plus process-level cap check/reject counters.\n","operationId":"adminDedicatedUsage","security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Dedicated Domain Cap Usage (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/duplicates":{"get":{"operationId":"adminDomainDuplicates","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Domain Duplicates (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/governance/events":{"get":{"operationId":"adminListGovernanceEvents","parameters":[{"in":"query","name":"limit","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Governance Events (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/governance/runs":{"get":{"operationId":"adminListGovernanceRuns","parameters":[{"in":"query","name":"limit","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Governance Runs (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/stats":{"get":{"operationId":"adminDomainStats","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Domain Stats (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/{id}":{"delete":{"operationId":"adminDeleteDomain","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Delete Domain (internal)","tags":["Admin"],"x-internal":true},"patch":{"operationId":"adminUpdateDomain","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Update Domain (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/{id}/catchall":{"get":{"operationId":"adminGetCatchall","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Get Catchall (internal)","tags":["Admin"],"x-internal":true},"put":{"operationId":"adminUpsertCatchall","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Upsert Catchall (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/{id}/governance":{"get":{"operationId":"adminGetDomainGovernance","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Get Domain Governance (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/{id}/governance-tier":{"get":{"operationId":"adminGetGovernanceTier","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Get Governance Tier (internal)","tags":["Admin"],"x-internal":true},"put":{"operationId":"adminUpsertGovernanceTier","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Upsert Governance Tier (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/{id}/governance/pause":{"post":{"operationId":"adminPauseDomainGovernance","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"note":{"type":"string"},"reasonCode":{"enum":["risk_manual_review","ops_manual_pause"],"type":"string"}},"required":["reasonCode"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Pause Domain Governance (internal)","tags":["Admin"],"x-internal":true}},"/admin/domains/{id}/governance/resume":{"post":{"operationId":"adminResumeDomainGovernance","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Resume Domain Governance (internal)","tags":["Admin"],"x-internal":true}},"/admin/email-dispatch":{"get":{"operationId":"adminListEmailDispatchJobs","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Email Dispatch Jobs (internal)","tags":["Admin"],"x-internal":true}},"/admin/email-dispatch/{id}":{"get":{"operationId":"adminGetEmailDispatchJob","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Get Email Dispatch Job (internal)","tags":["Admin"],"x-internal":true}},"/admin/email-dispatch/{id}/retry":{"post":{"operationId":"adminRetryEmailDispatchJob","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Retry Email Dispatch Job (internal)","tags":["Admin"],"x-internal":true}},"/admin/email-templates":{"get":{"operationId":"adminListEmailTemplates","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Email Templates (internal)","tags":["Admin"],"x-internal":true}},"/admin/email-templates/{code}":{"patch":{"operationId":"adminUpdateEmailTemplate","parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Update Email Template (internal)","tags":["Admin"],"x-internal":true}},"/admin/email-templates/{code}/preview":{"post":{"operationId":"adminPreviewEmailTemplate","parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Preview Email Template (internal)","tags":["Admin"],"x-internal":true}},"/admin/email-templates/{code}/reset":{"post":{"operationId":"adminResetEmailTemplate","parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Reset Email Template (internal)","tags":["Admin"],"x-internal":true}},"/admin/mail-sender-profiles":{"get":{"operationId":"adminListMailSenderProfiles","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Mail Sender Profiles (internal)","tags":["Admin"],"x-internal":true}},"/admin/mail-sender-profiles/{code}":{"put":{"operationId":"adminUpsertMailSenderProfile","parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Upsert Mail Sender Profile (internal)","tags":["Admin"],"x-internal":true}},"/admin/mail-sender-profiles/{code}/activate":{"post":{"operationId":"adminActivateMailSenderProfile","parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Activate Mail Sender Profile (internal)","tags":["Admin"],"x-internal":true}},"/admin/mail-sender-profiles/{code}/test":{"post":{"operationId":"adminTestMailSenderProfile","parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Test Mail Sender Profile (internal)","tags":["Admin"],"x-internal":true}},"/admin/messages":{"get":{"operationId":"adminListFeedback","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Feedback (internal)","tags":["Admin"],"x-internal":true}},"/admin/messages/{id}":{"delete":{"operationId":"adminDeleteMessage","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Delete Message (internal)","tags":["Admin"],"x-internal":true}},"/admin/messages/{id}/close":{"post":{"operationId":"adminCloseMessage","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Close Message (internal)","tags":["Admin"],"x-internal":true}},"/admin/messages/{id}/reply":{"post":{"operationId":"adminReplyMessage","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Reply Message (internal)","tags":["Admin"],"x-internal":true}},"/admin/monitor":{"get":{"operationId":"adminSystemMonitor","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin System Monitor (internal)","tags":["Admin"],"x-internal":true}},"/admin/orders":{"get":{"operationId":"adminListOrders","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Orders (internal)","tags":["Admin"],"x-internal":true}},"/admin/orders/stats":{"get":{"operationId":"adminOrderStats","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Order Stats (internal)","tags":["Admin"],"x-internal":true}},"/admin/orders/{id}/cancel":{"post":{"operationId":"adminCancelOrder","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Cancel Order (internal)","tags":["Admin"],"x-internal":true}},"/admin/orders/{id}/refund":{"post":{"operationId":"adminRefundOrder","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Refund Order (internal)","tags":["Admin"],"x-internal":true}},"/admin/plans":{"get":{"operationId":"adminListPlans","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Plans (internal)","tags":["Admin"],"x-internal":true}},"/admin/plans/{id}":{"put":{"operationId":"adminUpdatePlan","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Update Plan (internal)","tags":["Admin"],"x-internal":true}},"/admin/quota-alerts":{"get":{"description":"F1 — users at/above the quota alert threshold (default 90%, system_config quota.alert_threshold_percent) across inboxes / apiCallsDaily / storage. data = { alerts, total, page, limit, thresholdPercent, counts }.\n","operationId":"adminQuotaAlerts","parameters":[{"in":"query","name":"dimension","schema":{"enum":["all","inboxes","apiCallsDaily","storage"],"type":"string"}},{"in":"query","name":"page","schema":{"minimum":1,"type":"integer"}},{"in":"query","name":"limit","schema":{"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Quota Alerts (internal)","tags":["Admin"],"x-internal":true}},"/admin/redemption-codes":{"get":{"operationId":"adminListRedemptionCodes","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Redemption Codes (internal)","tags":["Admin"],"x-internal":true},"post":{"operationId":"adminCreateRedemptionCodes","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Create Redemption Codes (internal)","tags":["Admin"],"x-internal":true}},"/admin/redemption-codes/{id}":{"delete":{"operationId":"adminDeleteRedemptionCode","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Delete Redemption Code (internal)","tags":["Admin"],"x-internal":true},"get":{"operationId":"adminGetRedemptionCode","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Get Redemption Code (internal)","tags":["Admin"],"x-internal":true}},"/admin/revenue/summary":{"get":{"operationId":"adminRevenueSummary","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Revenue Summary (internal)","tags":["Admin"],"x-internal":true}},"/admin/stats":{"get":{"operationId":"adminStats","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Stats (internal)","tags":["Admin"],"x-internal":true}},"/admin/users":{"get":{"operationId":"adminListUsers","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Users (internal)","tags":["Admin"],"x-internal":true}},"/admin/users/{id}":{"get":{"operationId":"adminGetUser","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Get User (internal)","tags":["Admin"],"x-internal":true},"patch":{"operationId":"adminUpdateUser","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Update User (internal)","tags":["Admin"],"x-internal":true}},"/admin/users/{id}/active":{"patch":{"operationId":"adminToggleUserActive","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Toggle User Active (internal)","tags":["Admin"],"x-internal":true}},"/admin/users/{id}/redeem-history":{"get":{"operationId":"adminUserRedeemHistory","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin User Redeem History (internal)","tags":["Admin"],"x-internal":true}},"/admin/wildcard-rules":{"get":{"operationId":"adminListWildcardRules","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Wildcard Rules (internal)","tags":["Admin"],"x-internal":true}},"/admin/wildcard-rules/{id}":{"patch":{"operationId":"adminUpdateWildcardRule","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Update Wildcard Rule (internal)","tags":["Admin"],"x-internal":true}},"/admin/wildcard-rules/{id}/assignments":{"get":{"operationId":"adminListWildcardAssignments","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Wildcard Assignments (internal)","tags":["Admin"],"x-internal":true}},"/admin/wildcard-rules/{id}/assignments/{assignmentId}":{"delete":{"operationId":"adminDeleteWildcardAssignment","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"assignmentId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Delete Wildcard Assignment (internal)","tags":["Admin"],"x-internal":true}},"/admin/wildcard-rules/{id}/assignments/{assignmentId}/inboxes":{"get":{"operationId":"adminListWildcardAssignmentInboxes","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"assignmentId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin List Wildcard Assignment Inboxes (internal)","tags":["Admin"],"x-internal":true}},"/admin/wildcard-rules/{id}/assignments/{assignmentId}/release":{"post":{"operationId":"adminReleaseWildcardAssignment","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"assignmentId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Admin Release Wildcard Assignment (internal)","tags":["Admin"],"x-internal":true}},"/announcements":{"get":{"operationId":"listAnnouncements","parameters":[{"in":"query","name":"page","schema":{"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/limit"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Without page/limit, data = array of announcements. With pagination, data = { announcements, page, limit, total }.\n"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List active announcements","tags":["Content"]}},"/article-assets/{path}":{"get":{"operationId":"getArticleAsset","parameters":[{"description":"Asset path (greedy match).","in":"path","name":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"image/*":{"schema":{"format":"binary","type":"string"}}},"description":"Raw image bytes."},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Serve an uploaded article image asset","tags":["Content"]}},"/articles":{"get":{"operationId":"listArticles","parameters":[{"in":"query","name":"page","schema":{"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/limit"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { articles, total, page, limit }."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List published articles","tags":["Content"]}},"/articles/{slug}":{"get":{"operationId":"getArticleBySlug","parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = Article."},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get a published article by slug","tags":["Content"]}},"/auth/forgot-password":{"post":{"description":"Always responds sent=true (does not reveal whether the email exists).","operationId":"forgotPassword","requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"type":"string"}},"required":["email"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { sent, expiresInSeconds }."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Request a password reset email","tags":["Auth"]}},"/auth/login":{"post":{"operationId":"login","requestBody":{"content":{"application/json":{"schema":{"properties":{"password":{"type":"string"},"turnstileToken":{"type":"string"},"twofaCode":{"description":"Required when the account has 2FA enabled.","type":"string"},"username":{"description":"Username or email.","type":"string"}},"required":["username","password"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { id, access_token, expires_in, emailVerified }. Sets yyds_access_token / yyds_refresh_token cookies."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Login with username/email + password","tags":["Auth"]}},"/auth/oauth/config":{"get":{"operationId":"getOAuthConfig","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { providers, state }. Sets the yyds_oauth_state cookie (5 min)."}},"summary":"Available OAuth providers + CSRF state","tags":["Auth"]}},"/auth/oauth/github":{"post":{"operationId":"oauthGitHub","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"redirectUri":{"type":"string"},"state":{"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { id, access_token, expires_in, isNewUser }."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"Exchange a GitHub authorization code for local tokens","tags":["Auth"]}},"/auth/oauth/linuxdo":{"post":{"operationId":"oauthLinuxDo","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"redirectUri":{"type":"string"},"state":{"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { id, access_token, expires_in, isNewUser }."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"Exchange a LinuxDo authorization code for local tokens","tags":["Auth"]}},"/auth/passkey/login/begin":{"post":{"operationId":"passkeyLoginBegin","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = WebAuthn credential assertion options. Sets a passkey session cookie."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Begin passkey (WebAuthn) discoverable login","tags":["Auth"]}},"/auth/passkey/login/finish":{"post":{"operationId":"passkeyLoginFinish","requestBody":{"content":{"application/json":{"schema":{"description":"WebAuthn assertion response from navigator.credentials.get().","type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { id, access_token, expires_in }."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"Finish passkey login","tags":["Auth"]}},"/auth/register":{"post":{"operationId":"register","requestBody":{"content":{"application/json":{"schema":{"properties":{"displayName":{"type":"string"},"email":{"type":"string"},"inviteCode":{"type":"string"},"password":{"description":"8-128 characters.","type":"string"},"turnstileToken":{"type":"string"},"username":{"type":"string"}},"required":["displayName","username","email","password"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"When email verification is required, data = { emailVerificationRequired: true, emailVerified: false }. Otherwise data = { id, access_token, expires_in, emailVerified } and auth cookies are set.\n"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Register a new account","tags":["Auth"]}},"/auth/register/check":{"post":{"operationId":"checkRegisterAvailability","requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"type":"string"},"username":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { username?, usernameAvailable, email?, emailAvailable }."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Check username/email availability","tags":["Auth"]}},"/auth/resend-verify":{"post":{"operationId":"resendVerify","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { sent, expiresInSeconds }."},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Resend verification email (signed-in)","tags":["Auth"]}},"/auth/resend-verify/register":{"post":{"description":"Always responds sent=true (does not reveal whether the email exists).","operationId":"resendVerifyRegistration","requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"type":"string"}},"required":["email"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { sent, expiresInSeconds }."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Resend verification email during registration","tags":["Auth"]}},"/auth/reset-password":{"post":{"description":"Revokes all refresh tokens for the user on success.","operationId":"resetPassword","requestBody":{"content":{"application/json":{"schema":{"properties":{"password":{"type":"string"},"token":{"type":"string"}},"required":["token","password"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { reset: true }."},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Reset password with a token","tags":["Auth"]}},"/auth/reset-password/validate":{"get":{"operationId":"validatePasswordReset","parameters":[{"in":"query","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { valid, email, expiresAt }."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Validate a password reset token","tags":["Auth"]}},"/auth/status":{"get":{"operationId":"getAuthStatus","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { registerEnabled, passwordLoginEnabled, passwordRegisterEnabled, emailVerificationRequired, inviteCodeRequired, turnstileEnabled, turnstileSiteKey, passkeyEnabled, twofaEnabled, minPasswordLength, maxDisplayNameLength, oauthProviders }."}},"summary":"Auth feature flags","tags":["Auth"]}},"/auth/token/refresh":{"post":{"description":"Reads the yyds_refresh_token cookie. Rotates on every call; presenting a rotated token again revokes the whole token family (reuse detection).\n","operationId":"refreshToken","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { access_token, expires_in }. Sets rotated cookies."},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"Rotate refresh token + reissue access token","tags":["Auth"]}},"/auth/token/revoke":{"post":{"operationId":"revokeToken","responses":{"204":{"description":"Token revoked and auth cookies cleared (no body)."}},"summary":"Revoke the current refresh token (logout)","tags":["Auth"]}},"/auth/verify-email":{"post":{"operationId":"verifyEmail","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { verified, verifiedAt }."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Verify the signed-in user's email with a code","tags":["Auth"]}},"/auth/verify-email/register":{"post":{"description":"On success issues tokens and sets auth cookies (registration login).","operationId":"verifyEmailRegistration","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"email":{"type":"string"}},"required":["email","code"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { id, access_token, expires_in, emailVerified }."},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Verify email during registration (no session yet)","tags":["Auth"]}},"/auth/ws-ticket":{"get":{"operationId":"getWsTicket","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { ticket } (30s TTL, pass as ?ticket= to /ws)."},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]},{"tempToken":[]}],"summary":"Get a short-lived WebSocket ticket","tags":["Auth"]}},"/domain-reward/config":{"get":{"operationId":"getDomainRewardConfig","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { usagePerCredit, creditsPerCycle, runHour, creditExpireDays }."}},"summary":"Domain reward rule configuration","tags":["Public"]}},"/domains":{"get":{"description":"Anonymous callers see public domains only. Authenticated (JWT / API key) callers additionally see their own receiving-ready private domains.\n","operationId":"listDomains","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/Domain"},"type":"array"}},"type":"object"}]}}},"description":"data = array of Domain."},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"List available domains","tags":["Public"]}},"/emails":{"post":{"deprecated":true,"operationId":"legacyCreateEmail","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccountRequest"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Same payload as POST /accounts."}},"security":[{},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Legacy alias of POST /accounts","tags":["Accounts"]}},"/error-codes":{"get":{"description":"Machine-readable registry of every stable errorCode the API can emit, with English and Chinese messages. Generated from the server's error localization table; prefer these codes over localized error text.\n","operationId":"getErrorCodes","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"count":{"type":"integer"},"errorCodes":{"items":{"properties":{"code":{"type":"string"},"en":{"description":"English message, or the regexp pattern for source=pattern entries.","type":"string"},"source":{"enum":["exact","pattern"],"type":"string"},"zh":{"type":"string"}},"type":"object"},"type":"array"},"source":{"type":"string"}},"type":"object"}}},"description":"{ source, count, errorCodes: [{ code, en, zh?, source }] }."}},"summary":"Public errorCode catalog","tags":["Public"]}},"/external-accounts/oauth/{provider}/callback":{"get":{"description":"Public endpoint the provider redirects back to. Validates and burns the state token, exchanges the code, resolves the mailbox address via userinfo, verifies XOAUTH2 IMAP login, then persists the account and redirects (302) to the frontend /external-accounts page with ?oauth=success or ?oauth=error\u0026reason=\u003ccode\u003e. Never returns JSON.\n","operationId":"externalOAuthCallback","parameters":[{"in":"path","name":"provider","required":true,"schema":{"enum":["gmail","outlook"],"type":"string"}},{"in":"query","name":"state","required":true,"schema":{"type":"string"}},{"in":"query","name":"code","required":false,"schema":{"type":"string"}},{"in":"query","name":"error","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the frontend with the binding outcome."}},"security":[],"summary":"OAuth2 provider callback (browser redirect target)","tags":["Me"]}},"/health":{"get":{"description":"Returns ok/degraded based on PG, Redis (if configured), and the SMTP listener. Degraded responses use HTTP 503 with success=false.","operationId":"getHealth","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"All subsystems healthy. data = { status, version, buildDate }."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"One or more subsystems degraded (same data shape, success=false)."}},"summary":"Health check","tags":["Public"]}},"/inboxes":{"post":{"deprecated":true,"description":"Same behavior as POST /accounts. Responds with Deprecation and Link successor-version headers.","operationId":"legacyCreateInbox","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccountRequest"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Same payload as POST /accounts."}},"security":[{},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Legacy alias of POST /accounts","tags":["Accounts"]}},"/inboxes/{id}":{"get":{"description":"Canonical successor of GET /accounts/{id} — same handler, identical behavior and response shape. Temp tokens may only read their own inbox; JWT / API key callers must own the inbox.\n","operationId":"getInboxById","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/TempAccount"}},"type":"object"}]}}},"description":"data = TempAccount."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"tempToken":[]},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Get inbox by ID (canonical)","tags":["Inboxes"]}},"/inboxes/{id}/messages":{"get":{"description":"Canonical successor of GET /messages?address=… keyed by inbox ID instead of address. Delegates to the same implementation: identical filters, pagination, and response shape. Temp tokens may only read their own inbox; JWT / API key callers must own the inbox.\n","operationId":"listInboxMessages","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Max items (default 50, max 200).","in":"query","name":"limit","schema":{"maximum":200,"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/offset"},{"description":"Read-state filter (seen=false = only unread).","in":"query","name":"seen","schema":{"type":"boolean"}},{"description":"Only messages at/after this RFC 3339 timestamp (inclusive).","in":"query","name":"since","schema":{"format":"date-time","type":"string"}},{"description":"Case-insensitive substring match on subject and from.","in":"query","name":"q","schema":{"type":"string"}},{"description":"Cursor — return messages strictly after this id (supersedes offset).","in":"query","name":"after_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"messages":{"items":{"$ref":"#/components/schemas/MessageListItem"},"type":"array"},"total":{"type":"integer"},"unreadCount":{"type":"integer"}},"type":"object"}},"type":"object"}]}}},"description":"data = { messages, total, unreadCount, nextCursor? }."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"tempToken":[]},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"List messages in an inbox (canonical)","tags":["Inboxes"]}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Plain-text public API summary for AI assistants."}},"summary":"LLM-friendly API summary (plain text)","tags":["Public"]}},"/mailbox-shares/{token}":{"get":{"description":"Public. Inactive shares (revoked/expired/view-limit) return the same meta with success=false and HTTP 410/403.","operationId":"getMailboxShareMeta","parameters":[{"$ref":"#/components/parameters/shareToken"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = share meta { id, accessMode, passwordRequired, expiresAt, maxViews, viewCount, allowMessageDetail, status, accessGranted?, accessExpiresAt? }."},"404":{"$ref":"#/components/responses/NotFound"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Share revoked / expired / inbox gone (meta still included in data)."}},"summary":"Get share metadata","tags":["Mailbox Shares"]}},"/mailbox-shares/{token}/access":{"post":{"operationId":"accessMailboxShare","parameters":[{"$ref":"#/components/parameters/shareToken"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"password":{"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { accessToken, expiresAt, inboxAddress, inboxExpiresAt?, share }. Also sets a share session cookie."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Share no longer active or view limit consumed."}},"summary":"Unlock a share (password if required) and get a session token","tags":["Mailbox Shares"]}},"/mailbox-shares/{token}/messages":{"get":{"operationId":"listMailboxShareMessages","parameters":[{"$ref":"#/components/parameters/shareToken"},{"in":"query","name":"limit","schema":{"maximum":200,"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { messages, total, unreadCount } (same item shape as GET /messages)."},"401":{"$ref":"#/components/responses/Unauthorized"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Share no longer active."}},"summary":"List messages in a shared mailbox","tags":["Mailbox Shares"]}},"/mailbox-shares/{token}/messages/{id}":{"get":{"description":"Requires allowMessageDetail on the share.","operationId":"getMailboxShareMessage","parameters":[{"$ref":"#/components/parameters/shareToken"},{"$ref":"#/components/parameters/messageId"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/MessageDetail"}},"type":"object"}]}}},"description":"data = MessageDetail (attachment URLs point to the share attachment endpoint)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get message detail in a shared mailbox","tags":["Mailbox Shares"]}},"/mailbox-shares/{token}/messages/{id}/attachments/{num}/{file}":{"get":{"operationId":"getMailboxShareAttachment","parameters":[{"$ref":"#/components/parameters/shareToken"},{"$ref":"#/components/parameters/messageId"},{"description":"Zero-based attachment index.","in":"path","name":"num","required":true,"schema":{"type":"integer"}},{"description":"Attachment filename (display only).","in":"path","name":"file","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"Raw attachment bytes with original content type."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Download an attachment from a shared message","tags":["Mailbox Shares"]}},"/mailbox-shares/{token}/ws-ticket":{"get":{"operationId":"getMailboxShareWsTicket","parameters":[{"$ref":"#/components/parameters/shareToken"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { ticket } (30s TTL)."},"401":{"$ref":"#/components/responses/Unauthorized"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Share no longer active."}},"summary":"Get a WebSocket ticket for a share session","tags":["Mailbox Shares"]}},"/mailboxes":{"post":{"deprecated":true,"operationId":"legacyCreateMailbox","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccountRequest"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Same payload as POST /accounts."}},"security":[{},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Legacy alias of POST /accounts","tags":["Accounts"]}},"/me":{"get":{"description":"data = { user, isAdmin, quota }.","operationId":"getMe","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Get my profile + effective quota","tags":["Me"]},"patch":{"description":"Currently supports displayName (changeable once). data = { user, isAdmin, quota }.","operationId":"updateMe","requestBody":{"content":{"application/json":{"schema":{"properties":{"displayName":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Update my profile","tags":["Me"]}},"/me/announcements/{id}/read":{"post":{"operationId":"markAnnouncementRead","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Mark an announcement read","tags":["Me"]}},"/me/api-keys":{"get":{"description":"data = { apiKeys, total }. API-key callers only see their own key metadata.","operationId":"listMyApiKeys","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"List my API keys","tags":["Me"]},"post":{"description":"The plaintext key is returned in this response and can later be re-revealed via /me/api-keys/{id}/reveal.","operationId":"createApiKey","requestBody":{"content":{"application/json":{"schema":{"properties":{"allowedDomainIds":{"items":{"type":"string"},"type":"array"},"allowedWildcardRuleIds":{"items":{"type":"string"},"type":"array"},"defaultDomainId":{"type":"string"},"defaultWildcardRuleId":{"type":"string"},"defaultWildcardSubdomainLabel":{"type":"string"},"domainScope":{"enum":["all","public","own","specific"],"type":"string"},"expiresAt":{"format":"date-time","type":"string"},"name":{"maxLength":100,"type":"string"},"permissions":{"items":{"enum":["read","write","all"],"type":"string"},"type":"array"},"wildcardRuleScope":{"enum":["none","own","specific"],"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"$ref":"#/components/responses/Created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Create an API key","tags":["Me"]}},"/me/api-keys/{id}":{"delete":{"operationId":"deleteApiKey","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Delete an API key","tags":["Me"]},"patch":{"description":"Fields are optional and independent: name, domainScope (+ allowedDomainIds), expiresAt (RFC3339 to set, null to clear, absent to keep), enabled (reversible disable/enable).\n","operationId":"updateApiKey","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Update an API key (name / scope / expiry / enabled)","tags":["Me"]}},"/me/api-keys/{id}/reveal":{"get":{"operationId":"revealApiKey","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Reveal the full API key value","tags":["Me"]}},"/me/api-keys/{id}/rotate":{"post":{"description":"Generates a new secret (returned once in this response). The old secret keeps authenticating until graceUntil (default 24h, system-configurable), then stops permanently. Key id, scope and usage history are preserved.\n","operationId":"rotateApiKey","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Rotate an API key secret","tags":["Me"]}},"/me/api-keys/{id}/usage":{"get":{"operationId":"getApiKeyUsage","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"API key usage stats","tags":["Me"]}},"/me/balance":{"get":{"description":"data = { balance, transactions }. Amounts in cents.","operationId":"getMyBalance","parameters":[{"$ref":"#/components/parameters/limit"}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"My balance + recent transactions","tags":["Me"]}},"/me/balance/purchase":{"post":{"description":"Deducts balance and grants a purchased-pool credit. type \"api_calls\" buys API-call credits (quantity = calls); A3 capacity add-ons: type \"storage\" buys storage packs (quantity = GB), type \"inboxes\" buys persistent inbox slots (quantity = slots). Purchased packs stack onto the plan baseline at read/enforcement time and never rewrite it.\n","operationId":"balancePurchase","requestBody":{"content":{"application/json":{"schema":{"properties":{"quantity":{"description":"Pack size — must match a catalog entry from GET /pricing (packages for api_calls, addonPackages for storage/inboxes).\n","type":"integer"},"type":{"enum":["api_calls","storage","inboxes"],"type":"string"}},"required":["type","quantity"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Insufficient balance."}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Purchase API-call credits or capacity add-on packs with balance","tags":["Me"]}},"/me/balance/purchase-plan":{"post":{"operationId":"balancePurchasePlan","requestBody":{"content":{"application/json":{"schema":{"properties":{"confirmDowngrade":{"type":"boolean"},"planDays":{"enum":[30,90,180,365],"type":"integer"},"planId":{"type":"string"}},"required":["planId"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Insufficient balance."}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Purchase a plan with balance","tags":["Me"]}},"/me/balance/topup":{"post":{"operationId":"balanceTopUp","requestBody":{"content":{"application/json":{"schema":{"properties":{"amount":{"description":"Cents. Min 100 (1 yuan), max 1000000 (10000 yuan).","type":"integer"},"payType":{"enum":["alipay","wxpay"],"type":"string"}},"required":["amount"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Create a balance top-up order","tags":["Me"]}},"/me/banana/claim":{"post":{"description":"Body { source: \"daily_login\" | \"accrual\" | \"all\" }. Moves pending bananas into the wallet inventory (banana_grants). Respects wallet cap; returns actual claimed count. data = { claimed, wallet }.\n","operationId":"claimBananas","requestBody":{"content":{"application/json":{"schema":{"properties":{"source":{"enum":["daily_login","accrual","all"],"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Claim bananas from the pending pool (manual pickup)","tags":["Me"]}},"/me/banana/feed":{"post":{"description":"Body { count } (1-10, default 1). data = { state (ok|no_bananas|daily_cap|disabled|too_fast), results[] with outcome (eaten|rotten|refused) and rewardCalls, totalReward, wallet }. Refused bananas are returned and do not count toward the daily cap.\n","operationId":"feedBananas","requestBody":{"content":{"application/json":{"schema":{"properties":{"count":{"maximum":10,"minimum":1,"type":"integer"}},"type":"object"}}},"required":false},"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Feed bananas to the pig (server-adjudicated, per-banana outcomes)","tags":["Me"]}},"/me/banana/history":{"get":{"description":"Query param ?limit=10 (default 10, max 50). Aggregates per-second feed batches. data = array of { fedAt, count, eaten, rotten, refused, rewardCalls }.\n","operationId":"getBananaHistory","parameters":[{"in":"query","name":"limit","schema":{"maximum":50,"minimum":1,"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Get banana feeding history (last N entries)","tags":["Me"]}},"/me/banana/wallet":{"get":{"description":"data = { enabled, wallet: { bananas, walletCap, todayFed, feedDailyCap, rewardEnabled, expiringSoon, nextAccrualAt } }. Reading the wallet also lazily accrues daily-login and time-based banana grants.\n","operationId":"getBananaWallet","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Banana wallet snapshot (balance, today's feeds, expiring soon)","tags":["Me"]}},"/me/bind/github":{"post":{"operationId":"bindGitHub","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Bind a GitHub account","tags":["Me"]}},"/me/bind/linuxdo":{"post":{"operationId":"bindLinuxDo","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Bind a LinuxDo account","tags":["Me"]}},"/me/catchall/claims":{"get":{"operationId":"listMyCatchallClaims","parameters":[{"in":"query","name":"status","required":false,"schema":{"enum":["open","all","claimed_private","expired_unclaimed","blocked_prefix"],"type":"string"}},{"in":"query","name":"domainId","required":false,"schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List catch-all pending claims across owned domains","tags":["Me"]}},"/me/catchall/claims/{id}/claim":{"post":{"operationId":"claimCatchallAddress","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Claim a catch-all pending address as a private inbox","tags":["Me"]}},"/me/catchall/claims/{id}/dismiss":{"post":{"operationId":"dismissCatchallClaim","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"block":{"description":"true marks the local part blocked_prefix permanently","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Dismiss (expire or block) a catch-all pending claim","tags":["Me"]}},"/me/credits":{"get":{"operationId":"getMyCredits","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"My active credit balances grouped by source","tags":["Me"]}},"/me/deactivate":{"post":{"operationId":"deactivateAccount","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Deactivate my account (cooldown applies)","tags":["Me"]}},"/me/dns-service-connections":{"get":{"operationId":"listDnsConnections","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List DNS provider connections","tags":["Me"]},"post":{"operationId":"createDnsConnection","responses":{"201":{"$ref":"#/components/responses/Created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Create a DNS provider connection (e.g. Cloudflare token)","tags":["Me"]}},"/me/dns-service-connections/test-draft":{"post":{"operationId":"testDnsConnectionDraft","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Test a DNS connection draft before saving","tags":["Me"]}},"/me/dns-service-connections/{id}":{"delete":{"operationId":"deleteDnsConnection","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Delete a DNS connection","tags":["Me"]},"patch":{"operationId":"updateDnsConnection","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Update a DNS connection","tags":["Me"]}},"/me/dns-service-connections/{id}/test":{"post":{"operationId":"testDnsConnection","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Test a saved DNS connection","tags":["Me"]}},"/me/dns-service-connections/{id}/zones":{"get":{"operationId":"listDnsConnectionZones","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List zones visible to a DNS connection","tags":["Me"]}},"/me/domain-stats":{"get":{"operationId":"getMyDomainStats","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Usage stats for my shared domains","tags":["Me"]}},"/me/domains":{"get":{"operationId":"listMyDomains","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List my domains","tags":["Me"]},"post":{"description":"A leading `*.` enables a wildcard rule for the domain.","operationId":"createMyDomain","requestBody":{"content":{"application/json":{"schema":{"properties":{"domain":{"type":"string"},"enableWildcardRule":{"type":"boolean"}},"required":["domain"],"type":"object"}}},"required":true},"responses":{"201":{"$ref":"#/components/responses/Created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Add a custom domain","tags":["Me"]}},"/me/domains/batch":{"post":{"operationId":"batchCreateMyDomains","requestBody":{"content":{"application/json":{"schema":{"properties":{"domains":{"items":{"type":"string"},"type":"array"}},"required":["domains"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Batch-add custom domains","tags":["Me"]}},"/me/domains/batch-delete":{"post":{"description":"Deletes up to 50 owned domains; each goes through the full cascade (inbox cleanup in-transaction, mail files purged asynchronously). data = { results: [{id, domain, success, error?}], deleted, failed }.","operationId":"batchDeleteMyDomains","requestBody":{"content":{"application/json":{"schema":{"properties":{"ids":{"items":{"type":"string"},"type":"array"}},"required":["ids"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Batch-delete my domains by IDs","tags":["Me"]}},"/me/domains/{id}":{"delete":{"operationId":"deleteMyDomain","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Delete my domain","tags":["Me"]},"patch":{"operationId":"updateMyDomain","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Update my domain (e.g. visibility)","tags":["Me"]}},"/me/domains/{id}/catchall":{"get":{"operationId":"getMyCatchall","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Get catch-all safe mode settings and eligibility for a domain","tags":["Me"]},"put":{"operationId":"updateMyCatchall","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"confirm":{"description":"Explicit owner acknowledgment, required when enabling","type":"boolean"},"enabled":{"type":"boolean"}},"required":["enabled"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Enable or disable catch-all safe mode (owner proof required)","tags":["Me"]}},"/me/domains/{id}/dns-guide":{"get":{"operationId":"getDomainDnsGuide","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"DNS setup guide (records to add)","tags":["Me"]}},"/me/domains/{id}/dns-status":{"get":{"operationId":"getDomainDnsStatus","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Live DNS verification status","tags":["Me"]}},"/me/domains/{id}/dns-sync":{"post":{"operationId":"syncDomainDns","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Sync DNS records via a connected DNS provider","tags":["Me"]}},"/me/domains/{id}/reserved-prefixes":{"get":{"operationId":"listOwnerReservedPrefixes","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List owner protected reserved prefixes for a shared domain","tags":["Me"]},"put":{"operationId":"updateOwnerReservedPrefixes","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"prefixes":{"items":{"type":"string"},"type":"array"}},"required":["prefixes"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Replace the owner protected reserved prefix set for a domain","tags":["Me"]}},"/me/domains/{id}/verify":{"post":{"operationId":"verifyMyDomain","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Trigger domain DNS verification","tags":["Me"]}},"/me/domains/{id}/wildcard-rules":{"get":{"operationId":"listDomainWildcardRules","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List wildcard rules for a domain","tags":["Me"]},"post":{"operationId":"createDomainWildcardRule","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"201":{"$ref":"#/components/responses/Created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Create a wildcard rule for a domain","tags":["Me"]}},"/me/domains/{id}/wildcard-rules/{ruleId}":{"patch":{"operationId":"updateDomainWildcardRule","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"ruleId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Update a wildcard rule (pause/resume etc.)","tags":["Me"]}},"/me/email/bind":{"post":{"operationId":"bindEmail","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Bind an email address with a code","tags":["Me"]}},"/me/email/send-code":{"post":{"operationId":"sendEmailBindCode","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Send an email-bind verification code","tags":["Me"]}},"/me/external-accounts":{"get":{"description":"data = { accounts, total, maxPerUser, planSyncLimit, minSyncLimit }. Each account carries syncMessageLimit (user override, absent = follow plan), effectiveSyncLimit (enforced cap = min(plan, override)) and syncedMessageCount (live envelope count — the same COUNT the rolling eviction enforces).\n","operationId":"listExternalAccounts","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List external mail accounts","tags":["Me"]},"post":{"operationId":"createExternalAccount","requestBody":{"content":{"application/json":{"schema":{"properties":{"credential":{"type":"string"},"email":{"type":"string"},"imapHost":{"type":"string"},"imapPort":{"type":"integer"},"provider":{"type":"string"},"useTls":{"type":"boolean"}},"required":["provider","email","credential"],"type":"object"}}},"required":true},"responses":{"201":{"$ref":"#/components/responses/Created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Add an external mail account (IMAP verified before save)","tags":["Me"]}},"/me/external-accounts/oauth/{provider}/authorize":{"get":{"description":"Mints a one-shot CSRF state (10 min TTL, bound to the current user and provider) and redirects (302) to the provider's consent page. provider = gmail | outlook.\n","operationId":"externalOAuthAuthorize","parameters":[{"in":"path","name":"provider","required":true,"schema":{"enum":["gmail","outlook"],"type":"string"}}],"responses":{"302":{"description":"Redirect to the provider authorization page."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"OAuth client credentials or redirect base URL not configured."}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Start the OAuth2 (XOAUTH2) binding flow for Gmail/Outlook","tags":["Me"]}},"/me/external-accounts/providers":{"get":{"operationId":"listExternalProviders","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List supported external providers","tags":["Me"]}},"/me/external-accounts/test-draft":{"post":{"operationId":"testExternalAccountDraft","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Test external account credentials before saving","tags":["Me"]}},"/me/external-accounts/{id}":{"delete":{"operationId":"deleteExternalAccount","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Remove an external account","tags":["Me"]},"patch":{"description":"Body fields (all optional): displayName, enabled, credential (rotates the stored password after server-side re-verification), syncMessageLimit (per-account envelope retention cap — clamped to [10, plan cap]; \u003c= 0 clears the override so the account follows the plan entitlement; changing it queues an immediate resync that trims or backfills to the new cap).\n","operationId":"updateExternalAccount","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"credential":{"type":"string"},"displayName":{"type":"string"},"enabled":{"type":"boolean"},"syncMessageLimit":{"description":"Envelope retention cap for this account. Clamped to [10, plan cap]; \u003c= 0 clears the override (follow plan).\n","type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Update an external account","tags":["Me"]}},"/me/external-accounts/{id}/sync":{"post":{"operationId":"syncExternalAccount","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Request an IMAP sync","tags":["Me"]}},"/me/external-accounts/{id}/test":{"post":{"operationId":"testExternalAccount","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Test a saved external account connection","tags":["Me"]}},"/me/external-messages/{id}":{"get":{"operationId":"getExternalMessage","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Get an aggregated external message","tags":["Me"]}},"/me/external-messages/{id}/flags":{"post":{"operationId":"updateExternalMessageFlags","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Update external message flags (seen / starred)","tags":["Me"]}},"/me/feedback":{"get":{"operationId":"listMyFeedbackThreads","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List my feedback threads","tags":["Me"]}},"/me/feedback/unread-count":{"get":{"operationId":"getUnreadFeedbackCount","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Unread feedback reply count","tags":["Me"]}},"/me/feedback/{id}/reply":{"post":{"operationId":"replyFeedbackThread","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Reply in a feedback thread","tags":["Me"]}},"/me/growth-tasks":{"get":{"description":"data = { tasks (fixed set with completed/rewarded state), allCompleted }.","operationId":"getMyGrowthTasks","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Growth task progress and rewards","tags":["Me"]}},"/me/inboxes":{"get":{"description":"data = { inboxes, total, limit, offset, type, state, q, counts }. Query: type=persistent|temp, state, q (address search, max 128 chars), limit (default 100, max 500), offset.","operationId":"listMyInboxes","parameters":[{"in":"query","name":"type","schema":{"enum":["persistent","temp"],"type":"string"}},{"in":"query","name":"state","schema":{"type":"string"}},{"in":"query","name":"q","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"List my inboxes","tags":["Me"]},"post":{"operationId":"createMyInbox","requestBody":{"content":{"application/json":{"schema":{"properties":{"address":{"type":"string"},"displayName":{"type":"string"},"domain":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"201":{"$ref":"#/components/responses/Created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Create a persistent inbox","tags":["Me"]}},"/me/inboxes/batch-delete":{"post":{"description":"mode=delete (default) hard-deletes with async mail purge; mode=deactivate soft-disables (temp API inboxes only). Max 500 ids. data = { deleted, errors }.","operationId":"batchDeleteInboxes","requestBody":{"content":{"application/json":{"schema":{"properties":{"ids":{"items":{"type":"string"},"type":"array"},"mode":{"default":"delete","enum":["delete","deactivate"],"type":"string"}},"required":["ids"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Batch-delete or batch-deactivate inboxes by IDs","tags":["Me"]}},"/me/inboxes/cleanup":{"post":{"description":"Deletes the caller's TEMP inboxes created more than olderThanDays days ago (persistent inboxes are never eligible). dryRun=true returns { affected }; execute returns { deleted, remaining } — loop while remaining \u003e 0. onlyEmpty restricts to inboxes with no messages.","operationId":"cleanupMyInboxes","requestBody":{"content":{"application/json":{"schema":{"properties":{"dryRun":{"default":false,"type":"boolean"},"olderThanDays":{"maximum":3650,"minimum":1,"type":"integer"},"onlyEmpty":{"default":false,"type":"boolean"}},"required":["olderThanDays"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Age-based temp inbox cleanup (dry-run preview then execute)","tags":["Me"]}},"/me/inboxes/inactive":{"delete":{"operationId":"cleanupInactiveInboxes","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Bulk-delete inactive inboxes","tags":["Me"]}},"/me/inboxes/{id}":{"delete":{"operationId":"deleteMyInbox","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Delete an inbox (persistent = hard delete + mail purge)","tags":["Me"]}},"/me/inboxes/{id}/claim":{"post":{"operationId":"claimInbox","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Claim an anonymous temp inbox into my account","tags":["Me"]}},"/me/inboxes/{id}/restore":{"post":{"operationId":"restoreMyInbox","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Restore a deactivated API temp inbox","tags":["Me"]}},"/me/inboxes/{id}/shares":{"get":{"operationId":"listMyMailboxShares","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List shares for my inbox","tags":["Me"]},"post":{"operationId":"createMailboxShare","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"allowMessageDetail":{"type":"boolean"},"expiresAt":{"format":"date-time","type":"string"},"maxViews":{"type":"integer"},"password":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"201":{"$ref":"#/components/responses/Created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Create a share link for my inbox","tags":["Me"]}},"/me/inboxes/{id}/shares/{shareId}":{"delete":{"operationId":"revokeMailboxShare","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"shareId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Revoke a mailbox share","tags":["Me"]}},"/me/messages":{"get":{"operationId":"listMyFeedback","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List my feedback messages","tags":["Me"]},"post":{"operationId":"createUserMessage","requestBody":{"content":{"application/json":{"schema":{"properties":{"content":{"maxLength":2000,"type":"string"}},"required":["content"],"type":"object"}}},"required":true},"responses":{"201":{"$ref":"#/components/responses/Created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Send a feedback message","tags":["Me"]}},"/me/messages/cleanup":{"post":{"description":"Deletes LOCAL messages older than olderThanDays days across the caller's own inboxes. Optional domain / mailbox narrow the scope. External (IMAP-aggregated) messages are read-only and never touched. dryRun=true returns { affected }; execute returns { deleted, remaining } — loop while remaining \u003e 0.","operationId":"cleanupMyMessages","requestBody":{"content":{"application/json":{"schema":{"properties":{"domain":{"type":"string"},"dryRun":{"default":false,"type":"boolean"},"mailbox":{"type":"string"},"olderThanDays":{"maximum":3650,"minimum":1,"type":"integer"}},"required":["olderThanDays"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Age-based local message cleanup (dry-run preview then execute)","tags":["Me"]}},"/me/messages/mark-read":{"post":{"operationId":"markMessagesRead","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Mark feedback replies as read","tags":["Me"]}},"/me/messages/unified":{"get":{"description":"data = { messages, total, unreadCount }. total and unreadCount for external accounts are both derived from the synced external_messages index (unreadCount \u003c= total always holds). Query: limit (max 200), offset, filter, domain, q (subject/from search), source=local|external|all, accountId.","operationId":"getUnifiedMessages","parameters":[{"in":"query","name":"limit","schema":{"maximum":200,"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/offset"},{"in":"query","name":"filter","schema":{"type":"string"}},{"in":"query","name":"domain","schema":{"type":"string"}},{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"source","schema":{"enum":["local","external","all"],"type":"string"}},{"in":"query","name":"accountId","schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Unified message feed across my inboxes (+ external accounts)","tags":["Me"]}},"/me/messages/unread-count":{"get":{"operationId":"getUnreadRepliesCount","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Unread admin-reply count","tags":["Me"]}},"/me/notifications":{"get":{"description":"data = { notifications, hasMore, nextCursor }. Query: cursor, limit (max 100), unread=true, category=security|billing|domain|announcement.","operationId":"listMyNotifications","parameters":[{"in":"query","name":"cursor","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"unread","schema":{"type":"boolean"}},{"in":"query","name":"category","schema":{"enum":["security","billing","domain","announcement"],"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Notification feed (cursor-paginated)","tags":["Me"]}},"/me/notifications/clear":{"post":{"description":"Deletes every user_notifications row for the caller; virtual announcement entries cannot be deleted, so active announcements are marked read instead. data = { status, deleted }.","operationId":"clearMyNotifications","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Clear all notifications","tags":["Me"]}},"/me/notifications/read-all":{"post":{"operationId":"markAllNotificationsRead","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Mark all notifications read","tags":["Me"]}},"/me/notifications/unread-count":{"get":{"operationId":"getNotificationUnreadCount","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Unread notification count","tags":["Me"]}},"/me/notifications/{id}/read":{"post":{"operationId":"markNotificationRead","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Mark one notification read","tags":["Me"]}},"/me/oauth-bindings":{"get":{"operationId":"getOAuthBindings","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List my OAuth bindings","tags":["Me"]}},"/me/passkey/register/begin":{"post":{"operationId":"passkeyRegisterBegin","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Begin passkey registration","tags":["Me"]}},"/me/passkey/register/finish":{"post":{"operationId":"passkeyRegisterFinish","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Finish passkey registration","tags":["Me"]}},"/me/passkeys":{"delete":{"operationId":"deletePasskey","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Delete a passkey","tags":["Me"]},"get":{"operationId":"listPasskeys","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List my passkeys","tags":["Me"]}},"/me/password/change":{"post":{"operationId":"changePassword","requestBody":{"content":{"application/json":{"schema":{"properties":{"currentPassword":{"type":"string"},"newPassword":{"type":"string"}},"required":["currentPassword","newPassword"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Change my password","tags":["Me"]}},"/me/pig/feed":{"post":{"description":"data = { state (rewarded|cooldown|daily_cap|disabled|too_fast), rewarded, rewardCalls, todayRewarded, dailyCap, cooldownRemaining }. Rewards are granted only when pig.feed_reward_enabled is on; grants are capped per business day and rate-limited server-side.\n","operationId":"pigFeed","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Report a pig-feeding interaction (server-adjudicated reward)","tags":["Me"]}},"/me/pig/feed-status":{"get":{"description":"data = { rewardEnabled, rewardCalls, dailyCap, todayRewarded }.","operationId":"getPigFeedStatus","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Pig feeding reward config and today's progress","tags":["Me"]}},"/me/preferences":{"get":{"operationId":"getMyPreferences","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Get my notification / credit preferences","tags":["Me"]},"patch":{"operationId":"updateMyPreferences","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Update my preferences","tags":["Me"]}},"/me/quota":{"get":{"operationId":"getMyQuota","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"My quota usage (dashboard dimensions)","tags":["Me"]}},"/me/redeem":{"post":{"operationId":"redeemCode","requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"confirmDowngrade":{"type":"boolean"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Code expired / deactivated / fully used."}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Redeem a code (credits or plan)","tags":["Me"]}},"/me/redeem/history":{"get":{"operationId":"getRedeemHistory","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"My redemption history","tags":["Me"]}},"/me/security/login-activities":{"get":{"operationId":"listLoginActivities","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Recent login activity","tags":["Me"]}},"/me/security/sessions":{"get":{"operationId":"listSessions","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List active sessions","tags":["Me"]}},"/me/security/sessions/revoke-all":{"post":{"operationId":"revokeAllSessions","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Revoke all sessions except the current one","tags":["Me"]}},"/me/security/sessions/{id}":{"delete":{"operationId":"revokeSession","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Revoke a session","tags":["Me"]}},"/me/telegram/bind-token":{"post":{"operationId":"createTelegramBindToken","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Telegram bot not configured."}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Create a Telegram bind token + deep link","tags":["Me"]}},"/me/telegram/binding":{"delete":{"operationId":"deleteTelegramBinding","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Unbind Telegram","tags":["Me"]},"patch":{"description":"At least one of enabled / mailPush / announcementPush is required. enabled is the channel master switch (requires an active binding); mailPush and announcementPush are per-user sub-switches.","operationId":"updateTelegramEnabled","requestBody":{"content":{"application/json":{"schema":{"properties":{"announcementPush":{"type":"boolean"},"enabled":{"type":"boolean"},"mailPush":{"type":"boolean"}},"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Toggle Telegram notifications","tags":["Me"]}},"/me/telegram/status":{"get":{"description":"data = { botConfigured, botUsername, bound, username, enabled, mailPush, announcementPush }.","operationId":"getTelegramStatus","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Telegram binding status","tags":["Me"]}},"/me/telegram/test":{"post":{"operationId":"sendTelegramTest","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Send a Telegram test notification","tags":["Me"]}},"/me/twofa":{"get":{"description":"data = { enabled, confirmedAt, recoveryCodesRemaining }.","operationId":"getTwoFAStatus","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"2FA status","tags":["Me"]}},"/me/twofa/disable":{"post":{"operationId":"disableTwoFA","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Disable 2FA","tags":["Me"]}},"/me/twofa/enable":{"post":{"operationId":"enableTwoFA","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Confirm and enable 2FA","tags":["Me"]}},"/me/twofa/recovery-codes":{"post":{"operationId":"regenerateRecoveryCodes","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Regenerate 2FA recovery codes","tags":["Me"]}},"/me/twofa/setup":{"post":{"operationId":"setupTwoFA","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Begin 2FA setup (TOTP secret + QR)","tags":["Me"]}},"/me/unread-summary":{"get":{"description":"data = { activeInboxes, totalUnread, sampled }.","operationId":"getMyUnreadSummary","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Active inbox count + aggregated unread total","tags":["Me"]}},"/me/webhooks":{"get":{"description":"data = { webhooks, total }. Secrets are stripped (hasSecret + hint only).","operationId":"listMyWebhooks","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"List my webhooks","tags":["Me"]},"post":{"description":"Server generates a signing secret unless one is provided; the plaintext secret is shown once in this response.","operationId":"createWebhook","requestBody":{"content":{"application/json":{"schema":{"properties":{"events":{"items":{"enum":["message.received","message.deleted"],"type":"string"},"type":"array"},"secret":{"maxLength":256,"type":"string"},"url":{"maxLength":2048,"type":"string"}},"required":["url"],"type":"object"}}},"required":true},"responses":{"201":{"$ref":"#/components/responses/Created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Create a webhook","tags":["Me"]}},"/me/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Delete a webhook","tags":["Me"]},"patch":{"operationId":"updateWebhook","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Update a webhook","tags":["Me"]}},"/me/webhooks/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"List recent webhook deliveries","tags":["Me"]}},"/me/webhooks/{id}/regenerate-secret":{"post":{"deprecated":true,"operationId":"regenerateWebhookSecret","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Legacy alias of rotate-secret","tags":["Me"]}},"/me/webhooks/{id}/rotate-secret":{"post":{"description":"Old secret is invalidated; the new one is shown once.","operationId":"rotateWebhookSecret","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Rotate the webhook signing secret","tags":["Me"]}},"/me/webhooks/{id}/test":{"post":{"operationId":"testWebhook","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Send a signed test event","tags":["Me"]}},"/me/wildcard-rules":{"get":{"operationId":"listMyWildcardRules","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List my wildcard rules","tags":["Me"]}},"/me/wildcard-rules/{id}/assignments":{"get":{"operationId":"listWildcardAssignments","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List child-subdomain assignments of a wildcard rule","tags":["Me"]}},"/me/wildcard-rules/{id}/assignments/{assignmentId}":{"delete":{"operationId":"deleteWildcardAssignment","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"assignmentId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Delete a wildcard assignment","tags":["Me"]}},"/me/wildcard-rules/{id}/assignments/{assignmentId}/inboxes":{"get":{"operationId":"listWildcardAssignmentInboxes","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"assignmentId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List inboxes under a wildcard assignment","tags":["Me"]}},"/me/wildcard-rules/{id}/assignments/{assignmentId}/release":{"post":{"operationId":"releaseWildcardAssignment","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"assignmentId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Release a wildcard assignment (unbind inbox)","tags":["Me"]}},"/me/wildcard-rules/{id}/auto-allocate":{"post":{"operationId":"autoAllocateWildcard","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Auto-allocate the next sequential child subdomain","tags":["Me"]}},"/messages":{"get":{"operationId":"listMessages","parameters":[{"$ref":"#/components/parameters/address"},{"description":"Max items (default 50, max 200).","in":"query","name":"limit","schema":{"maximum":200,"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"messages":{"items":{"$ref":"#/components/schemas/MessageListItem"},"type":"array"},"total":{"type":"integer"},"unreadCount":{"type":"integer"}},"type":"object"}},"type":"object"}]}}},"description":"data = { messages, total, unreadCount }."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"tempToken":[]},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"List messages in an inbox","tags":["Messages"]}},"/messages/mark-read":{"post":{"description":"API keys need write permission.","operationId":"markMailboxRead","parameters":[{"$ref":"#/components/parameters/address"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { mailbox, updated, alreadySeen, total }."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]},{"tempToken":[]}],"summary":"Mark all messages in an inbox as read","tags":["Messages"]}},"/messages/next":{"get":{"description":"Returns the oldest unread message in scope and marks it read in the same operation. Designed for one-call verification-code retrieval: the response detail includes `verificationCode` when the server detects an OTP-style code. Concurrent callers never receive the same message. Returns 204 when no unread message exists (after the optional wait window).\n","operationId":"takeNextMessage","parameters":[{"description":"Restrict to one owned inbox; omit to take from all inboxes.","in":"query","name":"address","schema":{"type":"string"}},{"description":"Long-poll seconds (0-30) to hold the request until mail arrives.","in":"query","name":"wait","schema":{"maximum":30,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"inboxAddress":{"type":"string"},"message":{"$ref":"#/components/schemas/MessageDetail"}},"type":"object"}},"type":"object"}]}}},"description":"data = { message (MessageDetail incl. verificationCode), inboxAddress }."},"204":{"description":"No unread message in scope."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"tempToken":[]},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Take the next unread message (atomically marks it read)","tags":["Messages"]}},"/messages/{id}":{"delete":{"description":"API keys need write permission. Returns 204 on success.","operationId":"deleteMessage","parameters":[{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/address"}],"responses":{"204":{"description":"Message deleted (no body)."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]},{"tempToken":[]}],"summary":"Delete a message","tags":["Messages"]},"get":{"operationId":"getMessage","parameters":[{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/address"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/MessageDetail"}},"type":"object"}]}}},"description":"data = MessageDetail."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"tempToken":[]},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Get full message detail","tags":["Messages"]},"patch":{"description":"Back-compat semantics: a PATCH without a `starred` field marks the message read; a starred-only PATCH leaves `seen` untouched. Stars are per-user and require a JWT or API key identity. API keys need write permission.\n","operationId":"updateMessage","parameters":[{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/address"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"seen":{"type":"boolean"},"starred":{"type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { id, seen, starred? }."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]},{"tempToken":[]}],"summary":"Update message state (seen / starred)","tags":["Messages"]}},"/metrics":{"get":{"operationId":"metrics","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Metrics (internal)","tags":["Admin"],"x-internal":true}},"/openapi.json":{"get":{"operationId":"getOpenAPIJson","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OpenAPI 3.1 document converted from the YAML source."}},"summary":"This OpenAPI specification (JSON)","tags":["Public"]}},"/openapi.yaml":{"get":{"description":"Read-only, CORS-open. Importable into Postman / Swagger UI: https://maliapi.215.im/v1/openapi.yaml","operationId":"getOpenAPIYaml","responses":{"200":{"content":{"application/yaml":{"schema":{"type":"string"}}},"description":"OpenAPI 3.1 document."}},"summary":"This OpenAPI specification (YAML)","tags":["Public"]}},"/payment/balance-notify":{"get":{"description":"Called by the payment gateway, not by API clients. Signature-verified.","operationId":"balanceNotify","responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Plain-text gateway acknowledgement."}},"summary":"Balance top-up gateway async callback","tags":["Payment"]}},"/payment/checkout-options":{"post":{"operationId":"getCheckoutOptions","requestBody":{"content":{"application/json":{"schema":{"properties":{"confirmDowngrade":{"type":"boolean"},"planDays":{"type":"integer"},"planId":{"type":"string"}},"required":["planId"],"type":"object"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Get checkout quote + payment options for a plan","tags":["Payment"]}},"/payment/checkout-preview":{"post":{"deprecated":true,"operationId":"getCheckoutPreview","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Alias of checkout-options","tags":["Payment"]}},"/payment/create-order":{"post":{"operationId":"createPaymentOrder","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Create a plan purchase order (external gateway)","tags":["Payment"]}},"/payment/methods":{"get":{"operationId":"getPaymentMethods","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { methods }."}},"summary":"List enabled payment methods","tags":["Payment"]}},"/payment/notify":{"get":{"description":"Called by the payment gateway, not by API clients. Signature-verified.","operationId":"paymentNotify","responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Plain-text gateway acknowledgement."}},"summary":"Payment gateway async callback","tags":["Payment"]}},"/payment/orders":{"get":{"operationId":"listMyPaymentOrders","responses":{"200":{"$ref":"#/components/responses/OK"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"List my payment orders","tags":["Payment"]}},"/payment/orders/{id}/cancel":{"post":{"operationId":"cancelMyPaymentOrder","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Cancel my pending order","tags":["Payment"]}},"/payment/return":{"get":{"operationId":"paymentReturn","responses":{"302":{"description":"Redirects to the configured frontend return URL."}},"summary":"Post-payment browser redirect","tags":["Payment"]}},"/payment/upgrade-order":{"post":{"operationId":"createUpgradeOrder","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Create a prorated upgrade order","tags":["Payment"]}},"/payment/upgrade-preview":{"post":{"operationId":"getUpgradePreview","responses":{"200":{"$ref":"#/components/responses/OK"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"summary":"Preview a prorated plan upgrade","tags":["Payment"]}},"/plans":{"get":{"operationId":"listPlans","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/Plan"},"type":"array"}},"type":"object"}]}}},"description":"data = array of Plan."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List active plans","tags":["Public"]}},"/pricing":{"get":{"operationId":"getPricing","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { packages, addonPackages, rateLimits, currency }. addonPackages entries are { type: storage|inboxes, quantity, priceCents } — storage quantity is GB, inboxes quantity is persistent inbox slots (A3 purchased pool).\n"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Public pricing (API-call packages + capacity add-ons + rate-limit tiers)","tags":["Public"]}},"/sources/{id}":{"get":{"operationId":"getMessageSource","parameters":[{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/address"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { id, data } with the raw source as a string."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"tempToken":[]},{"cookieAuth":[]},{"bearerAuth":[]},{"apiKey":[]}],"summary":"Get raw RFC 822 message source","tags":["Messages"]}},"/stats":{"get":{"operationId":"getPublicStats","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = public stats snapshot (cached ~30s)."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Public platform statistics","tags":["Public"]}},"/token":{"post":{"description":"DuckMail-compatible. Requires the current (still valid) temp token for the same address; issues a fresh one.","operationId":"refreshTempToken","requestBody":{"content":{"application/json":{"schema":{"properties":{"address":{"type":"string"},"password":{"description":"Accepted for compatibility; ignored.","type":"string"}},"required":["address"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"data = { id, address, token }."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"tempToken":[]}],"summary":"Refresh the temp token for an inbox","tags":["Accounts"]}},"/ws":{"get":{"description":"HTTP GET upgrade to WebSocket. Authenticate with a short-lived ticket from GET /auth/ws-ticket (?ticket=...) or an auth cookie.\n","operationId":"websocket","responses":{"101":{"description":"Switching protocols (WebSocket upgrade)."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"description":"Too many concurrent WebSocket connections for this account (default cap 10, env YYDS_WS_MAX_CONNS_PER_USER). Close idle connections and retry.\n"}},"security":[{},{"cookieAuth":[]}],"summary":"WebSocket endpoint for realtime new-message events","tags":["Public"]}}},"security":[],"servers":[{"description":"Production","url":"https://maliapi.215.im/v1"}],"tags":[{"description":"No-auth discovery endpoints (health, domains, plans, pricing, stats).","name":"Public"},{"description":"Canonical inbox resource (naming convergence step 1). Prefer GET /inboxes/{id} and GET /inboxes/{id}/messages over the legacy accounts read alias and the address-keyed message list.\n","name":"Inboxes"},{"description":"Temporary inbox lifecycle (DuckMail/Mail.tm compatible surface).","name":"Accounts"},{"description":"Read, mark, and delete mail for an inbox you control.","name":"Messages"},{"description":"Public read-only mailbox share links.","name":"Mailbox Shares"},{"description":"Registration, login, tokens, OAuth, passkeys.","name":"Auth"},{"description":"Signed-in user resources (profile, inboxes, domains, API keys, webhooks...).","name":"Me"},{"description":"Orders, checkout, balance top-up.","name":"Payment"},{"description":"Public announcements and articles.","name":"Content"},{"description":"Internal console endpoints. Not part of the public contract.","name":"Admin","x-internal":true}]}