{"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.3.0","license":{"name":"MIT","identifier":"MIT"},"contact":{"name":"HPC Mail","url":"https://github.com/riba2534/hpc-mail"}},"servers":[{"url":"https://hpc-mail.shanicky.me/api"}],"security":[{"sessionToken":[]}],"externalDocs":{"description":"Agent usage guide and workflows","url":"https://hpc-mail.shanicky.me/skill.md"},"x-relatedApis":[{"url":"https://hpc-mail.shanicky.me/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":{"telegramWebhookSecret":{"type":"apiKey","in":"header","name":"X-Telegram-Bot-Api-Secret-Token"},"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"]},"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"}},"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"]},"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"},"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"},"unsubscribe":{"type":"object","properties":{"host":{"type":"string"},"signingDomain":{"type":"string"},"status":{"type":"string","enum":["available","processing","succeeded","failed","unknown"]}},"required":["host","signingDomain","status"]}},"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"},"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"}},"required":["id","direction","address","domain","fromAddress","fromName","subject","preview","verificationCode","status","errorDetail","isRead","isStarred","hasAttachments","size","createdAt"]},"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"]},"MutationScopeRequest":{"type":"object","properties":{"scope":{"type":"string","enum":["mine","unclaimed"]}},"required":[]},"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":["telegram","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":{"telegram":{"default":{"enabled":false,"chatId":"","contentLevel":"summary"},"type":"object","properties":{"enabled":{"type":"boolean"},"chatId":{"default":"","type":"string","maxLength":21,"pattern":"^$|^-?[1-9]\\d{0,19}$"},"contentLevel":{"default":"summary","type":"string","enum":["code_only","summary","preview"]},"allowedUserIds":{"maxItems":10,"type":"array","items":{"type":"string","pattern":"^[1-9]\\d{0,19}$"}}},"required":["enabled","chatId","contentLevel"],"additionalProperties":false},"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":["telegram","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"}},"required":["siteTitle","registrationMode","domains","require2fa"]},"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}},"required":["register_mode","code_extract","site","api","domains","retention","quota","mailbox_policy","security"]},"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"]},"UnsubscribeRequest":{"type":"object","properties":{"confirm":{"type":"boolean","const":true}},"required":["confirm"]},"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":{"telegram":{"type":"object","properties":{"enabled":{"type":"boolean"},"chatId":{"default":"","type":"string","maxLength":21,"pattern":"^$|^-?[1-9]\\d{0,19}$"},"contentLevel":{"default":"summary","type":"string","enum":["code_only","summary","preview"]},"allowedUserIds":{"maxItems":10,"type":"array","items":{"type":"string","pattern":"^[1-9]\\d{0,19}$"}}},"required":["enabled"]},"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"]}},"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"}},"/telegram/webhook":{"post":{"summary":"Receive authenticated Telegram updates","description":"Telegram Bot API only. Requires the configured X-Telegram-Bot-Api-Secret-Token header. JWT and API keys are not accepted. Update IDs are deduplicated; callbacks also require the bound chat, notification and authorized Telegram user.","tags":["Mail"],"security":[{"telegramWebhookSecret":[]}],"responses":{"200":{"description":"Update accepted or already processed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"update_id":{"type":"integer","minimum":0},"callback_query":{"type":"object"},"message":{"type":"object"}},"required":["update_id"]}}}},"operationId":"jwt_post__telegram_webhook"}},"/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. Read state is shared between mailbox readers.","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. Claim still enforces current domain visibility, ownership and quotas.","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":"List mail with cursor pagination","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 messages read/unread","description":"Mark selected messages read/unread","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 all visible incoming messages read","description":"Mark all visible incoming messages read","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/MutationScopeRequest"}}}},"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":"Count unread inbox messages","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}/unsubscribe":{"post":{"summary":"Confirm standard one-click unsubscribe","description":"Owner or administrator of unclaimed mail only. Requires explicit confirm=true and a verified DKIM signature covering RFC 8058 list headers. Shared readers cannot unsubscribe. A single HTTPS POST is sent without redirects, cookies or authorization. succeeded means provider acceptance; unknown is never automatically retried.","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/UnsubscribeRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"},"host":{"type":"string"}},"required":["status","host"]}},"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_unsubscribe"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages/{id}/thread":{"get":{"summary":"Read a visible thread","description":"Read a visible thread","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}/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, 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/telegram-test":{"post":{"summary":"Send a real Telegram test with saved settings","description":"Uses the server-side bot secret and validates Telegram JSON success. Uncertain delivery is recorded as unknown. 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_telegram_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.","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/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"}}}}