{"openapi":"3.1.0","info":{"title":"HPC Mail Session and Administration API","description":"JWT session API for all web-client functions. Authorization: Bearer <JWT> from login/register. hpcm_ API keys cannot authenticate these routes; see the related /v1 specification. Administrator endpoints require an active admin role. If site policy requires 2FA, un-enrolled sessions receive 403 totp_setup_required; /auth/me, logout and /auth/2fa routes remain available to complete setup.","version":"1.4.0","license":{"name":"MIT","identifier":"MIT"},"contact":{"name":"HPC Mail","url":"https://github.com/riba2534/hpc-mail"}},"servers":[{"url":"https://mail.starmontlabs.com/api"}],"security":[{"sessionToken":[]}],"externalDocs":{"description":"Agent usage guide and workflows","url":"https://mail.starmontlabs.com/skill.md"},"x-relatedApis":[{"url":"https://mail.starmontlabs.com/v1/openapi.json","description":"Scoped API-key mail/mailbox automation"}],"tags":[{"name":"Mail","description":"Session, mail, mailbox and personal preferences"},{"name":"Administration","description":"Administrator role required; no API-key scopes grant this role."}],"components":{"securitySchemes":{"sessionToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"attachmentSignature":{"type":"apiKey","in":"query","name":"sig"},"attachmentExpiry":{"type":"apiKey","in":"query","name":"exp"}},"schemas":{"AdminAuditLog":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"actorName":{"type":"string"},"action":{"type":"string"},"target":{"type":"string"},"detail":{"type":"string"},"ip":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","actorName","action","target","detail","ip","createdAt"]},"AdminUser":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"username":{"type":"string"},"role":{"type":"string","enum":["admin","user"]},"createdAt":{"type":"string","format":"date-time"},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","disabled"]},"mailboxCount":{"type":"integer","minimum":0},"mailboxes":{"type":"array","items":{"type":"string"}},"mailboxPolicy":{"anyOf":[{"type":"object","properties":{"perUserLimit":{"type":"integer","minimum":0,"maximum":10000},"domains":{"maxItems":64,"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^[a-z0-9.-]+\\.[a-z]{2,}$"},"perUserLimit":{"type":"integer","minimum":0,"maximum":10000}},"required":["domain","perUserLimit"]}}},"required":["perUserLimit","domains"]},{"type":"null"}]},"mailboxPolicyRevision":{"type":"integer","minimum":0},"apiKeyCount":{"type":"integer","minimum":0},"lastLoginAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","username","role","createdAt","avatarUrl","status","mailboxCount","mailboxes","mailboxPolicy","mailboxPolicyRevision","apiKeyCount","lastLoginAt"]},"AiModelTestRequest":{"type":"object","properties":{"baseUrl":{"anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"apiKey":{"type":"string","maxLength":512},"model":{"type":"string","maxLength":128}},"description":"All fields optional; the body may be omitted. Omitted or empty fields and apiKey ****** use the saved ai_model."},"AiModelTestResult":{"type":"object","properties":{"ok":{"const":true,"type":"boolean"},"latencyMs":{"type":"integer","minimum":0},"sample":{"type":"string","description":"Simplified Chinese translation of the fixed English sample."}},"required":["ok","latencyMs","sample"]},"ApiKeySummary":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"keyPrefix":{"type":"string"},"keySuffix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["mail.read","mail.write","mail.send","mailbox.read","mailbox.write"]}},"rateLimit":{"type":"integer","minimum":1},"allowedIps":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled","revoked"]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"ownerUsername":{"type":"string"}},"required":["id","name","keyPrefix","keySuffix","scopes","rateLimit","allowedIps","status","expiresAt","lastUsedAt","createdAt"]},"ApiRequestLog":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"requestId":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"},"statusCode":{"type":"integer","minimum":0},"ip":{"type":"string"},"durationMs":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"}},"required":["id","requestId","method","path","statusCode","ip","durationMs","createdAt"]},"Attachment":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"integer","minimum":0},"contentId":{"type":"string"},"disposition":{"type":"string"},"url":{"type":"string"}},"required":["id","filename","mimeType","size","contentId","disposition","url"]},"BatchClaimMailboxResult":{"type":"object","properties":{"claimed":{"type":"array","items":{"$ref":"#/components/schemas/Mailbox"}},"taken":{"type":"array","items":{"$ref":"#/components/schemas/ClaimMailboxRequest"},"description":"Skipped because the address is already claimed; request order."},"notAttempted":{"type":"array","items":{"$ref":"#/components/schemas/ClaimMailboxRequest"},"description":"Not attempted after stoppedBy, including the item that stopped the batch; request order."},"stoppedBy":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["validation_failed","unauthorized","forbidden","not_found","conflict","rate_limited","bad_credentials","user_disabled","totp_required","totp_setup_required","registration_closed","invite_invalid","address_taken","payload_too_large","internal"]},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["claimed","taken","notAttempted","stoppedBy"]},"BatchMailboxRequest":{"type":"object","properties":{"items":{"minItems":1,"maxItems":999,"type":"array","items":{"type":"object","properties":{"localPart":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9._+-]{0,62}[a-z0-9])?$"},"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^[a-z0-9.-]+\\.[a-z]{2,}$"},"strategy":{"type":"string","enum":["uniform","claude"]}},"required":["localPart","domain"]}}},"required":["items"]},"BatchShareMailboxesRequest":{"type":"object","properties":{"mailboxIds":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"userIds":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}},"required":["mailboxIds","userIds"]},"ChangePasswordRequest":{"type":"object","properties":{"oldPassword":{"type":"string","minLength":1,"maxLength":128},"newPassword":{"type":"string","minLength":8,"maxLength":128}},"required":["oldPassword","newPassword"]},"ClaimMailboxRequest":{"type":"object","properties":{"localPart":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9._+-]{0,62}[a-z0-9])?$"},"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^[a-z0-9.-]+\\.[a-z]{2,}$"},"strategy":{"type":"string","enum":["uniform","claude"],"description":"Optional. Omitted or uniform uses ordinary claim rules. claude rejects any domain with a historical Claude suspension, including for administrators and hosted domains; writes recheck atomically and return 403 forbidden: 该域名有 Claude 封号记录，不能在 Claude 0 封号模式下认领. Historical observations do not guarantee future safety."}},"required":["localPart","domain"]},"ClaimPlan":{"type":"object","properties":{"strategy":{"type":"string","enum":["uniform","claude"]},"items":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"suspended":{"type":"integer","minimum":0,"description":"Addresses on this domain that received a Claude suspension email, judged from historical official mail."}},"required":["domain","suspended"]},"description":"Allocated domains in allocation order; at most count items. Prefixes are chosen by the client."},"pool":{"type":"array","items":{"type":"string"},"description":"Domains the caller can claim that take part in random generation, still have quota, and satisfy this strategy. claude excludes every domain with a historical suspension."},"shortfall":{"type":"integer","minimum":0,"description":"count minus items length."},"reason":{"anyOf":[{"type":"string","enum":["quota","domain_quota","daily_limit","no_candidates"],"description":"quota: the per-user total claim limit ran out; domain_quota: per-domain limits of the eligible domains ran out; daily_limit (claude only): every zero-suspension domain with quota left reached claim_random.dailyLimit for the last 24 hours; no_candidates: no eligible domain."},{"type":"null"}]}},"required":["strategy","items","pool","shortfall","reason"]},"CompleteMultipartUploadRequest":{"type":"object","properties":{"parts":{"minItems":1,"type":"array","items":{"type":"object","properties":{"partNumber":{"type":"integer","minimum":1,"maximum":10000},"etag":{"type":"string","minLength":1}},"required":["partNumber","etag"]}}},"required":["parts"]},"CreateApiKeyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"scopes":{"minItems":1,"type":"array","items":{"type":"string","enum":["mail.read","mail.write","mail.send","mailbox.read","mailbox.write"]}},"rateLimit":{"default":120,"type":"integer","minimum":1,"maximum":600},"allowedIps":{"default":[],"maxItems":32,"type":"array","items":{"type":"string","pattern":"^(\\d{1,3}\\.){3}\\d{1,3}(\\/\\d{1,2})?$|^[0-9a-fA-F:]+(\\/\\d{1,3})?$"}},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["name","scopes"]},"CreateHostedDomainRequest":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^[a-z0-9.-]+\\.[a-z]{2,}$"}},"required":["domain"]},"CreateInviteRequest":{"type":"object","properties":{"count":{"default":1,"type":"integer","minimum":1,"maximum":50},"maxUses":{"default":1,"type":"integer","minimum":1,"maximum":1000},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"note":{"default":"","type":"string","maxLength":128}}},"CreateUserRequest":{"type":"object","properties":{"username":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{2,31}$"},"password":{"type":"string","minLength":8,"maxLength":128},"role":{"default":"user","type":"string","enum":["admin","user"]}},"required":["username","password"]},"CreatedApiKey":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"keyPrefix":{"type":"string"},"keySuffix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["mail.read","mail.write","mail.send","mailbox.read","mailbox.write"]}},"rateLimit":{"type":"integer","minimum":1},"allowedIps":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled","revoked"]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"ownerUsername":{"type":"string"},"key":{"type":"string","description":"Full hpcm_ key, returned only once at creation. Save securely."}},"required":["id","name","keyPrefix","keySuffix","scopes","rateLimit","allowedIps","status","expiresAt","lastUsedAt","createdAt","key"]},"DisableTwoFactorRequest":{"type":"object","properties":{"password":{"type":"string","maxLength":128},"code":{"type":"string","maxLength":32}}},"DomainClaudeStats":{"type":"object","properties":{"domain":{"type":"string"},"accounts":{"type":"integer","minimum":0,"description":"Addresses that received a Claude welcome, receipt, subscription confirmation, suspension or Claude product email from official senders."},"suspended":{"type":"integer","minimum":0},"paid":{"type":"integer","minimum":0},"paidSuspended":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0,"description":"Mailboxes claimed within claim_random.pendingDays that have not received Claude mail."},"recent":{"type":"integer","minimum":0,"description":"New in the last 24 hours: Claude accounts first seen plus newly claimed mailboxes without Claude mail. The Claude zero-suspension strategy stops allocating the domain once this reaches claim_random.dailyLimit."},"risk":{"anyOf":[{"type":"string","enum":["suspended","wiped","paid_suspended","suspended_rate"],"description":"suspended: any historical suspension exists, so the domain is excluded from the Claude zero-suspension strategy. Legacy enum values are retained for compatibility; new responses use suspended or null. Historical observations do not guarantee future safety."},{"type":"null"}]}},"required":["domain","accounts","suspended","paid","paidSuspended","pending","recent","risk"]},"DomainStatus":{"type":"object","properties":{"domain":{"type":"string"},"inList":{"type":"boolean"},"mxReady":{"type":"boolean"},"spfReady":{"type":"boolean"},"mxRecords":{"type":"array","items":{"type":"string"}},"resolved":{"type":"boolean"}},"required":["domain","inList","mxReady","spfReady","mxRecords","resolved"]},"EnableTwoFactorRequest":{"type":"object","properties":{"code":{"type":"string","pattern":"^\\d{6}$"}},"required":["code"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_failed","unauthorized","forbidden","not_found","conflict","rate_limited","bad_credentials","user_disabled","totp_required","totp_setup_required","registration_closed","invite_invalid","address_taken","payload_too_large","internal"]},"message":{"type":"string"}},"required":["code","message"]},"requestId":{"type":"string"}},"required":["error","requestId"]},"HostedDnsRecord":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Cloudflare DNS record id: 32 lowercase hex characters."},"type":{"type":"string","description":"Cloudflare record type; readonly records may use types outside the editable A/AAAA/CNAME/TXT/MX/SRV/CAA."},"name":{"type":"string","description":"Relative name: @ for the root, otherwise the name without the domain suffix, e.g. www, _acme-challenge, *.dev."},"fqdn":{"type":"string"},"content":{"type":"string","description":"Value as returned by Cloudflare. TXT may be quoted; SRV is \"weight port target\"; CAA is flags tag \"value\"."},"ttl":{"type":"integer","minimum":1,"description":"1 means automatic."},"priority":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"MX preference; null for other types."},"srv":{"anyOf":[{"type":"object","properties":{"priority":{"type":"integer","minimum":0},"weight":{"type":"integer","minimum":0},"port":{"type":"integer","minimum":0},"target":{"type":"string"}},"required":["priority","weight","port","target"]},{"type":"null"}]},"caa":{"anyOf":[{"type":"object","properties":{"flags":{"type":"integer","minimum":0},"tag":{"type":"string"},"value":{"type":"string"}},"required":["flags","tag","value"]},{"type":"null"}],"description":"CAA data as stored in Cloudflare. Editable records use flags 0 or 128 and tag issue/issuewild/iodef; other values only appear on kind=readonly records."},"proxied":{"type":"boolean","description":"Cloudflare proxy. This site never enables it; proxied records are readonly."},"comment":{"type":"string"},"kind":{"type":"string","enum":["user","mail","readonly"],"description":"user: editable here; an existing record that conflicts with mail, such as a root CNAME created in the Cloudflare dashboard, is still user so it can be deleted, while saving it returns 400 with the conflict reason. mail: used by receiving or sending (root MX and SPF, _dmarc, DKIM under _domainkey, cf-bounce, or marked email_routing by Cloudflare); never editable. readonly: a type this site does not edit, a CAA record outside the editable flags/tags, a proxied record, or one maintained by another Cloudflare service (marked read_only only)."},"lockedReason":{"type":"string","description":"Why a mail or readonly record cannot be changed; empty for user records."},"modifiedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","type","name","fqdn","content","ttl","priority","srv","caa","proxied","comment","kind","lockedReason","modifiedAt"]},"HostedDnsRecordInput":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"A"},"name":{"type":"string","minLength":1,"maxLength":253},"ttl":{"type":"integer","anyOf":[{"const":1},{"minimum":60,"maximum":86400}],"description":"1 means automatic."},"comment":{"default":"","type":"string","maxLength":100},"content":{"type":"string","format":"ipv4"}},"required":["type","name","ttl","content"]},{"type":"object","properties":{"type":{"type":"string","const":"AAAA"},"name":{"type":"string","minLength":1,"maxLength":253},"ttl":{"type":"integer","anyOf":[{"const":1},{"minimum":60,"maximum":86400}],"description":"1 means automatic."},"comment":{"default":"","type":"string","maxLength":100},"content":{"type":"string","format":"ipv6"}},"required":["type","name","ttl","content"]},{"type":"object","properties":{"type":{"type":"string","const":"CNAME"},"name":{"type":"string","minLength":1,"maxLength":253},"ttl":{"type":"integer","anyOf":[{"const":1},{"minimum":60,"maximum":86400}],"description":"1 means automatic."},"comment":{"default":"","type":"string","maxLength":100},"content":{"type":"string","minLength":1,"maxLength":253}},"required":["type","name","ttl","content"]},{"type":"object","properties":{"type":{"type":"string","const":"TXT"},"name":{"type":"string","minLength":1,"maxLength":253},"ttl":{"type":"integer","anyOf":[{"const":1},{"minimum":60,"maximum":86400}],"description":"1 means automatic."},"comment":{"default":"","type":"string","maxLength":100},"content":{"type":"string","minLength":1,"maxLength":2048}},"required":["type","name","ttl","content"]},{"type":"object","properties":{"type":{"type":"string","const":"MX"},"name":{"type":"string","minLength":1,"maxLength":253},"ttl":{"type":"integer","anyOf":[{"const":1},{"minimum":60,"maximum":86400}],"description":"1 means automatic."},"comment":{"default":"","type":"string","maxLength":100},"content":{"type":"string","minLength":1,"maxLength":253},"priority":{"type":"integer","minimum":0,"maximum":65535}},"required":["type","name","ttl","content","priority"]},{"type":"object","properties":{"type":{"type":"string","const":"SRV"},"name":{"type":"string","minLength":1,"maxLength":253},"ttl":{"type":"integer","anyOf":[{"const":1},{"minimum":60,"maximum":86400}],"description":"1 means automatic."},"comment":{"default":"","type":"string","maxLength":100},"srv":{"type":"object","properties":{"priority":{"type":"integer","minimum":0,"maximum":65535},"weight":{"type":"integer","minimum":0,"maximum":65535},"port":{"type":"integer","minimum":0,"maximum":65535},"target":{"type":"string","minLength":1,"maxLength":253}},"required":["priority","weight","port","target"]}},"required":["type","name","ttl","srv"]},{"type":"object","properties":{"type":{"type":"string","const":"CAA"},"name":{"type":"string","minLength":1,"maxLength":253},"ttl":{"type":"integer","anyOf":[{"const":1},{"minimum":60,"maximum":86400}],"description":"1 means automatic."},"comment":{"default":"","type":"string","maxLength":100},"caa":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","const":0},{"type":"number","const":128}]},"tag":{"type":"string","enum":["issue","issuewild","iodef"]},"value":{"type":"string","minLength":1,"maxLength":255}},"required":["flags","tag","value"]}},"required":["type","name","ttl","caa"]}],"description":"Selected by type. name is relative (@ for the root, www, _dmarc, *.dev) or a full name ending with the domain. ttl is 1 (automatic) or 60–86400 seconds. A/AAAA/CNAME/TXT use content, MX uses content and priority, SRV uses srv, CAA uses caa. comment is optional (empty clears it on update)."},"HostedDomain":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$","description":"Normalized lowercase DNS name. Each label is 1–63 characters and cannot start/end with a hyphen."},"status":{"type":"string","enum":["pending","provisioning","active","error","moved","suspended","deleting"],"description":"pending: waiting for the registrar nameservers to be changed; provisioning: nameservers active, Email Routing / catch-all / Email Sending being configured; active: receiving and sending ready; error: active nameservers but configuration or health check failed, retried automatically; moved: nameservers no longer point here; suspended: stopped by an administrator; deleting: mail, addresses and Cloudflare configuration are being removed."},"role":{"type":"string","enum":["owner","member","admin"],"description":"Caller relationship: owner, member granted by sharing, or administrator viewing another user’s domain."},"ownerUserId":{"type":"integer","minimum":1},"ownerUsername":{"type":"string"},"nameServers":{"type":"array","items":{"type":"string"},"description":"Set exactly these nameservers at the registrar."},"originalNameServers":{"type":"array","items":{"type":"string"},"description":"Nameservers detected when the domain was added; restore them before deleting the hosted domain."},"originalRegistrar":{"type":"string"},"steps":{"type":"object","properties":{"nameServers":{"type":"string","enum":["waiting","ready","error"]},"routing":{"type":"string","enum":["waiting","ready","error"]},"catchAll":{"type":"string","enum":["waiting","ready","error"]},"sending":{"type":"string","enum":["waiting","ready","error"]}},"required":["nameServers","routing","catchAll","sending"]},"warnings":{"type":"array","items":{"type":"string"},"description":"Actions required from the owner, such as disabling DNSSEC before changing nameservers."},"lastError":{"type":"string"},"memberLimit":{"type":"integer","minimum":0,"description":"Per-member claim limit on this domain; 0 means unlimited."},"memberCount":{"type":"integer","minimum":0},"mailboxCount":{"type":"integer","minimum":0,"description":"Claimed addresses on this domain across all users."},"createdAt":{"type":"string","format":"date-time"},"activatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"checkedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"While pending, the domain is deleted automatically if the nameservers are not changed by this time."}},"required":["id","domain","status","role","ownerUserId","ownerUsername","nameServers","originalNameServers","originalRegistrar","steps","warnings","lastError","memberLimit","memberCount","mailboxCount","createdAt","activatedAt","checkedAt","expiresAt"]},"HostedDomainMember":{"type":"object","properties":{"userId":{"type":"integer","minimum":1},"username":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"grantedAt":{"type":"string","format":"date-time"},"mailboxCount":{"type":"integer","minimum":0,"description":"Addresses this member claimed on the domain."}},"required":["userId","username","status","grantedAt","mailboxCount"]},"HostedDomainTransferResult":{"type":"object","properties":{"domain":{"$ref":"#/components/schemas/HostedDomain"},"previousUserId":{"type":"integer","minimum":1},"transferred":{"type":"boolean"},"movedMailboxes":{"type":"integer","minimum":0,"description":"Mailboxes of the previous owner moved with the domain when includeMailboxes was true."}},"required":["domain","previousUserId","transferred","movedMailboxes"]},"HostedDomainsHealth":{"type":"object","properties":{"enabled":{"type":"boolean"},"configured":{"type":"boolean","description":"Worker secrets cf_api_token and cf_account_id are set."},"tokenValid":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"error":{"type":"string"},"accountZones":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"accountPendingZones":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]}},"required":["enabled","configured","tokenValid","error","accountZones","accountPendingZones"]},"InitMultipartUploadRequest":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"mimeType":{"type":"string","minLength":3,"maxLength":128},"size":{"type":"integer","exclusiveMinimum":0,"maximum":52428800}},"required":["filename","mimeType","size"]},"Invite":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"code":{"type":"string"},"maxUses":{"type":"integer","minimum":1},"usedCount":{"type":"integer","minimum":0},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"note":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["usable","exhausted","expired","revoked"]},"usedBy":{"type":"array","items":{"type":"string"}}},"required":["id","code","maxUses","usedCount","expiresAt","note","createdAt","status","usedBy"]},"LoginRequest":{"type":"object","properties":{"username":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{2,31}$"},"password":{"type":"string","minLength":1,"maxLength":128},"totp":{"type":"string","maxLength":32}},"required":["username","password"]},"LoginResponse":{"type":"object","properties":{"token":{"type":"string","description":"Bearer JWT session token; store securely and never include it in published logs."},"user":{"$ref":"#/components/schemas/SessionUser"}},"required":["token","user"]},"Mailbox":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"address":{"type":"string"},"domain":{"type":"string"},"userId":{"type":"integer","minimum":1},"ownerUsername":{"type":"string"},"displayName":{"type":"string"},"messageCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"}},"required":["id","address","domain","userId","displayName","messageCount","createdAt"]},"MailboxAvailability":{"type":"object","properties":{"address":{"type":"string"},"available":{"type":"boolean"},"reason":{"type":"string","enum":["taken","reserved","quota","domain_limit","domain_unavailable","claude_suspended"],"description":"Present only when available=false. taken: already claimed; reserved: system-reserved prefix; quota: caller reached the per-user claim limit; domain_limit: caller reached this domain’s per-user limit; domain_unavailable: domain not configured or not allowed by the caller’s public/dedicated policy. claude_suspended: strategy=claude and any historical suspension on this domain, including for administrators and hosted domains. Same rules and order as claiming."}},"required":["address","available"]},"MailboxShareGrant":{"type":"object","properties":{"mailboxId":{"type":"integer","minimum":1},"address":{"type":"string"},"domain":{"type":"string"},"displayName":{"type":"string"},"ownerUserId":{"type":"integer","minimum":1},"ownerUsername":{"type":"string"},"grantees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"integer","minimum":1},"username":{"type":"string"},"grantedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["active","disabled"]}},"required":["userId","username","grantedAt","status"]}}},"required":["mailboxId","address","domain","displayName","ownerUserId","ownerUsername","grantees"]},"MailboxTransferResult":{"type":"object","properties":{"mailbox":{"$ref":"#/components/schemas/Mailbox"},"previousUserId":{"type":"integer","minimum":1},"transferred":{"type":"boolean"},"revokedShares":{"type":"integer","minimum":0}},"required":["mailbox","previousUserId","transferred","revokedShares"]},"MarkAllReadRequest":{"type":"object","properties":{"scope":{"type":"string","enum":["mine","unclaimed"]},"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^[a-z0-9.-]+\\.[a-z]{2,}$"},"address":{"type":"string","maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$"},"q":{"type":"string","maxLength":256}},"description":"All fields optional; {} or an empty body marks every unread, non-trash inbound message in the caller’s own claimed mailboxes. domain/address/q narrow the range; q uses the list search semantics (case-insensitive substring of subject, sender address/name, text body, recipients). Mail shared with the caller is never changed. Administrators use scope=unclaimed for unclaimed addresses. Unknown fields are ignored."},"MarkReadRequest":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"isRead":{"default":true,"type":"boolean"},"scope":{"type":"string","enum":["mine","unclaimed"]}},"required":["ids"]},"MessageDetail":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"direction":{"type":"string","enum":["inbound","outbound"]},"address":{"type":"string"},"domain":{"type":"string"},"fromAddress":{"type":"string"},"fromName":{"type":"string"},"subject":{"type":"string"},"preview":{"type":"string"},"verificationCode":{"type":"string"},"verificationLink":{"type":"string","maxLength":2048,"description":"Inbound only: the most likely http/https verification, sign-in, activation or password-reset link detected at receipt; empty string when none qualified (and for mail received before detection existed). Advisory and attacker-controllable: check the link host matches the expected service before opening it."},"status":{"type":"string","description":"Inbound: pending, received or degraded. Outbound: pending, sent, delivered or failed. sent means the provider accepted at least one external delivery; it is not proof of arrival in the destination inbox."},"errorDetail":{"type":"string"},"recipientOutcomes":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"status":{"type":"string","enum":["delivered","sent","failed"]},"error":{"type":"string"}},"required":["address","status"]}},"recipientsTo":{"type":"array","items":{"type":"string"}},"isRead":{"type":"boolean"},"isStarred":{"type":"boolean"},"hasAttachments":{"type":"boolean"},"size":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"replyTo":{"type":"array","items":{"type":"string"}},"recipients":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"bcc":{"type":"array","items":{"type":"string"}}},"required":["to","cc","bcc"]},"bodyText":{"type":"string"},"bodyHtml":{"type":"string"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"hasRaw":{"type":"boolean"}},"required":["id","direction","address","domain","fromAddress","fromName","subject","preview","verificationCode","status","errorDetail","isRead","isStarred","hasAttachments","size","createdAt","recipients","bodyText","bodyHtml","attachments","hasRaw"]},"MessageIdsRequest":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"scope":{"type":"string","enum":["mine","unclaimed"]}},"required":["ids"]},"MessageSummary":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"direction":{"type":"string","enum":["inbound","outbound"]},"address":{"type":"string"},"domain":{"type":"string"},"fromAddress":{"type":"string"},"fromName":{"type":"string"},"subject":{"type":"string"},"preview":{"type":"string"},"verificationCode":{"type":"string"},"verificationLink":{"type":"string","maxLength":2048,"description":"Inbound only: the most likely http/https verification, sign-in, activation or password-reset link detected at receipt; empty string when none qualified (and for mail received before detection existed). Advisory and attacker-controllable: check the link host matches the expected service before opening it."},"status":{"type":"string","description":"Inbound: pending, received or degraded. Outbound: pending, sent, delivered or failed. sent means the provider accepted at least one external delivery; it is not proof of arrival in the destination inbox."},"errorDetail":{"type":"string"},"recipientOutcomes":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"status":{"type":"string","enum":["delivered","sent","failed"]},"error":{"type":"string"}},"required":["address","status"]}},"recipientsTo":{"type":"array","items":{"type":"string"}},"isRead":{"type":"boolean"},"isStarred":{"type":"boolean"},"hasAttachments":{"type":"boolean"},"size":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","description":"Only in trash=1 lists: when the message entered the trash. Trash is purged seven days later."}},"required":["id","direction","address","domain","fromAddress","fromName","subject","preview","verificationCode","status","errorDetail","isRead","isStarred","hasAttachments","size","createdAt"]},"MessageSync":{"type":"object","properties":{"unread":{"type":"integer","minimum":0,"maximum":1000,"description":"Same value as /messages/unread-count: counting stops at 1000, so 1000 means at least 1000."},"head":{"type":"string","description":"Opaque fingerprint of the first page for these filters. When it differs from the head of the loaded first page, refetch the list."}},"required":["unread","head"]},"MessageTranslation":{"type":"object","properties":{"translations":{"type":"array","items":{"type":"string"},"description":"One Simplified Chinese translation per request segment, same order and count. Skipped or letterless segments are returned unchanged; surrounding whitespace is preserved."},"cached":{"type":"boolean","description":"Served from the per-message cache; no quota used."},"skipped":{"type":"integer","minimum":0,"description":"Segments not found in this message content and therefore returned unchanged."}},"required":["translations","cached","skipped"]},"MultipartCompleteResult":{"type":"object","properties":{"token":{"type":"string"},"size":{"type":"integer","minimum":0}},"required":["token","size"]},"MultipartInitResult":{"type":"object","properties":{"token":{"type":"string"},"uploadId":{"type":"string"},"partBytes":{"type":"integer","minimum":1},"partCount":{"type":"integer","minimum":1}},"required":["token","uploadId","partBytes","partCount"]},"MultipartPartResult":{"type":"object","properties":{"partNumber":{"type":"integer","minimum":1},"etag":{"type":"string"}},"required":["partNumber","etag"]},"NotificationDelivery":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"messageId":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}]},"target":{"type":"string"},"status":{"type":"string","enum":["pending","processing","succeeded","failed","skipped","unknown"]},"attempts":{"type":"integer","minimum":0},"maxAttempts":{"type":"integer","minimum":1},"lastError":{"type":"string"},"lastHttpStatus":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"nextAttemptAt":{"type":"string","format":"date-time"},"lastAttemptAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","messageId","target","status","attempts","maxAttempts","lastError","lastHttpStatus","createdAt","updatedAt","nextAttemptAt","lastAttemptAt"]},"NotificationHealth":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["feishu","pushdeer","webhook","forward"]},"enabled":{"type":"boolean"},"latest":{"anyOf":[{"$ref":"#/components/schemas/NotificationDelivery"},{"type":"null"}]},"pendingCount":{"type":"integer","minimum":0},"failedCount":{"type":"integer","minimum":0}},"required":["channel","enabled","latest","pendingCount","failedCount"]}},"forward":{"type":"object","properties":{"domainLimit":{"type":"integer","minimum":0},"targetLimit":{"type":"integer","minimum":0},"windowEndsAt":{"type":"string","format":"date-time"},"targets":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"attempts":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0}},"required":["address","attempts","remaining"]}},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"attempts":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0}},"required":["domain","attempts","remaining"]}}},"required":["domainLimit","targetLimit","windowEndsAt","targets","domains"]}},"required":["channels","forward"]},"NotifyPrefs":{"type":"object","properties":{"feishu":{"type":"object","properties":{"enabled":{"type":"boolean"},"webhookUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"secret":{"default":"","type":"string","maxLength":128},"contentLevel":{"default":"summary","type":"string","enum":["code_only","summary","full"]}},"required":["enabled","webhookUrl","secret","contentLevel"],"additionalProperties":false},"webhook":{"type":"object","properties":{"enabled":{"type":"boolean"},"url":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"secret":{"default":"","type":"string","maxLength":128}},"required":["enabled","url","secret"],"additionalProperties":false},"forward":{"type":"object","properties":{"enabled":{"type":"boolean"},"addresses":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$"}}},"required":["enabled","addresses"],"additionalProperties":false},"pushdeer":{"default":{"enabled":false,"endpoint":"","pushkey":""},"type":"object","properties":{"enabled":{"type":"boolean"},"endpoint":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^http.*"}]},"pushkey":{"default":"","type":"string","maxLength":128}},"required":["enabled","endpoint","pushkey"],"additionalProperties":false}},"required":["feishu","webhook","forward","pushdeer"],"additionalProperties":false,"description":"Personal preferences. Configured feishu.secret, webhook.secret and pushdeer.pushkey are returned as ******; plaintext secrets are never returned. In updates ****** preserves the secret and an explicit empty string clears it. Enabled configurations must have valid complete endpoints/keys/forward addresses. These are mail-owner notifications; shared mailbox readers do not receive owner notifications."},"PublicConfig":{"type":"object","properties":{"siteTitle":{"type":"string"},"registrationMode":{"type":"string","enum":["closed","invite","open"]},"domains":{"type":"array","items":{"type":"string"}},"require2fa":{"type":"boolean"},"translationEnabled":{"type":"boolean","description":"translation.enabled is on and ai_model has baseUrl, apiKey and model configured; provider details are never public."},"hostedDomainsEnabled":{"type":"boolean","description":"hosted_domains.enabled is on and the Worker has Cloudflare credentials, so users can add their own domains."}},"required":["siteTitle","registrationMode","domains","require2fa","translationEnabled","hostedDomainsEnabled"]},"RegisterRequest":{"type":"object","properties":{"username":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{2,31}$"},"password":{"type":"string","minLength":8,"maxLength":128},"inviteCode":{"type":"string","minLength":1,"maxLength":64}},"required":["username","password"]},"ReplaceHostedDomainMembersRequest":{"type":"object","properties":{"userIds":{"maxItems":100,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"expectedOwnerId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["userIds","expectedOwnerId"]},"ReplaceMailboxSharesRequest":{"type":"object","properties":{"mailboxId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"userIds":{"maxItems":100,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"expectedOwnerId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["mailboxId","userIds"]},"SendMailRequest":{"type":"object","properties":{"from":{"type":"object","properties":{"mailboxId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"localPart":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9._+-]{0,62}[a-z0-9])?$"},"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^[a-z0-9.-]+\\.[a-z]{2,}$"},"displayName":{"type":"string","maxLength":64}},"oneOf":[{"required":["mailboxId"],"not":{"anyOf":[{"required":["localPart"],"properties":{"localPart":{"type":"string"}}},{"required":["domain"],"properties":{"domain":{"type":"string"}}}]}},{"required":["localPart","domain"],"not":{"required":["mailboxId"],"properties":{"mailboxId":{"type":"integer","minimum":1}}}}]},"to":{"type":"array","items":{"type":"string","maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$"}},"cc":{"default":[],"type":"array","items":{"type":"string","maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$"}},"bcc":{"default":[],"type":"array","items":{"type":"string","maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$"}},"subject":{"type":"string","minLength":1,"maxLength":998},"text":{"type":"string","maxLength":1048576},"html":{"type":"string","maxLength":1048576},"replyToMessageId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"forwardAttachmentsFrom":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"attachments":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"contentType":{"type":"string","minLength":3,"maxLength":128},"content":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9+/\\s]+(?:=\\s*){0,2}$","description":"Base64 content; whitespace is allowed and removed before decoding. Combined decoded attachments must be at most 50 MiB."}},"required":["filename","contentType","content"]}},"attachmentTokens":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","minLength":1}}},"required":["from","to","subject"],"description":"At least one recipient across to/cc/bcc; combined maximum 100. At least one nonempty text/html body; combined UTF-8 body maximum 1048576 bytes. At most 10 total attachments, including tokens and source-message attachments. Base64 allows whitespace. A mailboxId must belong to the caller; ordinary users must own localPart+domain, and administrator explicit identities use configured/routable domains. Existing owned mailboxes remain usable when their domain is removed from the new-claim list. Shared mailboxes never grant send permission. replyToMessageId adds thread headers; use the original replyTo addresses from message detail as the new recipients. forwardAttachmentsFrom copies all original attachments and preserves inline CID images.","anyOf":[{"required":["text"],"properties":{"text":{"minLength":1}}},{"required":["html"],"properties":{"html":{"minLength":1}}}],"x-max-body-utf8-bytes":1048576,"x-max-total-recipients":100,"x-max-total-attachments":10,"x-max-attachment-bytes":52428800},"SessionMessagePage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MessageSummary"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"head":{"type":"string","description":"First page only (no cursor and no afterId): opaque fingerprint of this page for the current filters, same algorithm as /messages/sync head. Compare for equality only."}},"required":["items","nextCursor"]},"SessionUser":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"username":{"type":"string"},"role":{"type":"string","enum":["admin","user"]},"createdAt":{"type":"string","format":"date-time"},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"twoFactorEnabled":{"type":"boolean"}},"required":["id","username","role","createdAt","avatarUrl","twoFactorEnabled"]},"Settings":{"type":"object","properties":{"register_mode":{"type":"string","enum":["closed","invite","open"]},"code_extract":{"type":"object","properties":{"enabled":{"type":"boolean"},"aiEnabled":{"type":"boolean"}},"required":["enabled","aiEnabled"],"additionalProperties":false},"site":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":64}},"required":["title"],"additionalProperties":false},"api":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"domains":{"type":"object","properties":{"list":{"maxItems":64,"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^[a-z0-9.-]+\\.[a-z]{2,}$"},"public":{"default":false,"type":"boolean"},"perUserLimit":{"default":0,"type":"integer","minimum":0,"maximum":10000},"random":{"type":"boolean"}},"required":["domain","public","perUserLimit"],"additionalProperties":false}},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["list"],"additionalProperties":false},"retention":{"type":"object","properties":{"unclaimedDays":{"type":"integer","minimum":0,"maximum":3650},"allMessagesDays":{"type":"integer","minimum":0,"maximum":3650}},"required":["unclaimedDays","allMessagesDays"],"additionalProperties":false},"quota":{"type":"object","properties":{"dailyOutbound":{"type":"integer","minimum":0,"maximum":100000},"dailyRecipients":{"type":"integer","minimum":0,"maximum":1000000}},"required":["dailyOutbound","dailyRecipients"],"additionalProperties":false},"mailbox_policy":{"type":"object","properties":{"perUserLimit":{"type":"integer","minimum":0,"maximum":10000},"reservedLocalParts":{"maxItems":200,"type":"array","items":{"type":"string","maxLength":64}}},"required":["perUserLimit","reservedLocalParts"],"additionalProperties":false},"security":{"type":"object","properties":{"require2fa":{"type":"boolean"}},"required":["require2fa"],"additionalProperties":false},"ai_model":{"type":"object","properties":{"baseUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"apiKey":{"default":"","type":"string","maxLength":512,"description":"Write-only provider key. Responses return ****** when a key is stored (empty string when none). Submitting ****** keeps the stored key; an empty string clears it."},"model":{"default":"","type":"string","maxLength":128}},"required":["baseUrl","apiKey","model"],"additionalProperties":false,"description":"The single OpenAI-compatible Chat Completions model used by every AI feature: message translation and the inbound verification-code fallback. Configured means baseUrl, apiKey and model are all nonempty; baseUrl must be https and excludes /chat/completions. When translation is enabled, segments a user chooses to translate are sent to it; when code_extract.aiEnabled is on, the subject and first 6000 body characters of inbound mail that the regex could not resolve and that mentions a code-related keyword are sent to it. Unconfigured: translation is unavailable and code extraction uses regex only."},"translation":{"type":"object","properties":{"enabled":{"type":"boolean"},"dailyCharsPerUser":{"default":200000,"type":"integer","minimum":0,"maximum":10000000}},"required":["enabled","dailyCharsPerUser"],"additionalProperties":false,"description":"AI translation switch and quota. Enabling requires a configured ai_model (checked against the merged result when both are submitted). dailyCharsPerUser limits characters sent per user per UTC day, administrators included; 0 is unlimited."},"claim_random":{"type":"object","properties":{"paidSuspendedLimit":{"default":2,"type":"integer","minimum":0,"maximum":1000,"deprecated":true,"description":"Compatibility only; ignored for eligibility. Any historical Claude suspension always excludes the domain."},"pendingDays":{"default":7,"type":"integer","minimum":0,"maximum":90},"suspendedPercent":{"default":50,"type":"integer","minimum":0,"maximum":100,"deprecated":true,"description":"Compatibility only; ignored for eligibility. Any historical Claude suspension always excludes the domain."},"dailyLimit":{"default":3,"type":"integer","minimum":0,"maximum":1000}},"required":["paidSuspendedLimit","pendingDays","suspendedPercent","dailyLimit"],"additionalProperties":false,"description":"Rules for the Claude zero-suspension random suffix strategy. Any historical suspension excludes a domain. paidSuspendedLimit and suspendedPercent are deprecated compatibility fields and never change eligibility, including when zero. pendingDays counts recently claimed mailboxes without Claude mail as load (0 disables). dailyLimit caps additions in the last 24 hours (Claude accounts first seen plus new claims without Claude mail), including this plan (0 disables); full zero-suspension domains never spill over to suspended domains. domains.list[].random controls participation."},"hosted_domains":{"type":"object","properties":{"enabled":{"type":"boolean"},"maxPerUser":{"type":"integer","minimum":0,"maximum":1000},"maxPendingPerUser":{"type":"integer","minimum":1,"maximum":100},"maxPendingTotal":{"type":"integer","minimum":1,"maximum":1000},"pendingDays":{"type":"integer","minimum":1,"maximum":28},"autoClaimLimit":{"default":0,"type":"integer","minimum":0,"maximum":100000}},"required":["enabled","maxPerUser","maxPendingPerUser","maxPendingTotal","pendingDays","autoClaimLimit"],"additionalProperties":false}},"required":["register_mode","code_extract","site","api","domains","retention","quota","mailbox_policy","security","ai_model","translation","claim_random","hosted_domains"]},"SharedMailbox":{"type":"object","properties":{"mailboxId":{"type":"integer","minimum":1},"address":{"type":"string"},"domain":{"type":"string"},"displayName":{"type":"string"},"ownerUsername":{"type":"string"}},"required":["mailboxId","address","domain","displayName","ownerUsername"]},"SingleUploadResult":{"type":"object","properties":{"token":{"type":"string"},"filename":{"type":"string"},"size":{"type":"integer","minimum":0},"mimeType":{"type":"string"}},"required":["token","filename","size","mimeType"]},"StarMessagesRequest":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"starred":{"default":true,"type":"boolean"},"scope":{"type":"string","enum":["mine","unclaimed"]}},"required":["ids"]},"TransferHostedDomainRequest":{"type":"object","properties":{"userId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"expectedOwnerId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"includeMailboxes":{"type":"boolean"}},"required":["userId","expectedOwnerId","includeMailboxes"]},"TransferMailboxRequest":{"type":"object","properties":{"userId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"expectedOwnerId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["userId","expectedOwnerId"]},"TranslateMessageRequest":{"type":"object","properties":{"segments":{"minItems":1,"maxItems":60,"type":"array","items":{"type":"string","maxLength":2000}}},"required":["segments"],"description":"Segments cut from this message subject/body in display order, translated in order. 1–60 segments, each at most 2000 characters, combined at most 6000 characters; split longer messages into several requests.","x-max-total-chars":6000},"UpdateApiKeyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"scopes":{"minItems":1,"type":"array","items":{"type":"string","enum":["mail.read","mail.write","mail.send","mailbox.read","mailbox.write"]}},"rateLimit":{"type":"integer","minimum":1,"maximum":600},"allowedIps":{"maxItems":32,"type":"array","items":{"type":"string","pattern":"^(\\d{1,3}\\.){3}\\d{1,3}(\\/\\d{1,2})?$|^[0-9a-fA-F:]+(\\/\\d{1,3})?$"}},"status":{"type":"string","enum":["active","disabled"]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}}},"UpdateHostedDomainRequest":{"type":"object","properties":{"memberLimit":{"type":"integer","minimum":0,"maximum":10000}},"required":["memberLimit"]},"UpdateMailboxRequest":{"type":"object","properties":{"displayName":{"type":"string","maxLength":64}},"required":["displayName"]},"UpdateNotifyPrefsRequest":{"type":"object","properties":{"feishu":{"type":"object","properties":{"enabled":{"type":"boolean"},"webhookUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"secret":{"default":"","type":"string","maxLength":128},"contentLevel":{"default":"summary","type":"string","enum":["code_only","summary","full"]}},"required":["enabled"]},"webhook":{"type":"object","properties":{"enabled":{"type":"boolean"},"url":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"secret":{"default":"","type":"string","maxLength":128}},"required":["enabled"]},"forward":{"type":"object","properties":{"enabled":{"type":"boolean"},"addresses":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$"}}},"required":["enabled","addresses"]},"pushdeer":{"type":"object","properties":{"enabled":{"type":"boolean"},"endpoint":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^http.*"}]},"pushkey":{"default":"","type":"string","maxLength":128}},"required":["enabled"]}}},"UpdateSettingsRequest":{"type":"object","properties":{"register_mode":{"type":"string","enum":["closed","invite","open"]},"code_extract":{"type":"object","properties":{"enabled":{"type":"boolean"},"aiEnabled":{"type":"boolean"}},"required":["enabled","aiEnabled"]},"site":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":64}},"required":["title"]},"api":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]},"domains":{"type":"object","properties":{"list":{"type":"array","items":{"anyOf":[{"type":"string","minLength":1,"maxLength":253,"pattern":"^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$","description":"Normalized lowercase DNS name. Each label is 1–63 characters and cannot start/end with a hyphen."},{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$","description":"Normalized lowercase DNS name. Each label is 1–63 characters and cannot start/end with a hyphen."},"public":{"default":false,"type":"boolean"},"perUserLimit":{"default":0,"type":"integer","minimum":0,"maximum":10000},"random":{"type":"boolean","description":"Whether random suffix generation in the claim dialog (uniform and Claude zero-suspension) may pick this domain. Omitted means true; false keeps it available for manual selection only."}},"required":["domain","public","perUserLimit"],"additionalProperties":false}]},"maxItems":64,"x-unique-normalized-domain":true},"revision":{"type":"integer","minimum":0}},"required":["list"]},"expectedDomainsRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"retention":{"type":"object","properties":{"unclaimedDays":{"type":"integer","minimum":0,"maximum":3650},"allMessagesDays":{"type":"integer","minimum":0,"maximum":3650}},"required":["unclaimedDays","allMessagesDays"]},"quota":{"type":"object","properties":{"dailyOutbound":{"type":"integer","minimum":0,"maximum":100000},"dailyRecipients":{"type":"integer","minimum":0,"maximum":1000000}},"required":["dailyOutbound","dailyRecipients"]},"mailbox_policy":{"type":"object","properties":{"perUserLimit":{"type":"integer","minimum":0,"maximum":10000},"reservedLocalParts":{"maxItems":200,"type":"array","items":{"type":"string","maxLength":64}}},"required":["perUserLimit","reservedLocalParts"]},"security":{"type":"object","properties":{"require2fa":{"type":"boolean"}},"required":["require2fa"]},"ai_model":{"type":"object","properties":{"baseUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"apiKey":{"default":"","type":"string","maxLength":512,"description":"Write-only provider key. Responses return ****** when a key is stored (empty string when none). Submitting ****** keeps the stored key; an empty string clears it."},"model":{"default":"","type":"string","maxLength":128}},"description":"The single OpenAI-compatible Chat Completions model used by every AI feature: message translation and the inbound verification-code fallback. Configured means baseUrl, apiKey and model are all nonempty; baseUrl must be https and excludes /chat/completions. When translation is enabled, segments a user chooses to translate are sent to it; when code_extract.aiEnabled is on, the subject and first 6000 body characters of inbound mail that the regex could not resolve and that mentions a code-related keyword are sent to it. Unconfigured: translation is unavailable and code extraction uses regex only."},"translation":{"type":"object","properties":{"enabled":{"type":"boolean"},"dailyCharsPerUser":{"default":200000,"type":"integer","minimum":0,"maximum":10000000}},"required":["enabled"],"description":"AI translation switch and quota. Enabling requires a configured ai_model (checked against the merged result when both are submitted). dailyCharsPerUser limits characters sent per user per UTC day, administrators included; 0 is unlimited."},"claim_random":{"type":"object","properties":{"paidSuspendedLimit":{"default":2,"type":"integer","minimum":0,"maximum":1000,"deprecated":true,"description":"Compatibility only; ignored for eligibility. Any historical Claude suspension always excludes the domain."},"pendingDays":{"default":7,"type":"integer","minimum":0,"maximum":90},"suspendedPercent":{"default":50,"type":"integer","minimum":0,"maximum":100,"deprecated":true,"description":"Compatibility only; ignored for eligibility. Any historical Claude suspension always excludes the domain."},"dailyLimit":{"default":3,"type":"integer","minimum":0,"maximum":1000}},"description":"Rules for the Claude zero-suspension random suffix strategy. Any historical suspension excludes a domain. paidSuspendedLimit and suspendedPercent are deprecated compatibility fields and never change eligibility, including when zero. pendingDays counts recently claimed mailboxes without Claude mail as load (0 disables). dailyLimit caps additions in the last 24 hours (Claude accounts first seen plus new claims without Claude mail), including this plan (0 disables); full zero-suspension domains never spill over to suspended domains. domains.list[].random controls participation."},"hosted_domains":{"type":"object","properties":{"enabled":{"type":"boolean"},"maxPerUser":{"type":"integer","minimum":0,"maximum":1000},"maxPendingPerUser":{"type":"integer","minimum":1,"maximum":100},"maxPendingTotal":{"type":"integer","minimum":1,"maximum":1000},"pendingDays":{"type":"integer","minimum":1,"maximum":28},"autoClaimLimit":{"default":0,"type":"integer","minimum":0,"maximum":100000}},"required":["enabled","maxPerUser","maxPendingPerUser","maxPendingTotal","pendingDays"]}},"description":"Partial settings update. A domains replacement requires expectedDomainsRevision from the latest GET; stale revisions return 409. Adding a domain does not configure DNS or Cloudflare Email Routing. Removing a domain only removes new-claim availability, and preserves existing mailbox routing. At least one setting key is required.","dependentRequired":{"domains":["expectedDomainsRevision"]}},"UpdateUserRequest":{"type":"object","properties":{"status":{"type":"string","enum":["active","disabled"]},"role":{"type":"string","enum":["admin","user"]},"password":{"type":"string","minLength":8,"maxLength":128},"mailboxPolicy":{"anyOf":[{"type":"object","properties":{"perUserLimit":{"type":"integer","minimum":0,"maximum":10000},"domains":{"maxItems":64,"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^[a-z0-9.-]+\\.[a-z]{2,}$"},"perUserLimit":{"type":"integer","minimum":0,"maximum":10000}},"required":["domain","perUserLimit"]}}},"required":["perUserLimit","domains"]},{"type":"null"}]},"expectedMailboxPolicyRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"dependentRequired":{"mailboxPolicy":["expectedMailboxPolicyRevision"]}},"UploadAvatarRequest":{"type":"object","properties":{"contentType":{"type":"string","enum":["image/png","image/jpeg","image/webp"]},"image":{"type":"string","minLength":1,"maxLength":2796207,"pattern":"^[A-Za-z0-9+/]+={0,2}$"}},"required":["contentType","image"]},"UserSearchResults":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"username":{"type":"string"},"role":{"type":"string","enum":["admin","user"]}},"required":["id","username","role"]}},"hasMore":{"type":"boolean"}},"required":["items","hasMore"]}}},"paths":{"/openapi.json":{"get":{"summary":"Read this OpenAPI specification","description":"Read this OpenAPI specification","tags":["Mail"],"security":[],"responses":{"200":{"description":"Raw OpenAPI 3.1 document, without a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"openapi":{"type":"string"},"info":{"type":"object","properties":{"title":{"type":"string"},"version":{"type":"string"}},"required":["title","version"]},"paths":{"type":"object"}},"required":["openapi","info","paths"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__openapi_json"}},"/config":{"get":{"summary":"Read public site configuration","description":"Read public site configuration","tags":["Mail"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicConfig"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__config"}},"/avatar/{userId}":{"get":{"summary":"Download a public avatar","description":"Download a public avatar","tags":["Mail"],"security":[],"parameters":[{"name":"v","in":"query","required":false,"schema":{"type":"string"},"description":"Avatar version from avatarUrl; cache-busting value."}],"responses":{"200":{"description":"Success","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"*/*":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__avatar_userId_"},"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/auth/login":{"post":{"summary":"Sign in and create a JWT session","description":"If enabled, supply a six-digit TOTP or a recovery code in totp. A 401 error.code=totp_required means retry login with that code. The session token is different from an hpcm_ API key. New sessions are guarded against concurrent password/2FA changes.","tags":["Mail"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LoginResponse"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__auth_login"}},"/auth/register":{"post":{"summary":"Register a user and create a session","description":"Subject to closed/invite/open registration policy and IP limits. Invite mode requires inviteCode.","tags":["Mail"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LoginResponse"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__auth_register"}},"/auth/me":{"get":{"summary":"Read the current session user","description":"Read the current session user","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SessionUser"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__auth_me"}},"/auth/avatar":{"post":{"summary":"Upload a base64 avatar","description":"Upload a base64 avatar","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadAvatarRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SessionUser"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__auth_avatar"},"delete":{"summary":"Delete the current user avatar","description":"Delete the current user avatar","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SessionUser"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__auth_avatar"}},"/auth/password":{"put":{"summary":"Change password and replace the session","description":"Supply the current password. Changes password and credential epoch atomically, invalidates previous user JWTs, and returns a replacement JWT. Use the new token for subsequent calls.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePasswordRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LoginResponse"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__auth_password"}},"/auth/2fa/setup":{"post":{"summary":"Begin TOTP enrollment","description":"Returns a sensitive enrollment secret and QR-compatible otpauth URI; this does not enable TOTP until /auth/2fa/enable succeeds.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"secret":{"type":"string"},"otpauthUri":{"type":"string"}},"required":["secret","otpauthUri"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__auth_2fa_setup"}},"/auth/2fa/enable":{"post":{"summary":"Verify TOTP and enable two-factor authentication","description":"Supply the six-digit code for the current enrollment secret. Recovery codes are returned once; store securely. This route is available when totp_setup_required restricts other actions.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnableTwoFactorRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recoveryCodes":{"type":"array","items":{"type":"string"}}},"required":["recoveryCodes"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__auth_2fa_enable"}},"/auth/2fa/disable":{"post":{"summary":"Disable two-factor authentication","description":"An enrolled account must supply its current password or a valid TOTP code.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisableTwoFactorRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__auth_2fa_disable"}},"/auth/logout":{"post":{"summary":"Revoke the current session","description":"Revoke the current session","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__auth_logout"}},"/domains":{"get":{"summary":"List configured domains visible to this user","description":"Returns data as an array, unlike /v1/domains data.domains. Ordinary users see public domains or the domains allowed by their dedicated mailboxPolicy. Dedicated policies replace public visibility and quotas; explicitly granted private domains are allowed. Active hosted domains follow the system domains: those the caller owns or was granted, or every active hosted domain for administrators, who may claim addresses on any user’s hosted domain. Adding/managing system domains requires administrator settings; users host their own domains with /hosted-domains; claiming an address is a separate operation.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__domains"}},"/hosted-domains":{"get":{"summary":"List hosted domains the caller owns or was granted","description":"Users can host their own domains on this site. Each item has role owner or member; administrators also see only their own here and use /admin/hosted-domains for all.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HostedDomain"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__hosted_domains"},"post":{"summary":"Host a domain","description":"Requires /config hostedDomainsEnabled. Enter a registered root domain (not a subdomain). The site creates a Cloudflare zone and returns status pending with the two nameServers to set at the registrar; existing DNS records at the old nameservers are not migrated automatically; recreate common records (website, verification and so on) with /hosted-domains/{id}/dns-records, preferably before changing the nameservers. Disable DNSSEC at the registrar first. After the nameservers take effect, receiving (Email Routing catch-all) and sending (Email Sending) are configured automatically; poll GET /hosted-domains/{id}. Mail to any unclaimed address on an active hosted domain is claimed for the owner on arrival. Ordinary users obey hosted_domains.maxPerUser and pending limits; domains already used on this site, system domains and zones already in the site account are rejected with 409.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHostedDomainRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HostedDomain"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__hosted_domains"}},"/hosted-domains/{id}":{"get":{"summary":"Read a hosted domain and its setup progress","description":"Owner, member or administrator; otherwise 404.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HostedDomain"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__hosted_domains_id_"},"put":{"summary":"Set the per-member claim limit","description":"Owner or administrator.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHostedDomainRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HostedDomain"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__hosted_domains_id_"},"delete":{"summary":"Stop hosting and delete the domain","description":"Owner or administrator. Irreversible: the domain enters deleting, rejects mail immediately, then every message on the domain is permanently deleted, all its addresses are released and the Cloudflare zone is removed. Restore the original nameservers at the registrar first or the domain stops resolving.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__hosted_domains_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/hosted-domains/{id}/check":{"post":{"summary":"Check the nameservers and continue setup now","description":"Owner or administrator. Asks Cloudflare to re-check nameservers while pending, then advances setup. Calls within 15 seconds of the last check return the current state.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HostedDomain"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__hosted_domains_id_check"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/hosted-domains/{id}/members":{"get":{"summary":"List members of a hosted domain","description":"Owner or administrator.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HostedDomainMember"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__hosted_domains_id_members"},"put":{"summary":"Replace the members of a hosted domain","description":"Owner or administrator. Members may claim addresses on the domain (subject to memberLimit and reserved prefixes) and only see mail of addresses they claimed. userIds replaces the whole list; removed members keep addresses they already claimed. expectedOwnerId must be the current owner, otherwise 409. Find users with GET /mailboxes/share-users.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceHostedDomainMembersRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HostedDomainMember"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__hosted_domains_id_members"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/hosted-domains/{id}/members/{userId}":{"delete":{"summary":"Remove a member or leave a shared domain","description":"Owner or administrator removes any member; a member may remove themselves. Their claimed addresses are kept.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__hosted_domains_id_members_userId_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"userId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/hosted-domains/{id}/dns-records":{"get":{"summary":"List DNS records of a hosted domain","description":"Owner or administrator; members get 403, other users 404. Reads the domain’s Cloudflare zone directly and needs only the Worker’s Cloudflare credentials, not hosted_domains.enabled (403 without them). Works while pending, so records can be added before changing the nameservers, and while suspended. Deleting domains return 409, as do domains still being created. Sorted by name (@ first), type and content, including kind=mail records used for receiving and sending and kind=readonly records this site cannot edit. All four DNS endpoints share a limit of 30 requests per user per minute, administrators included. Because every hosted domain uses the site’s Cloudflare token, this feature is also limited to 150 Cloudflare calls per minute across the whole site: listing costs 1, adding, updating and deleting cost 2 each, and only requests that can reach Cloudflare count (not those over the per-user limit, or rejected for permission or domain status). Either limit returns 429 rate_limited.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HostedDnsRecord"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__hosted_domains_id_dns_records"},"post":{"summary":"Add a DNS record to a hosted domain","description":"Owner or administrator; on suspended domains only administrators may write (403). DNS only: A, AAAA and CNAME are created with proxied=false. Records that would conflict with mail are rejected with 400 before Cloudflare is called: root MX, root SPF TXT, any record at _dmarc, _domainkey, *._domainkey, cf-bounce or *.cf-bounce, and a CNAME at the root. At most 100 non-mail records per domain (403). Cloudflare rejecting the value returns 400; an existing record that cannot coexist with the same name returns 409.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostedDnsRecordInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HostedDnsRecord"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__hosted_domains_id_dns_records"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/hosted-domains/{id}/dns-records/{recordId}":{"put":{"summary":"Update a DNS record of a hosted domain","description":"Owner or administrator, same domain status rules as adding. Only kind=user records can be changed; mail and readonly records return 403 with their lockedReason. type must equal the existing record type (400; delete and re-add instead). The new name and value follow the same mail-conflict rules as adding. An unknown or malformed recordId returns 404.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostedDnsRecordInput"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HostedDnsRecord"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__hosted_domains_id_dns_records_recordId_"},"delete":{"summary":"Delete a DNS record of a hosted domain","description":"Owner or administrator, same domain status rules as adding. Only kind=user records can be deleted; mail and readonly records return 403. An unknown or malformed recordId returns 404.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__hosted_domains_id_dns_records_recordId_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"recordId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Cloudflare DNS record id: 32 lowercase hex characters."}}]},"/hosted-domains/{id}/transfer":{"post":{"summary":"Transfer a hosted domain to another user","description":"Owner or administrator. The target must be an active user; ordinary owners are limited by the target’s hosted_domains.maxPerUser. includeMailboxes moves the previous owner’s addresses on the domain with all history and revokes their mailbox shares. Members are kept. A stale expectedOwnerId returns 409; retrying a completed transfer returns transferred=false.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferHostedDomainRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HostedDomainTransferResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__hosted_domains_id_transfer"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/mailboxes":{"get":{"summary":"List caller-owned mailboxes","description":"List caller-owned mailboxes","tags":["Mail"],"parameters":[{"name":"all","in":"query","required":false,"schema":{"type":"string","enum":["1","true","0","false"]},"description":"Administrator all=1 or true includes all owners; ordinary users cannot request this range."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Mailbox"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__mailboxes"},"post":{"summary":"Claim an address on a configured domain","description":"Claim only a domain returned by /domains. Existing history at the address becomes visible to the claimant. Ordinary users obey their effective public or dedicated domain/global/per-domain quotas and system reserved-prefix restrictions. Dedicated policies do not revoke existing owned mailboxes. Does not provision a domain or Email Routing. Optional strategy=claude rejects any historical Claude suspension with 403 forbidden, including for administrators and hosted domains; checked atomically at insertion. Omitted or uniform preserves ordinary claims.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimMailboxRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Mailbox"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__mailboxes"}},"/mailboxes/shared":{"get":{"summary":"List inboxes shared with the caller","description":"Read-only inbound access; no sending, deletion or owner notifications. The read state of shared mail belongs to the owner: readers cannot change it, and it is excluded from their unread count and unread=1 list filter. Stars are personal.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SharedMailbox"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__mailboxes_shared"}},"/mailboxes/shares":{"get":{"summary":"List grants on caller-owned mailboxes","description":"List grants on caller-owned mailboxes","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxShareGrant"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__mailboxes_shares"},"put":{"summary":"Replace grants on a caller-owned mailbox","description":"Owner JWT only; cannot manage another owner through this endpoint, even as an administrator. userIds replaces the entire list; [] revokes all. At most 100 unique active users, including administrators, excluding the mailbox owner. expectedOwnerId is optional and returns 409 if ownership changed. Shares grant only existing and future non-deleted inbound mail; no send/delete/read-state/notification rights. Use administrator endpoints to manage any owner.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceMailboxSharesRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MailboxShareGrant"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__mailboxes_shares"}},"/mailboxes/shares/batch":{"post":{"summary":"Add the same grantees to several caller-owned mailboxes","description":"Owner JWT only; every mailboxId must be owned by the caller, even for administrators, otherwise 403 and nothing is written. Appends: each userId is added to every mailbox, existing grantees keep their grantedAt, and nobody is removed, so retries are idempotent. Duplicate ids are ignored. userIds must be existing active users or administrators other than the caller; each mailbox may end with at most 100 grantees. All or nothing: every error leaves all mailboxes unchanged. 400 covers the caller in userIds, missing or disabled users, and a mailbox that would exceed 100 grantees after the append. Ownership, recipient status and the limit are rechecked in the same transaction as the write; 409 means state changed after validation, for example a mailbox was transferred or released, a recipient was disabled or deleted, or concurrent writes pushed a mailbox past 100 grantees. Concurrent grants or replacements by themselves are not rejected: they are merged in order, skipping grantees already present. Returns each mailbox’s full list as of this write, in the order of the deduplicated mailboxIds; a repeated id appears once. Use PUT /mailboxes/shares to replace or shrink a list.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchShareMailboxesRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxShareGrant"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__mailboxes_shares_batch"}},"/mailboxes/shares/{mailboxId}/grantees/{userId}":{"delete":{"summary":"Revoke one grantee on a caller-owned mailbox","description":"Revoke one grantee on a caller-owned mailbox","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__mailboxes_shares_mailboxId_grantees_userId_"},"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"userId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/mailboxes/share-users":{"get":{"summary":"Search active users for mailbox sharing","description":"JWT only. Returns only id, username and role for active candidates; no account details or mailbox lists. hasMore means refine the search.","tags":["Mail"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":32},"description":"Required username substring; trimmed and case-insensitive."},{"name":"excludeUserId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Exclude the mailbox owner."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":20}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSearchResults"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__mailboxes_share_users"}},"/mailboxes/batch":{"post":{"summary":"Claim several addresses in order","description":"Same rules as POST /mailboxes, applied to each item in request order. Each item accepts optional strategy; claude rechecks current suspension facts inside the write transaction and stops with forbidden when a domain has any historical suspension. An already-claimed address is skipped into taken and the batch continues; any other error stops the batch, keeps the addresses already claimed and reports stoppedBy with the remaining items in notAttempted.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchMailboxRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BatchClaimMailboxResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__mailboxes_batch"}},"/mailboxes/availability/batch":{"post":{"summary":"Check availability of several addresses","description":"Advisory only, same rules as GET /mailboxes/availability. Results follow request order.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchMailboxRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxAvailability"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__mailboxes_availability_batch"}},"/mailboxes/random-plan":{"get":{"summary":"Allocate random suffixes for a batch claim","description":"JWT only. Read-only: allocates domains, does not claim or reserve. Candidates are the domains the caller may claim with domains.list[].random true, trimmed by per-domain and per-user remaining quota. The claude strategy excludes every domain with any historical Claude suspension from both items and pool, regardless of paid status or deprecated thresholds. It balances accounts plus recent pending claims and stops at claim_random.dailyLimit or claim quotas without spilling over to suspended domains. Generate prefixes, then pass strategy=claude on each item for availability and actual claims, including after manual suffix changes. Claims atomically recheck suspension facts; a plan does not reserve eligibility.","tags":["Mail"],"parameters":[{"name":"count","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":999},"description":"Number of addresses to allocate."},{"name":"strategy","in":"query","required":true,"schema":{"type":"string","enum":["uniform","claude"]},"description":"uniform: equal chance among eligible domains; claude: only zero-suspension domains, balanced by Claude accounts plus pending claims."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ClaimPlan"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__mailboxes_random_plan"}},"/mailboxes/availability":{"get":{"summary":"Check mailbox availability","description":"Advisory only, not a reservation. Same rules as claiming; when available=false, reason is taken, reserved, quota, domain_limit, domain_unavailable or claude_suspended. Claim still re-checks everything.","tags":["Mail"],"parameters":[{"name":"localPart","in":"query","required":true,"schema":{"type":"string"}},{"name":"domain","in":"query","required":true,"schema":{"type":"string"}},{"name":"strategy","in":"query","required":false,"schema":{"type":"string","enum":["uniform","claude"],"description":"Optional. Omitted or uniform uses ordinary claim rules. claude rejects any domain with a historical Claude suspension, including for administrators and hosted domains; writes recheck atomically and return 403 forbidden: 该域名有 Claude 封号记录，不能在 Claude 0 封号模式下认领. Historical observations do not guarantee future safety."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MailboxAvailability"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__mailboxes_availability"}},"/mailboxes/{id}":{"put":{"summary":"Set mailbox display name","description":"Mailbox owner or administrator only.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMailboxRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Mailbox"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__mailboxes_id_"},"delete":{"summary":"Release mailbox ownership","description":"Default retains all address history for the next claimant. deleteHistory=1 atomically removes all existing address mail and ownership. Owner or administrator only. Previously delivered external links retain their promised 90-day validity.","tags":["Mail"],"parameters":[{"name":"deleteHistory","in":"query","required":false,"schema":{"type":"string","enum":["1","true","0","false"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"deletedMessages":{"type":"integer","minimum":0}},"required":["success","deletedMessages"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__mailboxes_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages":{"get":{"summary":"List mail with cursor pagination","description":"unread=1 matches only caller-claimed addresses; other views still include shared inbound mail. trash=1 items include deletedAt. Inbound summaries carry verificationLink (empty when none was detected).","tags":["Mail"],"parameters":[{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"domain","in":"query","required":false,"schema":{"type":"string"}},{"name":"address","in":"query","required":false,"schema":{"type":"string"}},{"name":"unread","in":"query","required":false,"schema":{"type":"string","enum":["1","true","0","false"]}},{"name":"starred","in":"query","required":false,"schema":{"type":"string","enum":["1","true","0","false"]}},{"name":"trash","in":"query","required":false,"schema":{"type":"string","enum":["1","true","0","false"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":256},"description":"Literal substring search in subject/from/body; Unicode is supported."},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."},{"name":"afterId","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Only IDs greater than this value; 0 starts from the beginning. Never advance past unprocessed messages."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128},"description":"Opaque server nextCursor. Omit on first page; null means no next page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SessionMessagePage"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages"}},"/messages/sync":{"get":{"summary":"Poll unread count and first-page fingerprint","description":"Lightweight polling for the list view: accepts the same filters as GET /messages (cursor and afterId are ignored). Refetch the list only when head differs from the head returned with its first page.","tags":["Mail"],"parameters":[{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"domain","in":"query","required":false,"schema":{"type":"string"}},{"name":"address","in":"query","required":false,"schema":{"type":"string"}},{"name":"unread","in":"query","required":false,"schema":{"type":"string","enum":["1","true","0","false"]}},{"name":"starred","in":"query","required":false,"schema":{"type":"string","enum":["1","true","0","false"]}},{"name":"trash","in":"query","required":false,"schema":{"type":"string","enum":["1","true","0","false"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":256},"description":"Literal substring search in subject/from/body; Unicode is supported."},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."},{"name":"afterId","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Only IDs greater than this value; 0 starts from the beginning. Never advance past unprocessed messages."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128},"description":"Opaque server nextCursor. Omit on first page; null means no next page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageSync"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_sync"}},"/messages/send":{"post":{"summary":"Send, reply, resend or forward mail","description":"HTTP 201 may contain partial or total delivery failure. Inspect status/errorDetail/recipientOutcomes; retry only failed recipients. sent means provider acceptance, not confirmed destination-inbox delivery. Use base64 attachments or draft attachmentTokens; source forwarding attachments count toward the total. Large external attachments become independent 90-day signed links.","tags":["Mail"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Use one stable unique visible-ASCII key per logical send. Retry identical content with the same key after network/server failures. 409 pending/unknown means inspect the outbox and do not send with a fresh key. A partial-success response should retry only recipientOutcomes marked failed, with a new logical key. Completed keys are retained at least two days.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!-~]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMailRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageSummary"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__messages_send"}},"/messages/read":{"post":{"summary":"Mark selected owned messages read/unread","description":"Changes only mail at addresses the caller owns (or unclaimed addresses with administrator scope=unclaimed). Shared mail is silently skipped; changed counts actual matches.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed"]},"description":"Default mine; unclaimed requires administrator. Query or JSON body scope are accepted; conflicting values return 400."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkReadRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"changed":{"type":"integer","minimum":0}},"required":["changed"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__messages_read"}},"/messages/read-all":{"post":{"summary":"Mark incoming messages read, optionally narrowed by filters","description":"Range is unread, non-trash inbound mail in the caller’s own claimed mailboxes (administrator scope=unclaimed: unclaimed addresses). Shared mail is never changed: its read state belongs to the owner. domain/address/q narrow it with the list search semantics. It never applies pagination.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed"]},"description":"Default mine; unclaimed requires administrator. Query or JSON body scope are accepted; conflicting values return 400."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkAllReadRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"changed":{"type":"integer","minimum":0}},"required":["changed"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__messages_read_all"}},"/messages/delete":{"post":{"summary":"Move selected messages to trash","description":"Soft deletion. Restore before permanent deletion or the seven-day trash cleanup. Shared readers cannot delete mail.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed"]},"description":"Default mine; unclaimed requires administrator. Query or JSON body scope are accepted; conflicting values return 400."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageIdsRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"integer","minimum":0}},"required":["deleted"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__messages_delete"}},"/messages/restore":{"post":{"summary":"Restore selected trashed messages","description":"Restore selected trashed messages","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed"]},"description":"Default mine; unclaimed requires administrator. Query or JSON body scope are accepted; conflicting values return 400."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageIdsRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"restored":{"type":"integer","minimum":0},"changed":{"type":"integer","minimum":0}},"required":["restored","changed"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__messages_restore"}},"/messages/purge":{"post":{"summary":"Permanently delete selected trashed messages","description":"Irreversible metadata removal. R2 cleanup failures are retried durably. Count reflects actual permitted deletions, not the input id count.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed"]},"description":"Default mine; unclaimed requires administrator. Query or JSON body scope are accepted; conflicting values return 400."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageIdsRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"purged":{"type":"integer","minimum":0},"changed":{"type":"integer","minimum":0}},"required":["purged","changed"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__messages_purge"}},"/messages/star":{"post":{"summary":"Set per-user stars","description":"Set per-user stars","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed"]},"description":"Default mine; unclaimed requires administrator. Query or JSON body scope are accepted; conflicting values return 400."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StarMessagesRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"changed":{"type":"integer","minimum":0}},"required":["changed"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__messages_star"}},"/messages/unread-count":{"get":{"summary":"Count unread inbox messages","description":"Counts only addresses the caller claimed. Shared mail is excluded because its read state belongs to the owner. Counting stops at 1000 (1000 means at least 1000); /v1/messages/unread-count returns the exact value.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"unread":{"type":"integer","minimum":0}},"required":["unread"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_unread_count"}},"/messages/contacts":{"get":{"summary":"Read recent contact addresses","description":"Read recent contact addresses","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"string"}}},"required":["contacts"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_contacts"}},"/messages/{id}":{"get":{"summary":"Read full message detail","description":"replyTo supplies preferred reply targets; fall back to fromAddress. Attachment URLs are short-lived signed URLs. Degraded mail has errorDetail; hasRaw reports archive availability.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageDetail"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages/{id}/thread":{"get":{"summary":"Read a visible thread","description":"Bounded thread view built from Message-ID/In-Reply-To/References. Without linking headers it falls back to the same address and normalized subject within 30 days, only when one side has a Re:/Fwd:/Fw:/回复:/转发: prefix and neither side carries a verification code.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MessageSummary"}}},"required":["items"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_id_thread"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages/{id}/translate":{"post":{"summary":"Translate text segments of a visible message to Simplified Chinese","description":"JWT only; there is no /v1 equivalent. Returns 403 forbidden unless an administrator enabled translation and configured ai_model (see /config translationEnabled). Same visibility and scope/userId validation as message detail. Each segment is trimmed and whitespace-folded; only segments found in this message subject or full body (matching compares only letters and digits, ignoring HTML tags, entities, punctuation, whitespace and case) are sent to the configured external model, others are returned unchanged and counted in skipped. Segments without letters after removing URLs and email addresses (numbers, codes, punctuation) are returned unchanged and not billed. Identical segments are sent once. Results are cached per message and segment set: cached=true does not use quota. Each user has a daily character quota (settings.translation.dailyCharsPerUser, 0 unlimited; administrators included) and at most 30 model-calling requests per minute; exceeding either returns 429 rate_limited without consuming quota. A provider failure returns 500 and refunds the characters. Cached translations are deleted with the message.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateMessageRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageTranslation"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__messages_id_translate"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages/{id}/raw":{"get":{"summary":"Download the original .eml","description":"Binary response without a data envelope; 404 when the message has no original archive.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."}],"responses":{"200":{"description":"Success","content":{"message/rfc822":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_id_raw"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/attachments/{id}":{"get":{"summary":"Download an attachment by session or signed URL","description":"JWT mode enforces visibility. Signed mode requires both exp and sig and may serve retained external links after sent-mail deletion. Returns binary bytes with safe MIME/download headers.","tags":["Mail"],"security":[{"sessionToken":[]},{"attachmentSignature":[],"attachmentExpiry":[]}],"parameters":[{"name":"exp","in":"query","required":false,"schema":{"type":"integer"},"description":"Signed expiry, required together with sig for anonymous downloads."},{"name":"sig","in":"query","required":false,"schema":{"type":"string"},"description":"HMAC signature; obtain the complete URL from message detail or an external email."}],"responses":{"200":{"description":"Success","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"*/*":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__attachments_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/uploads":{"post":{"summary":"Upload a small draft attachment","description":"Raw binary upload up to 10 MiB. Pass returned token in SendMailRequest.attachmentTokens. Drafts expire after 24 hours; the combined attachment limit also applies at send time.","tags":["Mail"],"parameters":[{"name":"filename","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"No path separators or .."},{"name":"mimeType","in":"query","required":false,"schema":{"type":"string","maxLength":128,"default":"application/octet-stream"}},{"name":"Content-Length","in":"header","required":true,"schema":{"type":"integer","minimum":1,"maximum":10485760},"description":"Actual byte count of the raw binary request body."}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SingleUploadResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"operationId":"jwt_post__uploads"}},"/uploads/multipart":{"post":{"summary":"Initialize a large draft attachment","description":"Use returned token for parts/complete, and returned partBytes to split the file. Upload parts sequentially; the last part uses the remaining byte count. Maximum single file 50 MiB.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitMultipartUploadRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MultipartInitResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__uploads_multipart"}},"/uploads/multipart/{token}/parts/{partNumber}":{"put":{"summary":"Upload a numbered binary part","description":"partNumber starts at 1 and cannot exceed partCount. Content-Length must equal partBytes, except the final remainder. Save each returned etag for completion.","tags":["Mail"],"parameters":[{"name":"Content-Length","in":"header","required":true,"schema":{"type":"integer","minimum":1,"maximum":5242880},"description":"Actual byte count of the raw binary request body."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MultipartPartResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"operationId":"jwt_put__uploads_multipart_token_parts_partNumber_"},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"partNumber","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/uploads/multipart/{token}/complete":{"post":{"summary":"Complete the multipart draft","description":"Submit every partNumber/etag in parts. The server checks the actual final object size. Only completed tokens may be attached to a message.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteMultipartUploadRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MultipartCompleteResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__uploads_multipart_token_complete"},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":1}}]},"/uploads/{token}":{"delete":{"summary":"Cancel or delete a draft attachment","description":"Own draft only. Aborts unfinished multipart uploads or deletes the completed draft object. R2 failure keeps the durable reference for cleanup.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__uploads_token_"},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":1}}]},"/me/notify-prefs":{"get":{"summary":"Read masked personal notification and forwarding preferences","description":"Read masked personal notification and forwarding preferences","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotifyPrefs"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__me_notify_prefs"},"put":{"summary":"Update personal notification and forwarding preferences","description":"At least one channel. ****** preserves stored secrets; explicit empty strings clear them. Enabled channels require complete valid configuration. Webhook is HPC Mail JSON ({event:\"mail.received\",message:{id,address,fromAddress,fromName,subject,verificationCode,verificationLink,preview,createdAt}}), not a native Bark/ntfy request. Email forwarding includes rate limits; shared readers never receive owner notifications.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNotifyPrefsRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotifyPrefs"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__me_notify_prefs"}},"/me/notify-prefs/health":{"get":{"summary":"Read personal recent delivery health and forwarding quotas","description":"Current user only. pending/processing are queued; unknown means a result was not confirmed and must be checked before manual retry. Forward counts are attempts, and reset at UTC midnight. No message bodies or raw endpoint secrets are returned.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationHealth"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__me_notify_prefs_health"}},"/me/notify-prefs/jobs/{id}/retry":{"post":{"summary":"Explicitly retry a failed or unknown personal notification","description":"Owner-only failed/unknown mail notification jobs. Check actual receipt before retrying unknown results to avoid a duplicate. Forward/test records cannot use this endpoint. The selected channel must be enabled. Webhook has no automatic retry; this action is explicit.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"const":true,"type":"boolean"}},"required":["ok"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__me_notify_prefs_jobs_id_retry"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/me/notify-prefs/feishu-test":{"post":{"summary":"Send a real Feishu test with saved settings","description":"Performs an external notification and records its validated result. Failed delivery returns an error; this is not a dry run.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"const":true,"type":"boolean"}},"required":["ok"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__me_notify_prefs_feishu_test"}},"/me/notify-prefs/pushdeer-test":{"post":{"summary":"Send a real PushDeer test with saved settings","description":"Performs an external notification and validates HTTP and provider JSON success. This is not a dry run.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"const":true,"type":"boolean"}},"required":["ok"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__me_notify_prefs_pushdeer_test"}},"/api-keys":{"get":{"summary":"List own API keys without plaintext secrets","description":"List own API keys without plaintext secrets","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeySummary"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__api_keys"},"post":{"summary":"Create an API key","description":"The full key is returned only once. Scopes limit /v1 operations, never grant administrator/JWT-only permissions, and are additionally bounded by the owner role and mailbox visibility.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedApiKey"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__api_keys"}},"/api-keys/{id}":{"get":{"summary":"Read own API key metadata","description":"Read own API key metadata","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeySummary"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__api_keys_id_"},"put":{"summary":"Update own API key limits/scopes/status","description":"Update own API key limits/scopes/status","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApiKeyRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeySummary"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__api_keys_id_"},"delete":{"summary":"Revoke own API key","description":"Revoke own API key","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__api_keys_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/api-keys/{id}/logs":{"get":{"summary":"Read own API key audit logs","description":"Read own API key audit logs","tags":["Mail"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128},"description":"Opaque server nextCursor. Omit on first page; null means no next page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ApiRequestLog"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items","nextCursor"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__api_keys_id_logs"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/users":{"get":{"summary":"List users","description":"List users","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdminUser"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_users"},"post":{"summary":"Create a user","description":"Create a user","tags":["Administration"],"x-required-role":"admin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdminUser"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__admin_users"}},"/admin/users/search":{"get":{"summary":"Search active users for mailbox transfer","description":"Returns only active users with id, username and role. Exact matches are ranked first, then prefixes, then other substring matches. hasMore means refine q to narrow the results. This endpoint avoids returning all account details and mailbox lists.","tags":["Administration"],"x-required-role":"admin","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":32},"description":"Required username substring, trimmed and case-insensitive; % and _ are literal characters."},{"name":"excludeUserId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Exclude the mailbox current owner."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":20}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSearchResults"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_users_search"}},"/admin/users/{id}":{"put":{"summary":"Change user role/status/password or mailbox policy","description":"At least one field. Cannot disable self or remove the last active administrator. Password reset/disable revokes prior JWT epochs. Role changes preserve mailbox shares. mailboxPolicy=null restores public rules; a dedicated policy contains perUserLimit and domains:[{domain,perUserLimit}], with 0 meaning unlimited and an empty domain list blocking new claims. Only configured system domains may be granted, including private ones. Changing mailboxPolicy requires expectedMailboxPolicyRevision from GET /admin/users; a stale revision returns 409. Existing mailboxes retain read/send access and count toward quotas. Administrators are exempt. Role changes also increment mailboxPolicyRevision.","tags":["Administration"],"x-required-role":"admin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdminUser"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__admin_users_id_"},"delete":{"summary":"Delete a user","description":"Cannot delete self or last active administrator. Releases owned mailboxes and revokes keys/shares; message history remains address-owned and may be inherited by later claimants.","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__admin_users_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/mailboxes/{id}":{"get":{"summary":"Read any claimed mailbox","description":"Administrator JWT only. Includes ownerUsername and messageCount; 404 when the mailbox does not exist.","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Mailbox"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_mailboxes_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/mailboxes/{id}/transfer":{"post":{"summary":"Transfer any existing mailbox to an active user","description":"Administrator JWT only. userId is the target owner; expectedOwnerId comes from GET /mailboxes?all=1. Transfers an existing mailbox directly, including another user’s mailbox. For ordinary users with a dedicated mailboxPolicy, obeys configured-domain visibility, reserved-prefix restrictions and dedicated total/per-domain quotas; violations return 400/403. Users inheriting public rules and administrators retain the force-transfer exemption. Quotas and target permission/domain revisions are rechecked atomically; concurrent changes can return 409. Preserves mailbox id, address, display name and all message/attachment history. Atomically changes ownership, revokes all old shares and records mailbox.transfer audit. A stale owner returns 409, unless the mailbox already belongs to the target: that retry returns transferred=false and does not revoke new shares. Disabled/missing users cannot receive a mailbox. Future mail uses the new owner’s notification preferences; existing receipt-time snapshots/jobs remain unchanged.","tags":["Administration"],"x-required-role":"admin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferMailboxRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MailboxTransferResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__admin_mailboxes_id_transfer"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/settings":{"get":{"summary":"Read current settings and domain revision","description":"Read current settings and domain revision","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Settings"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_settings"},"put":{"summary":"Update validated settings with domain conflict protection","description":"Use expectedDomainsRevision from the latest GET when replacing domains. A stale revision returns 409. Domain changes control new claims; DNS/catch-all setup is external and existing owned mailbox routing persists. ai_model.apiKey is write-only: responses show ****** when configured and submitting ****** keeps the stored key. Enabling translation requires a configured ai_model, checked against the merged result when both are submitted; code_extract.aiEnabled may stay on without a model (regex only).","tags":["Administration"],"x-required-role":"admin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSettingsRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Settings"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__admin_settings"}},"/admin/settings/ai-model-test":{"post":{"summary":"Test the AI model with a fixed translation sample","description":"Performs one real Chat Completions call, in the translation JSON format, with the sample \"Your verification code is 123456. It expires in 10 minutes.\" Omitted or empty fields, and apiKey ******, use the saved settings.ai_model values; no feature needs to be enabled, so a model can be tested before saving it. Missing baseUrl/apiKey/model after resolution returns 400. A provider failure returns 500 with the HTTP status, timeout or invalid-response reason; the key is never echoed. Does not consume user translation quota.","tags":["Administration"],"x-required-role":"admin","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiModelTestRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AiModelTestResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__admin_settings_ai_model_test"}},"/admin/settings/domain-claude-stats":{"get":{"summary":"Per-domain Claude account statistics","description":"One item per configured domain, in list order. Judged from official Claude/Anthropic mail by MIME From and subject; senders are not DKIM-verified. Facts are kept after mail is deleted and are refreshed every 5 minutes.","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DomainClaudeStats"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_settings_domain_claude_stats"}},"/admin/settings/domain-status":{"get":{"summary":"Check public domain DNS onboarding","description":"Checks MX/SPF via public DNS. Cannot prove the private Cloudflare catch-all target or end-to-end email delivery.","tags":["Administration"],"x-required-role":"admin","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DomainStatus"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_settings_domain_status"}},"/admin/hosted-domains":{"get":{"summary":"List all hosted domains","description":"Administrators manage details, members, transfer and deletion through /hosted-domains/{id} with full rights.","tags":["Administration"],"x-required-role":"admin","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","provisioning","active","error","moved","suspended","deleting"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":253},"description":"Domain or owner username substring."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HostedDomain"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_hosted_domains"}},"/admin/hosted-domains/health":{"get":{"summary":"Check hosted domain prerequisites","description":"Whether the Worker has Cloudflare credentials, whether the token verifies, and the account zone counts. Cloudflare blocks new zones when an account has more than 50 zones and more pending than active ones.","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HostedDomainsHealth"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_hosted_domains_health"}},"/admin/hosted-domains/{id}/suspend":{"post":{"summary":"Suspend a hosted domain","description":"Rejects incoming mail, blocks sending and new claims. Addresses and history are kept.","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HostedDomain"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__admin_hosted_domains_id_suspend"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/hosted-domains/{id}/resume":{"post":{"summary":"Resume a suspended hosted domain","description":"Re-checks Cloudflare immediately and returns to the matching state.","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HostedDomain"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__admin_hosted_domains_id_resume"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/mailbox-shares":{"get":{"summary":"List grants on all claimed mailboxes","description":"List grants on all claimed mailboxes","tags":["Administration"],"x-required-role":"admin","parameters":[{"name":"mailboxId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Only this mailbox (at most one item)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MailboxShareGrant"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_mailbox_shares"},"put":{"summary":"Replace grants on any claimed mailbox","description":"Administrator JWT can share any claimed mailbox, including other users’ mailboxes, with any active user or administrator except the owner. Empty userIds revokes all shares. At most 100 grantees. expectedOwnerId optionally detects stale ownership with 409. The write also rechecks ownership and recipient status atomically. Owner metadata and grantee status are returned. Grants are read-only incoming mail; owner disable hides shares, role changes preserve them, and release/transfer/deletion revoke them.","tags":["Administration"],"x-required-role":"admin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceMailboxSharesRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MailboxShareGrant"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__admin_mailbox_shares"}},"/admin/mailbox-shares/{mailboxId}/grantees/{userId}":{"delete":{"summary":"Revoke one mailbox grantee","description":"Revoke one mailbox grantee","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__admin_mailbox_shares_mailboxId_grantees_userId_"},"parameters":[{"name":"mailboxId","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"userId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/invites":{"get":{"summary":"List invitation codes and use history","description":"List invitation codes and use history","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invite"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_invites"},"post":{"summary":"Create invitation codes","description":"Create invitation codes","tags":["Administration"],"x-required-role":"admin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInviteRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invite"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__admin_invites"}},"/admin/invites/{id}":{"delete":{"summary":"Revoke an invitation code","description":"Revoke an invitation code","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__admin_invites_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/api-keys":{"get":{"summary":"List all API key metadata with owners","description":"List all API key metadata with owners","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeySummary"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_api_keys"}},"/admin/api-keys/{id}":{"get":{"summary":"Read any API key metadata","description":"Read any API key metadata","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeySummary"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_api_keys_id_"},"delete":{"summary":"Revoke any API key","description":"Revoke any API key","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__admin_api_keys_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/api-keys/{id}/logs":{"get":{"summary":"Read any API key audit logs","description":"Read any API key audit logs","tags":["Administration"],"x-required-role":"admin","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128},"description":"Opaque server nextCursor. Omit on first page; null means no next page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ApiRequestLog"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items","nextCursor"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_api_keys_id_logs"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/audit-logs":{"get":{"summary":"Read administrator audit logs","description":"Read administrator audit logs","tags":["Administration"],"x-required-role":"admin","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128},"description":"Opaque server nextCursor. Omit on first page; null means no next page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminAuditLog"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items","nextCursor"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_audit_logs"}}}}