{"openapi":"3.1.0","info":{"title":"HPC Mail Open API","description":"API-key mail/mailbox automation. Bearer hpcm_ keys are distinct from JWT sessions. Keys are limited by owner, scope, expiry, IP allowlist and per-key/user/instance rates; users cannot create arbitrary domains. Management, notification preferences, sessions and 2FA use the related JWT API.","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/v1"}],"security":[{"apiKey":[]}],"externalDocs":{"description":"Agent usage guide and authentication workflows","url":"https://hpc-mail.shanicky.me/skill.md"},"x-relatedApis":[{"url":"https://hpc-mail.shanicky.me/api/openapi.json","description":"JWT session and administration API"}],"tags":[{"name":"Mail","description":"Mail and mailbox operations. Required scopes are listed in x-required-scopes."}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"hpcm_ followed by 64 hexadecimal characters"}},"schemas":{"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"]},"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"]},"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"]},"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"]},"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":[]},"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},"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"]},"UpdateMailboxRequest":{"type":"object","properties":{"displayName":{"type":"string","maxLength":64}},"required":["displayName"]}}},"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":"get__openapi_json"}},"/status":{"get":{"summary":"Check API key access","description":"Requires an active API key and enabled API. No additional scope. This confirms access, not end-to-end mail delivery.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","const":"operational"},"userId":{"type":"integer","minimum":1},"role":{"type":"string","enum":["admin","user"]},"scopes":{"type":"array","items":{"type":"string","enum":["mail.read","mail.write","mail.send","mailbox.read","mailbox.write"]}}},"required":["status","userId","role","scopes"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"get__status"}},"/domains":{"get":{"summary":"List configured domains available to this role","description":"No additional scope. Ordinary users see only public configured domains; administrators see all configured domains. Claim only a returned domain. Removed domains remain usable for existing owned mailbox identities but are absent from this new-claim list.","tags":["Mail"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"string"}}},"required":["domains"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"get__domains"}},"/mailboxes":{"get":{"summary":"List owned mailboxes","description":"List owned mailboxes","tags":["Mail"],"x-required-scopes":["mailbox.read"],"parameters":[{"name":"all","in":"query","required":false,"schema":{"type":"string","enum":["1","true","0","false"]},"description":"Administrator-only, explicit all=1 lists every owner. Default lists caller-owned mailboxes."}],"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":"get__mailboxes"},"post":{"summary":"Claim a mailbox in an existing configured domain","description":"Use a domain returned by GET /domains. Does not register a domain or provision DNS. Ordinary users obey public-domain, reserved-prefix and per-user/per-domain quotas. Claiming inherits all historical mail at this address. A concurrent domain change returns 409.","tags":["Mail"],"x-required-scopes":["mailbox.write"],"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":"post__mailboxes"}},"/mailboxes/shared":{"get":{"summary":"List inboxes shared with the caller","description":"Read-only inbound access. Shares do not grant send/delete/forward-notification rights. Read state is common to mailbox readers.","tags":["Mail"],"x-required-scopes":["mailbox.read"],"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":"get__mailboxes_shared"}},"/mailboxes/availability":{"get":{"summary":"Check address availability","description":"Availability is advisory; a subsequent claim still enforces visibility, reserved prefixes, quotas and concurrent ownership.","tags":["Mail"],"x-required-scopes":["mailbox.read"],"parameters":[{"name":"localPart","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"description":"Use a visible configured domain."}],"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":"get__mailboxes_availability"}},"/mailboxes/{id}":{"put":{"summary":"Update mailbox display name","description":"Update mailbox display name","tags":["Mail"],"x-required-scopes":["mailbox.write"],"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":"put__mailboxes_id_"},"delete":{"summary":"Release a mailbox","description":"Default retains all history and a future claimant inherits it. deleteHistory=1 atomically removes the address history and ownership. Already delivered external download links retain their promised 90-day lifetime. Owner or administrator only.","tags":["Mail"],"x-required-scopes":["mailbox.write"],"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":"delete__mailboxes_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages":{"get":{"summary":"List incoming or outgoing mail","description":"Descending cursor pagination. Use nextCursor exactly as returned; null ends the page stream. Shared inboxes only add non-trash inbound visibility. afterId supports incremental polling, but process all relevant results before advancing.","tags":["Mail"],"x-required-scopes":["mail.read"],"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":"get__messages"},"post":{"summary":"Send, reply, resend or forward mail","description":"HTTP 201 can represent partial or total recipient failure: always inspect status, errorDetail and recipientOutcomes. Retry only failed recipients; preserve BCC, body and attachments explicitly. Provider-accepted sent is not proof of recipient inbox delivery. Draft attachmentTokens come from /uploads; base64 attachments are also supported. Large external attachments become signed links valid for 90 days independently of sent-mail deletion.","tags":["Mail"],"x-required-scopes":["mail.send"],"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":"post__messages"}},"/messages/wait":{"get":{"summary":"Wait for the earliest new incoming message","description":"Returns the earliest inbound id > afterId or message:null. Default scope is caller-owned/shared inbound; administrator may explicitly select unclaimed or user with userId. Poll every two seconds internally; maximum 120 polls per user per minute. Persist the returned id only after processing that message.","tags":["Mail"],"x-required-scopes":["mail.read"],"parameters":[{"name":"address","in":"query","required":false,"schema":{"type":"string"}},{"name":"afterId","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"default":0}},{"name":"timeout","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"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":{"message":{"anyOf":[{"$ref":"#/components/schemas/MessageSummary"},{"type":"null"}]}},"required":["message"]}},"required":["data"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid credentials; login may return totp_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied or totp_setup_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, stale revision or send result not confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload exceeds limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server or notification-delivery error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"get__messages_wait"}},"/messages/read":{"post":{"summary":"Mark selected visible messages read or unread","description":"Mark selected visible messages read or unread","tags":["Mail"],"x-required-scopes":["mail.write"],"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":"post__messages_read"}},"/messages/read-all":{"post":{"summary":"Mark all visible incoming messages read","description":"Mark all visible incoming messages read","tags":["Mail"],"x-required-scopes":["mail.write"],"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":"post__messages_read_all"}},"/messages/delete":{"post":{"summary":"Move selected messages to trash","description":"Soft deletion only. Restorable until permanent deletion or automatic trash cleanup after seven days. Shared readers cannot delete mail.","tags":["Mail"],"x-required-scopes":["mail.write"],"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":"post__messages_delete"}},"/messages/restore":{"post":{"summary":"Restore selected messages from trash","description":"Restore selected messages from trash","tags":["Mail"],"x-required-scopes":["mail.write"],"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":"post__messages_restore"}},"/messages/purge":{"post":{"summary":"Permanently delete selected trashed messages","description":"Irreversible metadata deletion. Cleanup persists through R2 outages. Count reflects messages actually removed; zero does not mean every requested id existed or was permitted.","tags":["Mail"],"x-required-scopes":["mail.write"],"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":"post__messages_purge"}},"/messages/star":{"post":{"summary":"Set per-user stars on visible messages","description":"Set per-user stars on visible messages","tags":["Mail"],"x-required-scopes":["mail.write"],"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":"post__messages_star"}},"/messages/unread-count":{"get":{"summary":"Count unread inbox mail","description":"Count unread inbox mail","tags":["Mail"],"x-required-scopes":["mail.read"],"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":"get__messages_unread_count"}},"/messages/contacts":{"get":{"summary":"List recent contact addresses","description":"List recent contact addresses","tags":["Mail"],"x-required-scopes":["mail.read"],"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":"get__messages_contacts"}},"/messages/{id}":{"get":{"summary":"Read message detail, reply targets and attachments","description":"replyTo is the preferred reply recipient list; otherwise reply to fromAddress. Attachment url values are short-lived signed download URLs. hasRaw indicates an original .eml is available. Degraded inbound mail exposes errorDetail and the original archive.","tags":["Mail"],"x-required-scopes":["mail.read"],"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":"get__messages_id_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages/{id}/thread":{"get":{"summary":"Read a visible message thread","description":"Read a visible message thread","tags":["Mail"],"x-required-scopes":["mail.read"],"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":"get__messages_id_thread"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages/{id}/raw":{"get":{"summary":"Download the original message archive","description":"Returns binary .eml, without a data envelope. 404 when no raw archive exists.","tags":["Mail"],"x-required-scopes":["mail.read"],"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":"get__messages_id_raw"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}]},"/messages/{id}/attachments/{attId}":{"get":{"summary":"Download a visible message attachment","description":"Binary bytes with a safe Content-Type/Content-Disposition, without a data envelope. Attachment must belong to message id and the message must be visible.","tags":["Mail"],"x-required-scopes":["mail.read"],"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/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":"get__messages_id_attachments_attId_"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"attId","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"],"x-required-scopes":["mail.send"],"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":"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"],"x-required-scopes":["mail.send"],"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":"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"],"x-required-scopes":["mail.send"],"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":"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"],"x-required-scopes":["mail.send"],"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":"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"],"x-required-scopes":["mail.send"],"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":"delete__uploads_token_"},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":1}}]}}}