{"openapi":"3.1.0","info":{"title":"LHRST 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":"LHRST Mail","url":"https://github.com/lhrst/lhrst-mail-cf"}},"servers":[{"url":"https://mail.deepmoons.com/api"}],"security":[{"sessionToken":[]}],"externalDocs":{"description":"Agent usage guide and workflows","url":"https://mail.deepmoons.com/skill.md"},"x-relatedApis":[{"url":"https://mail.deepmoons.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","auth_unavailable","internal"]},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]}},"required":["claimed","taken","notAttempted","stoppedBy"]},"BatchMailboxRequest":{"type":"object","properties":{"items":{"minItems":1,"maxItems":20,"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,}$"}},"required":["localPart","domain"]}}},"required":["items"]},"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,}$"}},"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 and still have quota."},"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 domain in the least-suspended tier 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"]},"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 low-risk strategy stops allocating the domain once this reaches claim_random.dailyLimit."},"risk":{"anyOf":[{"type":"string","enum":["wiped","paid_suspended","suspended_rate"],"description":"wiped: every account or every paid account was suspended; paid_suspended: suspended paid accounts reached claim_random.paidSuspendedLimit; suspended_rate: at least 2 suspended accounts and the suspended share reached claim_random.suspendedPercent. All are excluded from the Claude low-risk strategy."},{"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","auth_unavailable","internal"]},"message":{"type":"string"}},"required":["code","message"]},"requestId":{"type":"string"}},"required":["error","requestId"]},"ImportMessageRequest":{"type":"object","properties":{"address":{"type":"string","maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$"},"raw":{"type":"string","minLength":1,"maxLength":27962028},"receivedAt":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"isRead":{"default":false,"type":"boolean"}},"required":["address","raw","receivedAt"]},"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"},"label":{"type":"string"},"note":{"type":"string"},"marked":{"type":"boolean"},"claudeStatus":{"type":"string"},"forwardEnabled":{"type":"boolean"},"lastForward":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["pending","processing","succeeded","failed","skipped","unknown"]},"target":{"type":"string"},"error":{"type":"string"},"at":{"type":"string","format":"date-time"}},"required":["status","target","error","at"]},{"type":"null"}]},"messageCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"}},"required":["id","address","domain","userId","displayName","label","note","marked","claudeStatus","forwardEnabled","lastForward","messageCount","createdAt"]},"MailboxAvailability":{"type":"object","properties":{"address":{"type":"string"},"available":{"type":"boolean"},"reason":{"type":"string","enum":["taken","reserved","quota","domain_limit","domain_unavailable"],"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. 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,}$"}},"annotate":{"type":"boolean"}},"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."}},"required":["siteTitle","registrationMode","domains","require2fa","translationEnabled"]},"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"]},"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},"pendingDays":{"default":7,"type":"integer","minimum":0,"maximum":90},"suspendedPercent":{"default":50,"type":"integer","minimum":0,"maximum":100},"dailyLimit":{"default":3,"type":"integer","minimum":0,"maximum":1000}},"required":["paidSuspendedLimit","pendingDays","suspendedPercent","dailyLimit"],"additionalProperties":false,"description":"Rules for the Claude low-risk random suffix strategy. Domains where every Claude account, or every paid account, was suspended are always excluded. paidSuspendedLimit also excludes domains with at least that many suspended paid accounts (0 disables this rule). suspendedPercent excludes domains with at least 2 suspended accounts whose suspended share of accounts reaches that percentage (0 disables). pendingDays counts mailboxes claimed within that many days that have not yet received Claude mail as load (0 disables). dailyLimit stops allocating a domain for the day once its new additions in the last 24 hours (Claude accounts first seen plus newly claimed mailboxes without Claude mail) reach that number; when every domain in the least-suspended tier has reached it, allocation stops instead of moving to domains with more suspensions (0 disables). Which domains take part in random generation is set per domain with domains.list[].random."}},"required":["register_mode","code_extract","site","api","domains","retention","quota","mailbox_policy","security","ai_model","translation","claim_random"]},"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"]},"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"}]}}},"UpdateMailboxRequest":{"type":"object","properties":{"displayName":{"type":"string","maxLength":64},"label":{"type":"string","maxLength":64},"note":{"type":"string","maxLength":1000},"marked":{"type":"boolean"},"claudeStatus":{"type":"string","minLength":1,"maxLength":50},"forwardEnabled":{"type":"boolean"}}},"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,}$"}},"annotate":{"type":"boolean"}},"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 low-risk) 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},"pendingDays":{"default":7,"type":"integer","minimum":0,"maximum":90},"suspendedPercent":{"default":50,"type":"integer","minimum":0,"maximum":100},"dailyLimit":{"default":3,"type":"integer","minimum":0,"maximum":1000}},"description":"Rules for the Claude low-risk random suffix strategy. Domains where every Claude account, or every paid account, was suspended are always excluded. paidSuspendedLimit also excludes domains with at least that many suspended paid accounts (0 disables this rule). suspendedPercent excludes domains with at least 2 suspended accounts whose suspended share of accounts reaches that percentage (0 disables). pendingDays counts mailboxes claimed within that many days that have not yet received Claude mail as load (0 disables). dailyLimit stops allocating a domain for the day once its new additions in the last 24 hours (Claude accounts first seen plus newly claimed mailboxes without Claude mail) reach that number; when every domain in the least-suspended tier has reached it, allocation stops instead of moving to domains with more suspensions (0 disables). Which domains take part in random generation is set per domain with domains.list[].random."}},"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. Adding/managing domains requires administrator settings; 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"}},"/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.","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/{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. 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 also excludes domains with claim_random risk (wiped, paid_suspended or suspended_rate), skips domains whose additions in the last 24 hours reached claim_random.dailyLimit (stopping rather than moving to domains with more suspensions), and reports how many Claude suspensions each allocated domain has. Generate prefixes, then check availability and claim with the batch endpoints.","tags":["Mail"],"parameters":[{"name":"count","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":20},"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: fewest Claude suspensions first, then fewest Claude accounts plus pending claims, spread evenly."}],"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 or domain_unavailable. 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"}}],"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 LHRST 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/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"}},"/admin/import/messages":{"post":{"summary":"Import one historical inbound message","description":"Runs the raw .eml through the normal inbound parsing, code extraction and storage path, then restores receivedAt and read state. Idempotent per address + Message-ID + raw bytes. Rejected with 409 while the target mailbox has forwarding enabled so history is never re-sent.","tags":["Administration"],"x-required-role":"admin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportMessageRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":1}},"required":["id"]}},"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_import_messages"}}}}