{"openapi":"3.1.0","info":{"title":"HPC Mail Session and Administration API","description":"JWT session API for all web-client functions. Authorization: Bearer <JWT> from login/register. hpcm_ API keys cannot authenticate these routes; see the related /v1 specification. Administrator endpoints require an active admin role. If site policy requires 2FA, un-enrolled sessions receive 403 totp_setup_required; /auth/me, logout and /auth/2fa routes remain available to complete setup.","version":"1.4.0","license":{"name":"MIT","identifier":"MIT"},"contact":{"name":"HPC Mail","url":"https://github.com/riba2534/hpc-mail"}},"servers":[{"url":"https://mail.iambling.com/api"}],"security":[{"sessionToken":[]}],"externalDocs":{"description":"Agent usage guide and workflows","url":"https://mail.iambling.com/skill.md"},"x-relatedApis":[{"url":"https://mail.iambling.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"}},"apiKeyCount":{"type":"integer","minimum":0},"lastLoginAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","username","role","createdAt","avatarUrl","status","mailboxCount","mailboxes","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"]},"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"]},"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}}},"DomainStatus":{"type":"object","properties":{"domain":{"type":"string"},"inList":{"type":"boolean"},"mxReady":{"type":"boolean"},"spfReady":{"type":"boolean"},"mxRecords":{"type":"array","items":{"type":"string"}},"resolved":{"type":"boolean"}},"required":["domain","inList","mxReady","spfReady","mxRecords","resolved"]},"EnableTwoFactorRequest":{"type":"object","properties":{"code":{"type":"string","pattern":"^\\d{6}$"}},"required":["code"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_failed","unauthorized","forbidden","not_found","conflict","rate_limited","bad_credentials","user_disabled","totp_required","totp_setup_required","registration_closed","invite_invalid","address_taken","payload_too_large","internal"]},"message":{"type":"string"}},"required":["code","message"]},"requestId":{"type":"string"}},"required":["error","requestId"]},"InitMultipartUploadRequest":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"mimeType":{"type":"string","minLength":3,"maxLength":128},"size":{"type":"integer","exclusiveMinimum":0,"maximum":52428800}},"required":["filename","mimeType","size"]},"Invite":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"code":{"type":"string"},"maxUses":{"type":"integer","minimum":1},"usedCount":{"type":"integer","minimum":0},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"note":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["usable","exhausted","expired","revoked"]},"usedBy":{"type":"array","items":{"type":"string"}}},"required":["id","code","maxUses","usedCount","expiresAt","note","createdAt","status","usedBy"]},"LoginRequest":{"type":"object","properties":{"username":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{2,31}$"},"password":{"type":"string","minLength":1,"maxLength":128},"totp":{"type":"string","maxLength":32}},"required":["username","password"]},"LoginResponse":{"type":"object","properties":{"token":{"type":"string","description":"Bearer JWT session token; store securely and never include it in published logs."},"user":{"$ref":"#/components/schemas/SessionUser"}},"required":["token","user"]},"Mailbox":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"address":{"type":"string"},"domain":{"type":"string"},"userId":{"type":"integer","minimum":1},"ownerUsername":{"type":"string"},"displayName":{"type":"string"},"messageCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"}},"required":["id","address","domain","userId","displayName","messageCount","createdAt"]},"MailboxAvailability":{"type":"object","properties":{"address":{"type":"string"},"available":{"type":"boolean"},"reason":{"type":"string","enum":["taken","reserved","quota","domain_limit","domain_unavailable"],"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 public to this caller. 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"},"grantees":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"integer","minimum":1},"username":{"type":"string"},"grantedAt":{"type":"string","format":"date-time"}},"required":["userId","username","grantedAt"]}}},"required":["mailboxId","address","domain","displayName","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"]},"MessagePage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MessageSummary"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items","nextCursor"]},"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"]},"MessageTranslation":{"type":"object","properties":{"translations":{"type":"array","items":{"type":"string"},"description":"One Simplified Chinese translation per request segment, same order and count. Skipped or letterless segments are returned unchanged; surrounding whitespace is preserved."},"cached":{"type":"boolean","description":"Served from the per-message cache; no quota used."},"skipped":{"type":"integer","minimum":0,"description":"Segments not found in this message content and therefore returned unchanged."}},"required":["translations","cached","skipped"]},"MultipartCompleteResult":{"type":"object","properties":{"token":{"type":"string"},"size":{"type":"integer","minimum":0}},"required":["token","size"]},"MultipartInitResult":{"type":"object","properties":{"token":{"type":"string"},"uploadId":{"type":"string"},"partBytes":{"type":"integer","minimum":1},"partCount":{"type":"integer","minimum":1}},"required":["token","uploadId","partBytes","partCount"]},"MultipartPartResult":{"type":"object","properties":{"partNumber":{"type":"integer","minimum":1},"etag":{"type":"string"}},"required":["partNumber","etag"]},"NotificationDelivery":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"messageId":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}]},"target":{"type":"string"},"status":{"type":"string","enum":["pending","processing","succeeded","failed","skipped","unknown"]},"attempts":{"type":"integer","minimum":0},"maxAttempts":{"type":"integer","minimum":1},"lastError":{"type":"string"},"lastHttpStatus":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"nextAttemptAt":{"type":"string","format":"date-time"},"lastAttemptAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","messageId","target","status","attempts","maxAttempts","lastError","lastHttpStatus","createdAt","updatedAt","nextAttemptAt","lastAttemptAt"]},"NotificationHealth":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["feishu","pushdeer","webhook","forward"]},"enabled":{"type":"boolean"},"latest":{"anyOf":[{"$ref":"#/components/schemas/NotificationDelivery"},{"type":"null"}]},"pendingCount":{"type":"integer","minimum":0},"failedCount":{"type":"integer","minimum":0}},"required":["channel","enabled","latest","pendingCount","failedCount"]}},"forward":{"type":"object","properties":{"domainLimit":{"type":"integer","minimum":0},"targetLimit":{"type":"integer","minimum":0},"windowEndsAt":{"type":"string","format":"date-time"},"targets":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"attempts":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0}},"required":["address","attempts","remaining"]}},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"attempts":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0}},"required":["domain","attempts","remaining"]}}},"required":["domainLimit","targetLimit","windowEndsAt","targets","domains"]}},"required":["channels","forward"]},"NotifyPrefs":{"type":"object","properties":{"feishu":{"type":"object","properties":{"enabled":{"type":"boolean"},"webhookUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"secret":{"default":"","type":"string","maxLength":128},"contentLevel":{"default":"summary","type":"string","enum":["code_only","summary","full"]}},"required":["enabled","webhookUrl","secret","contentLevel"],"additionalProperties":false},"webhook":{"type":"object","properties":{"enabled":{"type":"boolean"},"url":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"secret":{"default":"","type":"string","maxLength":128}},"required":["enabled","url","secret"],"additionalProperties":false},"forward":{"type":"object","properties":{"enabled":{"type":"boolean"},"addresses":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$"}}},"required":["enabled","addresses"],"additionalProperties":false},"pushdeer":{"default":{"enabled":false,"endpoint":"","pushkey":""},"type":"object","properties":{"enabled":{"type":"boolean"},"endpoint":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^http.*"}]},"pushkey":{"default":"","type":"string","maxLength":128}},"required":["enabled","endpoint","pushkey"],"additionalProperties":false}},"required":["feishu","webhook","forward","pushdeer"],"additionalProperties":false,"description":"Personal preferences. Configured feishu.secret, webhook.secret and pushdeer.pushkey are returned as ******; plaintext secrets are never returned. In updates ****** preserves the secret and an explicit empty string clears it. Enabled configurations must have valid complete endpoints/keys/forward addresses. These are mail-owner notifications; shared mailbox readers do not receive owner notifications."},"PublicConfig":{"type":"object","properties":{"siteTitle":{"type":"string"},"registrationMode":{"type":"string","enum":["closed","invite","open"]},"domains":{"type":"array","items":{"type":"string"}},"require2fa":{"type":"boolean"},"translationEnabled":{"type":"boolean","description":"translation.enabled is on and ai_model has baseUrl, apiKey and model configured; provider details are never public."}},"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}}},"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},"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}},"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."}},"required":["register_mode","code_extract","site","api","domains","retention","quota","mailbox_policy","security","ai_model","translation"]},"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}},"required":["displayName"]},"UpdateNotifyPrefsRequest":{"type":"object","properties":{"feishu":{"type":"object","properties":{"enabled":{"type":"boolean"},"webhookUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"secret":{"default":"","type":"string","maxLength":128},"contentLevel":{"default":"summary","type":"string","enum":["code_only","summary","full"]}},"required":["enabled"]},"webhook":{"type":"object","properties":{"enabled":{"type":"boolean"},"url":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^https:\\/\\/.*"}]},"secret":{"default":"","type":"string","maxLength":128}},"required":["enabled"]},"forward":{"type":"object","properties":{"enabled":{"type":"boolean"},"addresses":{"maxItems":5,"type":"array","items":{"type":"string","maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$"}}},"required":["enabled","addresses"]},"pushdeer":{"type":"object","properties":{"enabled":{"type":"boolean"},"endpoint":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","format":"uri","pattern":"^http.*"}]},"pushkey":{"default":"","type":"string","maxLength":128}},"required":["enabled"]}}},"UpdateSettingsRequest":{"type":"object","properties":{"register_mode":{"type":"string","enum":["closed","invite","open"]},"code_extract":{"type":"object","properties":{"enabled":{"type":"boolean"},"aiEnabled":{"type":"boolean"}},"required":["enabled","aiEnabled"]},"site":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":64}},"required":["title"]},"api":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]},"domains":{"type":"object","properties":{"list":{"type":"array","items":{"anyOf":[{"type":"string","minLength":1,"maxLength":253,"pattern":"^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$","description":"Normalized lowercase DNS name. Each label is 1–63 characters and cannot start/end with a hyphen."},{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":253,"pattern":"^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$","description":"Normalized lowercase DNS name. Each label is 1–63 characters and cannot start/end with a hyphen."},"public":{"default":false,"type":"boolean"},"perUserLimit":{"default":0,"type":"integer","minimum":0,"maximum":10000}},"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."}},"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}}},"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 only public domains. 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 public/reserved-prefix/global/per-domain quotas. 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/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/MessagePage"}},"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/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.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"unread":{"type":"integer","minimum":0}},"required":["unread"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_unread_count"}},"/messages/contacts":{"get":{"summary":"Read recent contact addresses","description":"Read recent contact addresses","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"string"}}},"required":["contacts"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_contacts"}},"/messages/{id}":{"get":{"summary":"Read full message detail","description":"replyTo supplies preferred reply targets; fall back to fromAddress. Attachment URLs are short-lived signed URLs. Degraded mail has errorDetail; hasRaw reports archive availability.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageDetail"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages/{id}/thread":{"get":{"summary":"Read a visible thread","description":"Bounded thread view built from Message-ID/In-Reply-To/References. Without linking headers it falls back to the same address and normalized subject within 30 days, only when one side has a Re:/Fwd:/Fw:/回复:/转发: prefix and neither side carries a verification code.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MessageSummary"}}},"required":["items"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_id_thread"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages/{id}/translate":{"post":{"summary":"Translate text segments of a visible message to Simplified Chinese","description":"JWT only; there is no /v1 equivalent. Returns 403 forbidden unless an administrator enabled translation and configured ai_model (see /config translationEnabled). Same visibility and scope/userId validation as message detail. Each segment is trimmed and whitespace-folded; only segments found in this message subject or full body (matching compares only letters and digits, ignoring HTML tags, entities, punctuation, whitespace and case) are sent to the configured external model, others are returned unchanged and counted in skipped. Segments without letters after removing URLs and email addresses (numbers, codes, punctuation) are returned unchanged and not billed. Identical segments are sent once. Results are cached per message and segment set: cached=true does not use quota. Each user has a daily character quota (settings.translation.dailyCharsPerUser, 0 unlimited; administrators included) and at most 30 model-calling requests per minute; exceeding either returns 429 rate_limited without consuming quota. A provider failure returns 500 and refunds the characters. Cached translations are deleted with the message.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateMessageRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageTranslation"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__messages_id_translate"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages/{id}/raw":{"get":{"summary":"Download the original .eml","description":"Binary response without a data envelope; 404 when the message has no original archive.","tags":["Mail"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["mine","unclaimed","user"]},"description":"Default mine. unclaimed/user are administrator-only; user requires userId. Shared inboxes add read-only inbound visibility."},{"name":"userId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Required for administrator scope=user; mutations cannot modify another owner’s mail."}],"responses":{"200":{"description":"Success","content":{"message/rfc822":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__messages_id_raw"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/attachments/{id}":{"get":{"summary":"Download an attachment by session or signed URL","description":"JWT mode enforces visibility. Signed mode requires both exp and sig and may serve retained external links after sent-mail deletion. Returns binary bytes with safe MIME/download headers.","tags":["Mail"],"security":[{"sessionToken":[]},{"attachmentSignature":[],"attachmentExpiry":[]}],"parameters":[{"name":"exp","in":"query","required":false,"schema":{"type":"integer"},"description":"Signed expiry, required together with sig for anonymous downloads."},{"name":"sig","in":"query","required":false,"schema":{"type":"string"},"description":"HMAC signature; obtain the complete URL from message detail or an external email."}],"responses":{"200":{"description":"Success","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"*/*":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__attachments_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/uploads":{"post":{"summary":"Upload a small draft attachment","description":"Raw binary upload up to 10 MiB. Pass returned token in SendMailRequest.attachmentTokens. Drafts expire after 24 hours; the combined attachment limit also applies at send time.","tags":["Mail"],"parameters":[{"name":"filename","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"No path separators or .."},{"name":"mimeType","in":"query","required":false,"schema":{"type":"string","maxLength":128,"default":"application/octet-stream"}},{"name":"Content-Length","in":"header","required":true,"schema":{"type":"integer","minimum":1,"maximum":10485760},"description":"Actual byte count of the raw binary request body."}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SingleUploadResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"operationId":"jwt_post__uploads"}},"/uploads/multipart":{"post":{"summary":"Initialize a large draft attachment","description":"Use returned token for parts/complete, and returned partBytes to split the file. Upload parts sequentially; the last part uses the remaining byte count. Maximum single file 50 MiB.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitMultipartUploadRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MultipartInitResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__uploads_multipart"}},"/uploads/multipart/{token}/parts/{partNumber}":{"put":{"summary":"Upload a numbered binary part","description":"partNumber starts at 1 and cannot exceed partCount. Content-Length must equal partBytes, except the final remainder. Save each returned etag for completion.","tags":["Mail"],"parameters":[{"name":"Content-Length","in":"header","required":true,"schema":{"type":"integer","minimum":1,"maximum":5242880},"description":"Actual byte count of the raw binary request body."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MultipartPartResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"operationId":"jwt_put__uploads_multipart_token_parts_partNumber_"},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"partNumber","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/uploads/multipart/{token}/complete":{"post":{"summary":"Complete the multipart draft","description":"Submit every partNumber/etag in parts. The server checks the actual final object size. Only completed tokens may be attached to a message.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteMultipartUploadRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MultipartCompleteResult"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__uploads_multipart_token_complete"},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":1}}]},"/uploads/{token}":{"delete":{"summary":"Cancel or delete a draft attachment","description":"Own draft only. Aborts unfinished multipart uploads or deletes the completed draft object. R2 failure keeps the durable reference for cleanup.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__uploads_token_"},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":1}}]},"/me/notify-prefs":{"get":{"summary":"Read masked personal notification and forwarding preferences","description":"Read masked personal notification and forwarding preferences","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotifyPrefs"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__me_notify_prefs"},"put":{"summary":"Update personal notification and forwarding preferences","description":"At least one channel. ****** preserves stored secrets; explicit empty strings clear them. Enabled channels require complete valid configuration. Webhook is HPC Mail JSON ({event:\"mail.received\",message:{id,address,fromAddress,fromName,subject,verificationCode,verificationLink,preview,createdAt}}), not a native Bark/ntfy request. Email forwarding includes rate limits; shared readers never receive owner notifications.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNotifyPrefsRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotifyPrefs"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__me_notify_prefs"}},"/me/notify-prefs/health":{"get":{"summary":"Read personal recent delivery health and forwarding quotas","description":"Current user only. pending/processing are queued; unknown means a result was not confirmed and must be checked before manual retry. Forward counts are attempts, and reset at UTC midnight. No message bodies or raw endpoint secrets are returned.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationHealth"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__me_notify_prefs_health"}},"/me/notify-prefs/jobs/{id}/retry":{"post":{"summary":"Explicitly retry a failed or unknown personal notification","description":"Owner-only failed/unknown mail notification jobs. Check actual receipt before retrying unknown results to avoid a duplicate. Forward/test records cannot use this endpoint. The selected channel must be enabled. Webhook has no automatic retry; this action is explicit.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"const":true,"type":"boolean"}},"required":["ok"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__me_notify_prefs_jobs_id_retry"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/me/notify-prefs/feishu-test":{"post":{"summary":"Send a real Feishu test with saved settings","description":"Performs an external notification and records its validated result. Failed delivery returns an error; this is not a dry run.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"const":true,"type":"boolean"}},"required":["ok"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__me_notify_prefs_feishu_test"}},"/me/notify-prefs/pushdeer-test":{"post":{"summary":"Send a real PushDeer test with saved settings","description":"Performs an external notification and validates HTTP and provider JSON success. This is not a dry run.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"const":true,"type":"boolean"}},"required":["ok"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__me_notify_prefs_pushdeer_test"}},"/api-keys":{"get":{"summary":"List own API keys without plaintext secrets","description":"List own API keys without plaintext secrets","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeySummary"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__api_keys"},"post":{"summary":"Create an API key","description":"The full key is returned only once. Scopes limit /v1 operations, never grant administrator/JWT-only permissions, and are additionally bounded by the owner role and mailbox visibility.","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedApiKey"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__api_keys"}},"/api-keys/{id}":{"get":{"summary":"Read own API key metadata","description":"Read own API key metadata","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeySummary"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__api_keys_id_"},"put":{"summary":"Update own API key limits/scopes/status","description":"Update own API key limits/scopes/status","tags":["Mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApiKeyRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeySummary"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_put__api_keys_id_"},"delete":{"summary":"Revoke own API key","description":"Revoke own API key","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"const":true,"type":"boolean"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_delete__api_keys_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/api-keys/{id}/logs":{"get":{"summary":"Read own API key audit logs","description":"Read own API key audit logs","tags":["Mail"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128},"description":"Opaque server nextCursor. Omit on first page; null means no next page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ApiRequestLog"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items","nextCursor"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__api_keys_id_logs"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/admin/users":{"get":{"summary":"List users","description":"List users","tags":["Administration"],"x-required-role":"admin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdminUser"}}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_users"},"post":{"summary":"Create a user","description":"Create a user","tags":["Administration"],"x-required-role":"admin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdminUser"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_post__admin_users"}},"/admin/users/search":{"get":{"summary":"Search active users for mailbox transfer","description":"Returns only active users with id, username and role. Exact matches are ranked first, then prefixes, then other substring matches. hasMore means refine q to narrow the results. This endpoint avoids returning all account details and mailbox lists.","tags":["Administration"],"x-required-role":"admin","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":32},"description":"Required username substring, trimmed and case-insensitive; % and _ are literal characters."},{"name":"excludeUserId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Exclude the mailbox current owner."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":20}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSearchResults"}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"jwt_get__admin_users_search"}},"/admin/users/{id}":{"put":{"summary":"Change user role/status or reset password","description":"At least one field. Cannot disable self or remove the last active administrator. Password reset/disable revokes prior JWT epochs. Downgrading an administrator revokes their mailbox shares.","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}/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. Bypasses ordinary claim quotas, reserved prefixes and domain visibility. 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-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 this administrator’s mailboxes","description":"List grants on this administrator’s mailboxes","tags":["Administration"],"x-required-role":"admin","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 an owned mailbox","description":"Only this administrator’s own mailboxes may be shared. Empty userIds revokes all shares. New grantees must be active ordinary users. Grants are read-only incoming mail; disable/downgrade changes remove effective access.","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"}}}}