{"components":{"schemas":{"Account":{"properties":{"activityDay":{"description":"The UTC date (YYYY-MM-DD) of the latest recorded client activity of any identity in this account, the dormancy signal; null means no recorded activity. Show it as returned, not converted to a local timezone","format":"date","type":["string","null"]},"addressCreatesPerDay":{"description":"Addresses (routes) this account may CREATE per rolling day (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"billingTier":{"description":"What the billing tool sold this account (system-written, PUT /accounts/:accountId/billing-tier). Not a limit: Pro's numbers are stamped only once the account is also vetted (`plan` = `trusted`); an unvetted Pro account keeps the `untrusted` numbers until an operator vets it","enum":["free","pro"],"type":"string"},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"deletedAt":{"description":"Soft-deletion timestamp in epoch seconds, or null if active","format":"int64","type":["integer","null"]},"domainCreatesPerDay":{"description":"Domains this account may onboard per rolling day (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"forwardMsgsPerDay":{"description":"Inbound-driven egress per rolling day — mail leaving because a route was configured, with no local sender to charge (null = platform default, 0 = unlimited). Ledger is per DOMAIN, so N domains get N x this; never spends the send allowance","format":"int64","type":["integer","null"]},"id":{"description":"Unique account ULID","type":"string"},"mailboxCreatesPerDay":{"description":"Mailboxes this account may CREATE per rolling day (null = platform default, 0 = unlimited) — a churn bound, not a ceiling; maxMailboxes is the ceiling","format":"int64","type":["integer","null"]},"mailboxSendMsgsPerDay":{"description":"The MAILBOX DEFAULT: messages each of this account's mailboxes may send per day when it has no override of its own (null = the platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"mailboxSendMsgsPerHour":{"description":"The MAILBOX DEFAULT's burst window: messages each mailbox may send per hour when it has no override of its own (null = the platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"mailboxSendRcptsPerDay":{"description":"The MAILBOX DEFAULT: recipients each mailbox may send to per day when it has no override of its own (null = the platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"mailboxSendRcptsPerHour":{"description":"The MAILBOX DEFAULT's burst window: recipients each mailbox may send to per hour when it has no override of its own (null = the platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"maxMailTemplates":{"description":"Stored mail templates this account may hold (null = the platform default, MAX_MAIL_TEMPLATES_DEFAULT; 0 = unlimited)","format":"int64","type":["integer","null"]},"maxMailboxes":{"description":"Maximum allowed mailboxes (null = the platform default, MAX_MAILBOXES_DEFAULT)","format":"int64","type":["integer","null"]},"name":{"description":"Account name","type":"string"},"noticeLanguage":{"description":"The language platform mail to a recipient with no identity here is written in (BCP 47, lowercased; null = English)","type":["string","null"]},"noticeMailboxId":{"description":"Mailbox that receives limit notices as local postmaster mail (null = console-only)","type":["string","null"]},"plan":{"description":"The service-class label last applied via POST /accounts/:accountId/plan (display/billing only — enforcement reads the limit columns; null = no plan recorded)","type":["string","null"]},"purgeAt":{"description":"Scheduled permanent purge timestamp in epoch seconds, or null","format":"int64","type":["integer","null"]},"purgedAt":{"description":"Permanent purge completion timestamp in epoch seconds, or null","format":"int64","type":["integer","null"]},"recoverySelfService":{"description":"True if mailbox users in this account may recover their own password (recovery codes, and the recovery address once it ships). False is the admin_only policy: existing addresses and codes are KEPT and refused, and resets come from an admin. Written by the tenant via PUT /accounts/:accountId/recovery-policy","type":"boolean"},"recvBytesPerDay":{"description":"Daily inbound byte allowance across the account (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"recvMsgsPerDay":{"description":"Daily inbound message allowance across the account (null = platform default, 0 = unlimited); a backstop — over it inbound is deferred, never bounced","format":"int64","type":["integer","null"]},"retentionDays":{"description":"The account DEFAULT time-based retention window in days, applied to every mailbox with no window of its own (null = none, the default). Outside the plan system","type":["integer","null"]},"semantic":{"description":"True if this account's mailboxes may enable SEMANTIC search (the plan gate for embedding). System-written only. Clearing it is refused 409 semantic_mailboxes_opted_in while any mailbox is opted in — paid with vectors does not become free; the tenant opts out (which deletes the embeddings) or the account is deleted (which wipes them). Once none is opted in, clearing stops new opt-ins and darkens the semantic read routes (409 semantic_not_enabled)","type":"boolean"},"sendHold":{"anyOf":[{"enum":["disabled","paused"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"Operator enforcement over every mailbox on every domain this account owns: 'disabled' = permanent stop, 'paused' = reversible hold, null = neither"},"sendMsgsPerDay":{"description":"Daily outbound message limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"sendMsgsPerHour":{"description":"Hourly (burst) outbound message limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"sendRcptsPerDay":{"description":"Daily outbound recipient limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"sendRcptsPerHour":{"description":"Hourly (burst) outbound recipient limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"storageLimitBytes":{"description":"Account storage limit in bytes (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"vanityHosts":{"description":"True if account is permitted to configure custom vanity hostnames","type":"boolean"},"verificationToken":{"description":"DNS TXT verification token for claiming domains","type":["string","null"]},"verifiedRecipientsOnly":{"description":"True while the account may send only to its VERIFIED RECIPIENTS (GET /accounts/:accountId/verified-recipients): addresses on its own domains, and outside addresses whose owners confirmed them; any other outside recipient is refused 403 recipient_not_verified, that recipient alone. Stamped by the vetting label (`untrusted` on, `trusted` off; system-written, POST /accounts/:accountId/plan); false for an account never vetted either way","type":"boolean"}},"required":["id","name","maxMailboxes","verificationToken","sendHold","sendMsgsPerDay","sendRcptsPerDay","sendMsgsPerHour","sendRcptsPerHour","mailboxSendMsgsPerDay","mailboxSendRcptsPerDay","mailboxSendMsgsPerHour","mailboxSendRcptsPerHour","recvMsgsPerDay","recvBytesPerDay","mailboxCreatesPerDay","addressCreatesPerDay","domainCreatesPerDay","forwardMsgsPerDay","noticeMailboxId","plan","storageLimitBytes","retentionDays","maxMailTemplates","noticeLanguage","vanityHosts","verifiedRecipientsOnly","billingTier","semantic","recoverySelfService","createdAt","deletedAt","purgeAt","purgedAt","activityDay"],"type":"object"},"AccountDeleteResult":{"properties":{"deleted":{"description":"True if the account was soft-deleted","type":"boolean"},"deletedAt":{"description":"Soft-deletion timestamp in epoch seconds","format":"int64","type":"integer"},"id":{"description":"Account ULID identifier","type":"string"},"purgeAt":{"description":"Timestamp when the account and its data will be permanently wiped in epoch seconds","format":"int64","type":"integer"},"restorable":{"description":"True if the account can still be restored before purgeAt","type":"boolean"}},"required":["id","deleted","deletedAt","purgeAt","restorable"],"type":"object"},"AccountEvents":{"properties":{"accountId":{"description":"Account ID","type":"string"},"domains":{"description":"Domain names the query was scoped to","items":{"type":"string"},"type":"array"},"domainsTruncated":{"description":"True if the account owns more domains than the query limit","type":"boolean"},"estimated":{"description":"True if numbers are estimated (false for authoritative logs)","type":"boolean"},"events":{"description":"List of authoritative traffic events across the account's domains","items":{"$ref":"#/components/schemas/AccountTrafficEvent"},"type":"array"},"nextCursor":{"description":"Pagination cursor for next page of events","type":"string"},"range":{"description":"Time range queried (e.g. '24h', '7d')","type":"string"}},"required":["accountId","range","domains","domainsTruncated","events","estimated"],"type":"object"},"AccountLimitInForce":{"properties":{"agreed":{"description":"True if this number is the account's AGREED LIMIT: an operator set it on this account with PATCH /accounts/:accountId, and no plan stamp (vet, revoke, billing-tier change) replaces it. An agreement of the platform default (value null) is an agreement too. While the account is unvetted, the stamped value is the stricter of the agreement and the unvetted number, so `value` can be lower than what was agreed","type":"boolean"},"enforcement":{"description":"Configured behavior of this threshold: enforced = exceeding it can trigger refusal; log_only = measured and logged without refusing; off = no threshold applies (`limit` is null). SEND_LIMITS_LOG_ONLY shadows the eight send/mailbox-send limits, the three creation limits and forwarding; RECV_LIMITS_LOG_ONLY shadows both receive limits; STORAGE_LIMITS_LOG_ONLY shadows the account storage pool. Only the exact flag value true enables shadow mode. maxMailboxes and maxMailTemplates remain enforced when finite. This describes limit configuration, not transient ledger health or other refusal checks","enum":["enforced","log_only","off"],"type":"string"},"limit":{"description":"The resolved threshold used by the limit's check: the account's own number, or the platform default when the account stores none. Shadow mode preserves this number; `enforcement` says whether exceeding it can trigger refusal. null = no threshold applies on this axis: the account stores 0 (explicitly unlimited), or it stores null and the platform default is blank or 0, or (mailboxCreatesPerDay, addressCreatesPerDay, domainCreatesPerDay, forwardMsgsPerDay) the deployment has that limit switched off, which makes any account number inert. `value` says which","format":"int64","type":["integer","null"]},"value":{"description":"The account's stored number, as GET /accounts/:accountId reports it: null = the account follows the platform default, 0 = explicitly unlimited (except maxMailboxes, which has no such spelling), n = the account's own number. With `limit` it tells the causes of a null limit apart: value 0 = the account is unlimited; value null = the platform sets no bound; value n with a null limit = the deployment has the limit switched off","format":"int64","type":["integer","null"]}},"required":["limit","enforcement","value","agreed"],"type":"object"},"AccountLimits":{"properties":{"accountId":{"description":"Account ULID","type":"string"},"billingTier":{"description":"What the billing tool sold this account. Not a limit: Pro's numbers are stamped only once the account is also vetted (`plan` = `trusted`)","enum":["free","pro"],"type":"string"},"limits":{"description":"Every plan limit, keyed by its field name on GET and PATCH /accounts/:accountId, which describe what each bounds. Each NULL value follows its platform default: send* the ACCOUNT_SEND_* vars; mailboxSend* (the default for a mailbox with no override of its own, which comes first) the per-mailbox SEND_* vars; recvMsgsPerDay/recvBytesPerDay ACCOUNT_RECV_*; storageLimitBytes ACCOUNT_STORAGE_LIMIT_BYTES; maxMailboxes MAX_MAILBOXES_DEFAULT (no API stores 0 for it: positive or null; a row holding 0 anyway is a ceiling of zero, reported as limit 0, enforced, not as unlimited); mailboxCreatesPerDay, addressCreatesPerDay, domainCreatesPerDay MAX_{MAILBOX,ADDRESS,DOMAIN}_CREATES_PER_DAY and forwardMsgsPerDay FORWARD_MSGS_PER_DAY, each of which is also the limit's on switch; maxMailTemplates MAX_MAIL_TEMPLATES_DEFAULT, where a blank default is the built-in 50, so its limit is null only when unlimited. forwardMsgsPerDay is counted per domain: N domains get N x this","properties":{"addressCreatesPerDay":{"$ref":"#/components/schemas/AccountLimitInForce"},"domainCreatesPerDay":{"$ref":"#/components/schemas/AccountLimitInForce"},"forwardMsgsPerDay":{"$ref":"#/components/schemas/AccountLimitInForce"},"mailboxCreatesPerDay":{"$ref":"#/components/schemas/AccountLimitInForce"},"mailboxSendMsgsPerDay":{"$ref":"#/components/schemas/AccountLimitInForce"},"mailboxSendMsgsPerHour":{"$ref":"#/components/schemas/AccountLimitInForce"},"mailboxSendRcptsPerDay":{"$ref":"#/components/schemas/AccountLimitInForce"},"mailboxSendRcptsPerHour":{"$ref":"#/components/schemas/AccountLimitInForce"},"maxMailTemplates":{"$ref":"#/components/schemas/AccountLimitInForce"},"maxMailboxes":{"$ref":"#/components/schemas/AccountLimitInForce"},"recvBytesPerDay":{"$ref":"#/components/schemas/AccountLimitInForce"},"recvMsgsPerDay":{"$ref":"#/components/schemas/AccountLimitInForce"},"sendMsgsPerDay":{"$ref":"#/components/schemas/AccountLimitInForce"},"sendMsgsPerHour":{"$ref":"#/components/schemas/AccountLimitInForce"},"sendRcptsPerDay":{"$ref":"#/components/schemas/AccountLimitInForce"},"sendRcptsPerHour":{"$ref":"#/components/schemas/AccountLimitInForce"},"storageLimitBytes":{"$ref":"#/components/schemas/AccountLimitInForce"}},"required":["sendMsgsPerDay","sendRcptsPerDay","sendMsgsPerHour","sendRcptsPerHour","mailboxSendMsgsPerDay","mailboxSendRcptsPerDay","mailboxSendMsgsPerHour","mailboxSendRcptsPerHour","recvMsgsPerDay","recvBytesPerDay","storageLimitBytes","maxMailboxes","mailboxCreatesPerDay","addressCreatesPerDay","domainCreatesPerDay","forwardMsgsPerDay","maxMailTemplates"],"type":"object"},"plan":{"description":"The account's vetting label (`untrusted`, `trusted`, or a tooling tier's name; null = no plan recorded). Display only: the limits below describe the resolved thresholds and their enforcement state","type":["string","null"]}},"required":["accountId","plan","billingTier","limits"],"type":"object"},"AccountReceiveUsage":{"properties":{"accountId":{"description":"Account ULID","type":"string"},"bytes":{"description":"Bytes stored in the window, from the staged message sizes","format":"int64","type":"integer"},"bytesPerDay":{"description":"Receive allowance in force on the bytes axis (null = unenforced)","format":"int64","type":["integer","null"]},"mailboxShare":{"description":"Fraction of each allowance one mailbox may draw alone (RECV_MAILBOX_SHARE); 1 = no per-mailbox level","type":"number"},"messages":{"description":"Messages STORED for this account's mailboxes in the rolling 24-hour window (only stored mail charges — refused, aborted and duplicate deliveries do not)","format":"int64","type":"integer"},"msgsPerDay":{"description":"Receive allowance in force on the message axis (null = unenforced)","format":"int64","type":["integer","null"]},"topMailboxes":{"description":"The window's heaviest receivers, most messages first — the list that answers 'which address is being bombed' without a per-mailbox fan-out","items":{"properties":{"bytes":{"format":"int64","type":"integer"},"mailboxId":{"type":"string"},"messages":{"format":"int64","type":"integer"}},"required":["mailboxId","messages","bytes"],"type":"object"},"type":"array"},"windowSeconds":{"description":"Duration of the window in seconds (86400)","format":"int64","type":"integer"}},"required":["accountId","messages","bytes","msgsPerDay","bytesPerDay","mailboxShare","windowSeconds","topMailboxes"],"type":"object"},"AccountRequests":{"properties":{"accountId":{"description":"Account ULID identifier","type":"string"},"estimated":{"description":"True if metrics are sampled estimates","type":"boolean"},"range":{"description":"Time range queried","type":"string"},"retentionDays":{"description":"Analytics retention window in days","type":"integer"},"series":{"description":"One point per bucket that holds a call, oldest first. A bucket with no call is absent","items":{"$ref":"#/components/schemas/RequestsSeriesPoint"},"type":"array"},"total":{"description":"Calls across the window: the series summed","format":"int64","type":"integer"}},"required":["accountId","range","estimated","retentionDays","series","total"],"type":"object"},"AccountRetention":{"properties":{"accountId":{"description":"Account ULID","type":"string"},"mailboxes":{"description":"This page of the account's mailboxes","items":{"$ref":"#/components/schemas/AccountRetentionRow"},"type":"array"},"minDays":{"description":"The platform floor","type":"integer"},"nextCursor":{"description":"Cursor for the next page, present only when one exists","type":"string"},"retentionDays":{"description":"The account default window (null = none)","type":["integer","null"]},"unreadable":{"description":"Mailbox ids on this page whose store could not be read; their rows are omitted rather than reported as zero","items":{"type":"string"},"type":"array"}},"required":["accountId","retentionDays","minDays","mailboxes","unreadable"],"type":"object"},"AccountRetentionRow":{"properties":{"effectiveDays":{"description":"The window in force for this mailbox after resolution","type":["integer","null"]},"id":{"description":"Mailbox ULID","type":"string"},"preview":{"allOf":[{"$ref":"#/components/schemas/RetentionPreview"},{"description":"What the previewed window (?days=, else the effective one) would expunge; null when there is no window to preview","type":["object","null"]}]},"primaryAddress":{"description":"Primary address, or null","type":["string","null"]},"retentionDays":{"description":"The mailbox's OWN window (null = inherits the account default, if any)","type":["integer","null"]},"source":{"description":"Where the effective window came from","enum":["own","account","none"],"type":"string"}},"required":["id","primaryAddress","retentionDays","effectiveDays","source","preview"],"type":"object"},"AccountSendUsage":{"properties":{"accountId":{"description":"Account ULID","type":"string"},"burstWindowSeconds":{"description":"Width of one burst bucket in seconds (3600); the burst figures cover two of them","format":"int64","type":"integer"},"creates":{"properties":{"addresses":{"description":"Addresses (routes) created in the rolling 24-hour window, one per new address (a re-create of the same address does not count again); 0 while addressesPerDay is null, since nothing is counted while that limit is off; null = the count could not be read right now (the rest of the answer is unaffected; read again)","format":"int64","type":["integer","null"]},"addressesPerDay":{"description":"Maximum addresses allowed to be created per day (null = unenforced: the account's number is 0, or MAX_ADDRESS_CREATES_PER_DAY is blank, which switches the limit off)","format":"int64","type":["integer","null"]},"domains":{"description":"Domain onboardings counted in the rolling 24-hour window: one per new domain name POSTed, counted before the ownership check, so an onboarding that fails verification counts and a re-POST of the same name does not; 0 while domainsPerDay is null, since nothing is counted while that limit is off; null = the count could not be read right now (the rest of the answer is unaffected; read again)","format":"int64","type":["integer","null"]},"domainsPerDay":{"description":"Maximum domains allowed to be onboarded per day (null = unenforced: the account's number is 0, or MAX_DOMAIN_CREATES_PER_DAY is blank, which switches the limit off)","format":"int64","type":["integer","null"]},"mailboxes":{"description":"Mailboxes created in the rolling 24-hour window","format":"int64","type":"integer"},"perDay":{"description":"Maximum mailboxes allowed to be created per day (null = unenforced)","format":"int64","type":["integer","null"]}},"required":["mailboxes","perDay","addresses","addressesPerDay","domains","domainsPerDay"],"type":"object"},"send":{"properties":{"messages":{"description":"Distinct messages sent in the rolling 24-hour window, plus each accepted list post whose fan-out is still being delivered: the count the daily limit is checked against","format":"int64","type":"integer"},"messagesHour":{"description":"Distinct messages in the BURST window (current + previous hourly bucket), summed across the account's ledger shards","format":"int64","type":"integer"},"msgsPerDay":{"description":"Configured daily message limit (null = unenforced)","format":"int64","type":["integer","null"]},"msgsPerHour":{"description":"Configured hourly (burst) message limit (null = unenforced)","format":"int64","type":["integer","null"]},"rcptsPerDay":{"description":"Configured daily recipient limit (null = unenforced)","format":"int64","type":["integer","null"]},"rcptsPerHour":{"description":"Configured hourly (burst) recipient limit (null = unenforced)","format":"int64","type":["integer","null"]},"recipients":{"description":"Total recipients sent to in the rolling 24-hour window, plus the recipients an accepted list post still holds for its fan-out: the count the daily limit is checked against","format":"int64","type":"integer"},"recipientsHour":{"description":"Recipients in the BURST window (current + previous hourly bucket)","format":"int64","type":"integer"}},"required":["messages","recipients","msgsPerDay","rcptsPerDay","messagesHour","recipientsHour","msgsPerHour","rcptsPerHour"],"type":"object"},"sendHold":{"anyOf":[{"enum":["disabled","paused"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"The account's own hold: 'disabled' = permanent stop, 'paused' = reversible hold, null = neither"},"windowSeconds":{"description":"Duration of the rate-limit window in seconds (e.g. 86400)","format":"int64","type":"integer"}},"required":["accountId","sendHold","send","creates","windowSeconds","burstWindowSeconds"],"type":"object"},"AccountStorageUsage":{"properties":{"accountId":{"description":"Account ULID","type":"string"},"complete":{"description":"True when `usedBytes` is a full sum computed by this request. False for an account large enough that the walk is paged across passes: this request advanced the sweep by one pass and `usedBytes` is the last completed sweep's cached figure (null if none has finished yet). Poll until true.","type":"boolean"},"computedAt":{"description":"Timestamp when usage was calculated in epoch seconds, or null when no sum has ever been computed for this account. When `complete` is false this is the cached gauge's stamp, not this request's.","format":"int64","type":["integer","null"]},"limitBytes":{"description":"Effective storage limit in bytes (null = unlimited)","format":"int64","type":["integer","null"]},"mailboxCount":{"description":"Total count of mailboxes owned by this account","format":"int64","type":"integer"},"storageLimitBytes":{"description":"Configured storage limit override in bytes (null = default, 0 = unlimited)","format":"int64","type":["integer","null"]},"usedBytes":{"description":"Total storage used across all mailboxes in bytes including trash. NULL when `complete` is false and no full sweep has ever finished for this account: the sum is deliberately withheld rather than reported short, because a partial total would under-report storage.","format":"int64","type":["integer","null"]}},"required":["accountId","usedBytes","mailboxCount","limitBytes","storageLimitBytes","computedAt","complete"],"type":"object"},"AccountTraffic":{"properties":{"accountId":{"description":"Account ID","type":"string"},"byOutcome":{"additionalProperties":{"format":"int64","type":"integer"},"description":"Breakdown of event counts by outcome","type":"object"},"domains":{"description":"List of domain names included in this aggregate","items":{"type":"string"},"type":"array"},"domainsTruncated":{"description":"True if account owns more domains than query limit","type":"boolean"},"estimated":{"description":"True if metrics are sampled estimates","type":"boolean"},"mailboxId":{"description":"Present when the aggregate was narrowed to one mailbox","type":"string"},"range":{"description":"Time range of statistics","type":"string"},"retentionDays":{"description":"Analytics retention window in days","type":"integer"},"rows":{"description":"Breakdown rows grouped by outcome and route kind","items":{"$ref":"#/components/schemas/TrafficRow"},"type":"array"},"series":{"description":"Time-series buckets for charting","items":{"$ref":"#/components/schemas/TrafficSeriesPoint"},"type":"array"},"totals":{"properties":{"bytes":{"description":"Total bytes across all account domains","format":"int64","type":"integer"},"bytesIn":{"description":"Bytes received across all account domains over the window, by daily usage's `inboundBytes` rule (see the series point)","format":"int64","type":"integer"},"bytesOut":{"description":"Bytes sent across all account domains over the window, by daily usage's `outboundBytes` rule (see the series point)","format":"int64","type":"integer"},"events":{"description":"Total events across all account domains","format":"int64","type":"integer"},"forwarded":{"description":"Inbound-driven egress events across all account domains — the forwarded SUBSET of outbound, counted inside it rather than beside it. The number a tenant is billed for separately, below submitted mail","format":"int64","type":"integer"}},"required":["events","bytes","forwarded","bytesIn","bytesOut"],"type":"object"}},"required":["accountId","range","domains","domainsTruncated","totals","byOutcome","rows","estimated","retentionDays"],"type":"object"},"AccountTrafficEvent":{"allOf":[{"$ref":"#/components/schemas/TrafficEvent"},{"properties":{"domain":{"description":"The domain this event is attributed to, or null","type":["string","null"]}},"required":["domain"],"type":"object"}]},"AccountUsage":{"properties":{"accountId":{"description":"Account ID","type":"string"},"days":{"description":"Daily usage metrics for each day in range","items":{"$ref":"#/components/schemas/UsageDay"},"type":"array"},"from":{"description":"Start date of queried usage range (YYYY-MM-DD)","type":"string"},"requests":{"description":"Summary of API calls broken down by resource and surface","items":{"$ref":"#/components/schemas/RequestBreakdownRow"},"type":"array"},"to":{"description":"End date of queried usage range (YYYY-MM-DD)","type":"string"}},"required":["accountId","from","to","days"],"type":"object"},"AddressList":{"properties":{"catchAll":{"description":"Whether this list holds a live catch-all (`*@*`) entry: the \"block all\" switch, for this list only. Read-only, present on list reads.","type":"boolean"},"contactsExempt":{"description":"Inbound block lists only: when this list's catch-all (`*@*`) decides, a vouched sender found in the receiving mailbox's own address book is let through. Applies only where a concrete receiving mailbox is known: a group, webhook or remote route behind the same block-all still needs a named allow. Every catch-all list at the most specific scope holding one must opt in. Never lifts a named block.","type":"boolean"},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"direction":{"description":"Traffic direction ('inbound' for senders, 'outbound' for recipients)","enum":["inbound","outbound"],"type":"string"},"entryCount":{"description":"Count of pattern entries in this list (on single list read)","format":"int64","type":"integer"},"id":{"description":"Address list ULID identifier","type":"string"},"name":{"description":"Descriptive name for this address list","type":"string"},"scopeId":{"description":"Associated account ID, domain name, or mailbox ID depending on scopeKind","type":"string"},"scopeKind":{"description":"Policy scope level ('account', 'domain', or 'mailbox')","enum":["account","domain","mailbox"],"type":"string"},"updatedAt":{"description":"Last updated timestamp in epoch seconds","format":"int64","type":"integer"},"verdict":{"description":"Policy action ('allow' or 'block')","enum":["allow","block"],"type":"string"}},"required":["id","scopeKind","scopeId","name","direction","verdict","contactsExempt","createdAt","updatedAt"],"type":"object"},"AddressListBatchResult":{"properties":{"added":{"description":"Count of new patterns added to the list","format":"int64","type":"integer"},"invalid":{"description":"List of invalid pattern strings that could not be added (a CSV import reports at most the first 100)","items":{"type":"string"},"type":"array"},"invalidCount":{"description":"Total invalid rows when the list above was truncated (CSV import only)","format":"int64","type":"integer"}},"required":["added","invalid"],"type":"object"},"AddressListEntry":{"properties":{"createdAt":{"description":"Timestamp when pattern was added in epoch seconds","format":"int64","type":"integer"},"expiresAt":{"description":"Epoch seconds after which the entry stops applying and disappears from the list, or null for never","format":"int64","type":["integer","null"]},"hitCount":{"description":"Evaluations this entry decided (at least: hits within ten seconds of the previous recorded one are folded into it)","format":"int64","type":"integer"},"lastHitAt":{"description":"Epoch seconds of the last recorded hit, or null if never matched","format":"int64","type":["integer","null"]},"note":{"description":"Optional operator note, or null","type":["string","null"]},"pattern":{"description":"Address pattern (e.g. user@example.com, *@example.com, or *@.example.com)","type":"string"}},"required":["pattern","note","createdAt","expiresAt","hitCount","lastHitAt"],"type":"object"},"AddressListEntryPage":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/AddressListEntry"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["entries"],"type":"object"},"AddressListPage":{"properties":{"lists":{"items":{"$ref":"#/components/schemas/AddressList"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["lists"],"type":"object"},"AddressListVerdict":{"properties":{"allowUnvouched":{"description":"Message simulation only: an allow MATCHED an identity that no SPF pass, DMARC pass or local submission vouched for, so it could not fire. The usual answer to \"I allowed them and they are still blocked\".","properties":{"identity":{"description":"The sender identity it matched, which nothing vouched for","type":"string"},"list":{"description":"The allow list whose entry matched","type":"string"},"pattern":{"description":"The entry that matched","type":"string"}},"required":["list","pattern","identity"],"type":"object"},"decidedBy":{"description":"Absent when a named entry decided. `catch_all`: no named entry at any scope matched and the list's `*@*` decided. `contact`: that catch-all's list allows contacts and the sender is in the mailbox's address book.","enum":["catch_all","contact"],"type":"string"},"listId":{"description":"ID of the address list that matched (if any)","type":"string"},"pattern":{"description":"Specific pattern entry that matched (if any)","type":"string"},"scopeKind":{"description":"Scope level of the matching list (if any)","enum":["account","domain","mailbox"],"type":"string"},"verdict":{"description":"Policy evaluation result ('allow', 'block', or 'none')","enum":["allow","block","none"],"type":"string"}},"required":["verdict"],"type":"object"},"ApiKey":{"properties":{"accountId":{"description":"Owning account ID (null for system keys)","type":["string","null"]},"accountName":{"description":"Owning account name (null for system keys)","type":["string","null"]},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"domains":{"description":"The domains this key is scoped to (migration 0078), sorted; ABSENT for a key with full account authority. A scoped key reaches only these domains' directory and the mailboxes with an address on them; everything account-level answers 403 account_credentials_required. An EMPTY list is a stored scope core cannot read (a hand-edited row): that key refuses to authenticate, and this is where the listing says so — never folded into absent, which would show a dead key as the widest one.","items":{"type":"string"},"type":"array"},"id":{"description":"Unique API key identifier","type":"string"},"idleExpiresAt":{"description":"The idle deadline computed from idleTtlS and the recorded lastUsedAt/createdAt, in epoch seconds, or null when the key never lapses. A successful renewal moves this deadline. During an account's deletion window, a key that was live at deletion can still access the restricted account recovery routes after this timestamp.","format":"int64","type":["integer","null"]},"idleTtlS":{"description":"Seconds of disuse after which this key stops authenticating (migration 0051), or null for a key that never lapses. Measured from lastUsedAt, or from createdAt while no use has been recorded. Usage updates are best-effort and coalesced with a five-minute interval; this is not an end-to-end precision guarantee, and a key can lapse before idleTtlS has passed since its final successful request.","format":"int64","type":["integer","null"]},"kind":{"description":"What this key is ('cli' for one the browser login minted), or null. Display metadata only — the caller sets it at mint, so nothing authorizes on it; it lets a keys list identify a row without matching on a name the owner can change.","type":["string","null"]},"lastUsedAt":{"description":"Approximately when this key last authenticated at core, in epoch seconds, or null if no use has been recorded. A best-effort update is attempted on first use, then coalesced with a five-minute interval. Delayed or failed writes can leave this older than the last successful request; for a key with idleTtlS, idle expiry is measured from this recorded value.","format":"int64","type":["integer","null"]},"managed":{"description":"True if this key is managed by platform infrastructure","type":"boolean"},"name":{"description":"Descriptive name for the API key","type":"string"},"requireActing":{"description":"System keys only (migration 0046): when true, mailbox-scoped requests made with this key must declare `X-Acting-Identity` or are refused `403 acting_required`. Set it on an INGRESS credential (a gateway or BFF acting for a logged-in user); never on an autonomous one (smtp-in, pop3-fetch, automation), which has no acting user.","type":"boolean"},"requireActingCredential":{"description":"System keys only (migration 0081): when true, those same requests must ALSO declare `X-Acting-Credential`, naming the mailbox credential the call acts under, or are refused `403 acting_credential_required` — so the credential's scope and recipient list survive being relayed under this key. It is also what lets `/auth/verify` hand this key a credential scoped below 'full': only a key that carries the header can honour a scope, and a session it would silently exceed must not open.","type":"boolean"},"revokedAt":{"description":"Timestamp when key was revoked in epoch seconds, or null","format":"int64","type":["integer","null"]},"role":{"description":"Key role ('system' or 'account')","type":"string"}},"required":["id","name","role","accountId","accountName","managed","createdAt","lastUsedAt","revokedAt","requireActing","requireActingCredential","kind","idleTtlS","idleExpiresAt"],"type":"object"},"ApiKeyCreated":{"properties":{"accountId":{"description":"Owning account ID (null for system keys)","type":["string","null"]},"domains":{"description":"The domains this key is scoped to, normalized (lowercased, deduplicated, sorted); ABSENT when the key was minted unscoped. A minter that asked for a scope and does not see it echoed here is talking to a core that predates the feature and must treat the key as mis-minted (revoke it) — core strips unknown request keys.","items":{"type":"string"},"type":"array"},"id":{"description":"Unique API key identifier","type":"string"},"idleExpiresAt":{"description":"When this key would lapse if never used, in epoch seconds — null when it never lapses. Present so a client can show the date without doing calendar arithmetic against its own clock, which may not be the server's.","format":"int64","type":["integer","null"]},"idleTtlS":{"description":"Seconds of disuse after which this key stops authenticating, or null for never","format":"int64","type":["integer","null"]},"kind":{"description":"Display metadata for what this key is, or null (see ApiKey.kind)","type":["string","null"]},"managed":{"description":"True if this key is managed by platform infrastructure","type":"boolean"},"name":{"description":"Descriptive name for the API key","type":"string"},"role":{"description":"Key role ('system' or 'account')","type":"string"},"token":{"description":"Plaintext API key secret token (returned once only at creation)","type":"string"}},"required":["id","name","role","accountId","managed","token","kind","idleTtlS","idleExpiresAt"],"type":"object"},"AppendResult":{"oneOf":[{"properties":{"blobHash":{"description":"On a fresh store: the blob SHA-256 (what body caches key on)","type":"string"},"duplicate":{"description":"True if message was already delivered previously","type":"boolean"},"flags":{"description":"On a fresh store: the flags the row was stored with","items":{"type":"string"},"type":"array"},"keywords":{"description":"On a fresh store: the keywords the row was stored with","items":{"type":"string"},"type":"array"},"messageId":{"description":"Assigned message ULID","type":"string"},"modseq":{"description":"On a fresh store: the membership row's MODSEQ in the target label","format":"int64","type":"integer"},"receivedAt":{"description":"On a fresh store: the INTERNALDATE in epoch seconds","format":"int64","type":"integer"},"size":{"description":"On a fresh store: the stored size in bytes","format":"int64","type":"integer"},"status":{"description":"Message was successfully delivered and stored","enum":["delivered"],"type":"string"},"threadId":{"description":"Assigned conversation thread ULID, or null on duplicate","type":["string","null"]},"uid":{"description":"Assigned message UID, or null on duplicate","format":"int64","type":["integer","null"]},"uidValidity":{"description":"Label UID validity epoch, or null on duplicate","format":"int64","type":["integer","null"]}},"required":["status","messageId","uid","uidValidity","threadId","duplicate"],"type":"object"},{"properties":{"deliveryId":{"description":"The STORED delivery key: any supplied X-Delivery-Id namespaced into the `append:` import family (so an append is never mistaken for an arrival). Correlates with the traffic log's delivery_id; retry with the ORIGINAL X-Delivery-Id, not this value.","type":"string"},"redirected":{"description":"True if message was forwarded/redirected by rule","type":"boolean"},"status":{"description":"Message was processed by a Sieve rule action","enum":["filtered"],"type":"string"}},"required":["status","deliveryId","redirected"],"type":"object"}]},"AttachmentRef":{"properties":{"contentId":{"description":"Content-ID header value for inline referencing, or null","type":["string","null"]},"contentType":{"description":"Attachment MIME content type","type":"string"},"degraded":{"description":"True if attachment was generated from fallback decoding","type":"boolean"},"filename":{"description":"Attachment filename","type":"string"},"inline":{"description":"True if attachment is meant for inline rendering","type":"boolean"},"section":{"description":"MIME part section identifier to fetch via /parts/:section","type":"string"},"size":{"description":"Decoded attachment file size in bytes","format":"int64","type":"integer"}},"required":["section","filename","contentType","size","inline","contentId"],"type":"object"},"AuditEvent":{"properties":{"accountId":{"description":"Account ID owning the touched resource, or null for system actions","type":["string","null"]},"action":{"description":"Action identifier (e.g. 'mailbox.delete', 'domain.update')","type":"string"},"actorId":{"description":"Identifier of the acting API key or credential","type":"string"},"actorName":{"description":"Resolved name of actor (API key name or mailbox address), or null","type":["string","null"]},"actorType":{"description":"Actor permission scope: 'system', 'account', 'mailbox', or 'recipient' — the anonymous holder of a forwarding disable link or of a verified-recipient confirmation link, identified by the capability spent rather than a credential (so `actorName` is always null for it)","enum":["system","account","mailbox","recipient"],"type":"string"},"createdAt":{"description":"Action timestamp in epoch seconds","format":"int64","type":"integer"},"detail":{"additionalProperties":{},"description":"Sanitized JSON object describing specific property changes, or null","type":["object","null"]},"forwardedIp":{"description":"Forwarded client IP address from proxy header, or null","type":["string","null"]},"id":{"description":"Audit event ULID (time-ordered, newest first)","type":"string"},"ip":{"description":"Direct network caller IP address, or null","type":["string","null"]},"mailboxId":{"description":"Acting mailbox ID for mailbox actors, or null","type":["string","null"]},"resourceId":{"description":"Target resource identifier (ULID or domain name)","type":"string"},"resourceType":{"description":"Type of resource modified ('account', 'domain', 'mailbox', 'route', 'api_key', 'blocklist')","type":"string"}},"required":["id","accountId","action","resourceType","resourceId","actorType","actorId","actorName","mailboxId","ip","forwardedIp","detail","createdAt"],"type":"object"},"BatchDeleteEntry":{"properties":{"blobOrphaned":{"description":"True if underlying storage blob was unreferenced and deleted","type":"boolean"},"expungedAt":{"description":"Expunge timestamp in epoch seconds (when expunged)","format":"int64","type":"integer"},"id":{"description":"Message ULID","type":"string"},"purgeAfter":{"description":"Purge deadline timestamp in epoch seconds (when expunged)","format":"int64","type":"integer"},"status":{"description":"Deletion outcome. `expunged` = moved to the Recently-deleted tier, restorable until purgeAfter; `purged` = permanently removed; `gone` = a folder-scoped grantee's delete, which detaches the message from the folders they were granted rather than expunging it — the message survives in the owner's own folders, or in Trash if it was in none.","enum":["expunged","purged","gone","not_found"],"type":"string"}},"required":["id","status"],"type":"object"},"BatchDeleteResult":{"properties":{"results":{"description":"List of deletion outcomes for each requested message","items":{"$ref":"#/components/schemas/BatchDeleteEntry"},"type":"array"}},"required":["results"],"type":"object"},"BatchLearnEntry":{"properties":{"id":{"description":"Message ULID","type":"string"},"status":{"description":"Spam/ham training submission status","enum":["accepted","not_found"],"type":"string"}},"required":["id","status"],"type":"object"},"BatchLearnResult":{"properties":{"results":{"description":"List of training submission outcomes","items":{"$ref":"#/components/schemas/BatchLearnEntry"},"type":"array"}},"required":["results"],"type":"object"},"BatchRestoreEntry":{"properties":{"id":{"description":"Message ULID","type":"string"},"message":{"allOf":[{"$ref":"#/components/schemas/MessageMeta"},{"description":"Restored message metadata (when status=restored)"}]},"status":{"description":"Restore outcome for this message","enum":["restored","not_found"],"type":"string"}},"required":["id","status"],"type":"object"},"BatchRestoreResult":{"properties":{"results":{"description":"List of restore outcomes for each requested message","items":{"$ref":"#/components/schemas/BatchRestoreEntry"},"type":"array"}},"required":["results"],"type":"object"},"BatchUnjunkEntry":{"properties":{"id":{"description":"Message ULID","type":"string"},"message":{"allOf":[{"$ref":"#/components/schemas/MessageMeta"},{"description":"Unjunked message metadata (when status=unjunked)"}]},"status":{"description":"Unjunk outcome for this message. not_junked: the message exists and is readable but does not carry the Junk label, so there is nothing to undo — deliberately distinct from not_found, which means no such live message (an EXPUNGED id is not_found here; use POST /messages/restore for that tier).","enum":["unjunked","not_junked","not_found"],"type":"string"}},"required":["id","status"],"type":"object"},"BatchUnjunkResult":{"properties":{"results":{"description":"List of unjunk outcomes for each requested message","items":{"$ref":"#/components/schemas/BatchUnjunkEntry"},"type":"array"}},"required":["results"],"type":"object"},"BatchUntrashEntry":{"properties":{"id":{"description":"Message ULID","type":"string"},"message":{"allOf":[{"$ref":"#/components/schemas/MessageMeta"},{"description":"Untrashed message metadata (when status=untrashed)"}]},"status":{"description":"Untrash outcome for this message. not_trashed: the message exists and is readable but does not carry the Trash label, so there is nothing to undo — deliberately distinct from not_found, which means no such live message (an EXPUNGED id is not_found here; use POST /messages/restore for that tier).","enum":["untrashed","not_trashed","not_found"],"type":"string"}},"required":["id","status"],"type":"object"},"BatchUntrashResult":{"properties":{"results":{"description":"List of untrash outcomes for each requested message","items":{"$ref":"#/components/schemas/BatchUntrashEntry"},"type":"array"}},"required":["results"],"type":"object"},"BatchUpdateEntry":{"properties":{"currentModseq":{"description":"Current message MODSEQ value on CAS conflict","format":"int64","type":"integer"},"expungedAt":{"description":"Expunge timestamp in epoch seconds (when status=expunged)","format":"int64","type":"integer"},"id":{"description":"Message ULID","type":"string"},"labelsAdded":{"description":"Labels attached by this write","items":{"type":"string"},"type":"array"},"labelsRemoved":{"description":"Labels detached by this write","items":{"type":"string"},"type":"array"},"message":{"allOf":[{"$ref":"#/components/schemas/MessageMeta"},{"description":"Updated message metadata (when status=updated)"}]},"modified":{"description":"True if CAS check failed due to concurrent modification","type":"boolean"},"modseq":{"description":"Updated or current MODSEQ value","format":"int64","type":"integer"},"purgeAfter":{"description":"Purge deadline timestamp in epoch seconds (when status=expunged)","format":"int64","type":"integer"},"status":{"description":"Outcome status for this message. `not_in_label`: the patch named a `flagLabel` this message is not filed in, so nothing was written for it","enum":["updated","expunged","not_found","not_in_label","too_many_keywords","modified"],"type":"string"}},"required":["id","status"],"type":"object"},"BatchUpdateResult":{"properties":{"results":{"description":"List of update outcomes for each requested message","items":{"$ref":"#/components/schemas/BatchUpdateEntry"},"type":"array"}},"required":["results"],"type":"object"},"ContactSuggestion":{"properties":{"address":{"description":"Email address to file in the To field (the card's first EMAIL)","type":"string"},"addressbookId":{"description":"Collection ULID the card lives in","type":"string"},"name":{"description":"Formatted name (vCard FN), or null when the card has none","type":["string","null"]},"ownerIdentityId":{"description":"Identity that owns the addressbook (differs from the caller's for a shared book)","type":"string"},"uid":{"description":"vCard UID; usable as ?uid= on the owning addressbook's objects listing","type":"string"}},"required":["name","address","uid","addressbookId","ownerIdentityId"],"type":"object"},"ContactSuggestions":{"properties":{"suggestions":{"description":"Deduplicated by address; the caller's own books rank ahead of shared ones","items":{"$ref":"#/components/schemas/ContactSuggestion"},"type":"array"}},"required":["suggestions"],"type":"object"},"ContentAddress":{"properties":{"email":{"description":"Email address","type":"string"},"name":{"description":"Display name or personal name, or null","type":["string","null"]}},"required":["name","email"],"type":"object"},"ContentBody":{"properties":{"charset":{"description":"Original character set encoding","type":["string","null"]},"content":{"description":"Decoded body text content (null if truncated due to large size)","type":["string","null"]},"section":{"description":"MIME section identifier","type":"string"},"size":{"description":"Full decoded body size in bytes","format":"int64","type":"integer"},"truncated":{"description":"True if body content was truncated because it exceeded inline limits","type":"boolean"}},"required":["section","content","size","truncated","charset"],"type":"object"},"ContentHeaders":{"description":"Message headers","properties":{"cc":{"description":"Parsed Cc addresses","items":{"$ref":"#/components/schemas/ContentAddress"},"type":"array"},"date":{"description":"Date header as epoch seconds (message sentAt); null if absent/unparseable","format":"int64","type":["integer","null"]},"from":{"description":"Parsed From addresses","items":{"$ref":"#/components/schemas/ContentAddress"},"type":"array"},"inReplyTo":{"description":"In-Reply-To header Message-ID, or null","type":["string","null"]},"messageIdHeader":{"description":"Message-ID header value, or null","type":["string","null"]},"replyTo":{"description":"Parsed Reply-To addresses","items":{"$ref":"#/components/schemas/ContentAddress"},"type":"array"},"subject":{"description":"Message subject line, or null","type":["string","null"]},"to":{"description":"Parsed To addresses","items":{"$ref":"#/components/schemas/ContentAddress"},"type":"array"}},"required":["from","to","cc","replyTo","subject","date","messageIdHeader","inReplyTo"],"type":"object"},"ContentResult":{"properties":{"attachments":{"description":"List of file attachments","items":{"$ref":"#/components/schemas/AttachmentRef"},"type":"array"},"headers":{"$ref":"#/components/schemas/ContentHeaders"},"html":{"anyOf":[{"$ref":"#/components/schemas/ContentBody"},{"type":"null"}],"description":"HTML body part, or null if message has no HTML"},"text":{"anyOf":[{"$ref":"#/components/schemas/ContentBody"},{"type":"null"}],"description":"Plain-text body part, or null if message has no plain text"}},"required":["headers","text","html","attachments"],"type":"object"},"CreatedIdentity":{"properties":{"accountId":{"description":"Account ID owning this mailbox, or null","type":["string","null"]},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"ephemeral":{"description":"Whether the mailbox was created DISPOSABLE (ephemeral: true at creation, immutable afterwards): its DELETE destroys it at once — no undo record, no 7-day window, the address free again immediately. False for every ordinary mailbox, whose DELETE keeps the window","type":"boolean"},"eventWebhook":{"anyOf":[{"$ref":"#/components/schemas/EventWebhook"},{"type":"null"}],"description":"Present when the create asked for an eventWebhook: the mailbox's event webhook as it now is (null if it has since been deleted)"},"groupAddress":{"description":"When this identity is a GROUP PERSONA, the group address whose archive it keeps and which it may send as; null for every other identity. A persona has no primaryAddress, cannot be a route target, refuses its own DELETE (delete the group route instead) and its Sieve/rules writes, and is exempt from max_mailboxes","type":["string","null"]},"hasMailStore":{"description":"Whether this identity has the mail capability. False for a calendar/contacts-only identity; true may also have a null primaryAddress. Derived from the directory row without reading or provisioning a store, not an indication that the store has been initialized or contains messages","type":"boolean"},"id":{"description":"Unique mailbox ULID","type":"string"},"messageWebhook":{"anyOf":[{"$ref":"#/components/schemas/MessageWebhook"},{"type":"null"}],"description":"Present when the create asked for a messageWebhook: the mailbox's message webhook as it now is (null if it has since been removed)"},"permittedRecipients":{"description":"This mailbox's outbound recipient allowlist, written by system callers only. Entries are exact addresses (`jo@acme.dev`) or domain wildcards (`*@acme.dev`). null = unrestricted (the default); [] = may send to nobody. A submission outside the list is refused with 403 recipient_not_permitted (SMTP 550). Egress only: receiving is unaffected. A credential's own permittedRecipients may restrict sending further","items":{"type":"string"},"type":["array","null"]},"primaryAddress":{"description":"Primary email address assigned to this mailbox, or null if none","type":["string","null"]},"provisioningPending":{"description":"Present, true, only while this identity's creation with messageWebhook or eventWebhook is still setting up: mail to its address and its calendar and contact writes are refused as temporary (503 temporary_failure) until it is, and the setup completes in the background. Absent for every other identity","type":"boolean"},"quotaBytes":{"description":"Storage quota in bytes, or null for unlimited","format":"int64","type":["integer","null"]},"receiveHold":{"anyOf":[{"enum":["paused","disabled"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"The account owner's hold on this mailbox's RECEIVING, independent of suspension and of sendHold: 'paused' = senders are told to retry later (429 receiving_paused, SMTP 451; they give up after about four to five days, so a pause is for short interruptions), 'disabled' = mail to it is rejected at once (403 receiving_disabled, SMTP 550), null = receiving. Set with PATCH {\"receiveHold\": \"paused\"|\"disabled\"|null}, or on create"},"receiveHoldAt":{"description":"When the current receiveHold was set (epoch seconds), restamped when the mode changes; null while receiving. The age of a pause is what decides whether it is still a pause: warn from the third day","format":"int64","type":["integer","null"]},"receiveHoldPending":{"description":"Whether the current receiveHold has not yet reached the mailbox's store: true right after a change still being applied (PATCH answered 202), false once it holds. Poll until false","type":"boolean"},"retentionDays":{"description":"The mailbox's OWN time-based retention window in days (null = none; the account default applies if one is set). The window in force, with a preview, is GET /mailboxes/:id/retention","type":["integer","null"]},"semantic":{"description":"Whether SEMANTIC (meaning-based) search is enabled for this mailbox: messages are embedded after delivery and GET /mailboxes/:id/search/semantic and …/messages/:id/similar answer. Tenant-set, gated by the account's plan; off by default. Turning it off DELETES the mailbox's embeddings","type":"boolean"},"sendHold":{"anyOf":[{"enum":["disabled","paused"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"This mailbox's own operator enforcement: 'disabled' = permanent stop (403 sending_disabled), 'paused' = reversible hold (429 sending_paused), null = neither. System-written only"},"sendMsgsPerDay":{"description":"Daily outbound message limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"sendMsgsPerHour":{"description":"Hourly (burst) outbound message limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"sendRcptsPerDay":{"description":"Daily outbound recipient limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"sendRcptsPerHour":{"description":"Hourly (burst) outbound recipient limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"suspendedAt":{"description":"When the account owner suspended this mailbox (epoch seconds), null when it is not suspended. While suspended its logins are refused as a wrong password is, its sending is held (429 sending_paused) and its open sessions end; it still receives mail, and its owner keys can still read and administer it. Set with PATCH {\"suspended\": true|false}","format":"int64","type":["integer","null"]},"suspensionPending":{"description":"Whether the current suspendedAt has not yet reached every core gate it must: true right after a change whose enforcement is still being applied (PATCH answered 202), false once it holds everywhere. Poll until false","type":"boolean"}},"required":["id","primaryAddress","hasMailStore","quotaBytes","accountId","createdAt","sendHold","permittedRecipients","suspendedAt","suspensionPending","receiveHold","receiveHoldAt","receiveHoldPending","sendMsgsPerDay","sendRcptsPerDay","sendMsgsPerHour","sendRcptsPerHour","retentionDays","groupAddress","semantic","ephemeral"],"type":"object"},"CreatedLabel":{"properties":{"color":{"description":"Hex color code for the label badge/chip, or null","type":["string","null"]},"id":{"description":"Assigned label ID","format":"int64","type":"integer"},"name":{"description":"Created label name","type":"string"},"uidValidity":{"description":"Initial UIDVALIDITY epoch for the label","format":"int64","type":"integer"}},"required":["id","name","uidValidity","color"],"type":"object"},"Credential":{"properties":{"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"expiresAt":{"description":"Expiration timestamp in epoch seconds, or null for no expiry","format":"int64","type":["integer","null"]},"id":{"description":"Unique credential ULID","type":"string"},"kind":{"description":"Credential kind ('password' for main login, 'app_password' for client token)","enum":["password","app_password"],"type":"string"},"lastUsedAt":{"description":"Timestamp when credential was last used in epoch seconds, or null","format":"int64","type":["integer","null"]},"name":{"description":"Descriptive name or label (e.g. 'Phone Mail App'), or null","type":["string","null"]},"permittedRecipients":{"description":"The credential's OWN outbound recipient allowlist (exact addresses or `*@domain`), intersected with the identity's: both must permit. null = none of its own. Only a 'send' credential carries one","items":{"type":"string"},"type":["array","null"]},"revokedAt":{"description":"Timestamp when credential was revoked in epoch seconds, or null","format":"int64","type":["integer","null"]},"scope":{"description":"The credential's scope, a ladder: 'read' (list and read mail — nothing that leaves a trace), 'write' (also mark, file, label and trash — everything the store can undo), 'send' (also submit mail), 'full' (also permanent deletion, every settings and credential route, PIM collection lifecycle and sharing — the human's own session, and the default)","enum":["read","write","send","full"],"type":"string"},"username":{"description":"Login username or email address","type":"string"}},"required":["id","kind","username","name","createdAt","lastUsedAt","revokedAt","expiresAt","scope","permittedRecipients"],"type":"object"},"CredentialCreated":{"oneOf":[{"properties":{"id":{"description":"Credential ULID","type":"string"},"kind":{"description":"Standard password","enum":["password"],"type":"string"},"name":{"description":"Optional credential label","type":["string","null"]},"username":{"description":"Username or email address","type":"string"}},"required":["id","kind","username","name"],"type":"object"},{"properties":{"expiresAt":{"description":"Expiration timestamp in epoch seconds, or null for no expiry","format":"int64","type":["integer","null"]},"id":{"description":"Credential ULID","type":"string"},"kind":{"description":"App-specific password","enum":["app_password"],"type":"string"},"name":{"description":"Optional credential label","type":["string","null"]},"permittedRecipients":{"description":"The credential's OWN outbound recipient allowlist (exact addresses or `*@domain`), intersected with the identity's: both must permit. null = none of its own. Only a 'send' credential carries one","items":{"type":"string"},"type":["array","null"]},"scope":{"description":"The credential's scope, a ladder: 'read' (list and read mail — nothing that leaves a trace), 'write' (also mark, file, label and trash — everything the store can undo), 'send' (also submit mail), 'full' (also permanent deletion, every settings and credential route, PIM collection lifecycle and sharing — the human's own session, and the default)","enum":["read","write","send","full"],"type":"string"},"token":{"description":"Plaintext app password secret (returned once only at creation)","type":"string"},"username":{"description":"Username or email address","type":"string"}},"required":["id","kind","username","name","token","expiresAt","scope","permittedRecipients"],"type":"object"}]},"DeletedMailbox":{"properties":{"accountId":{"description":"Account ID owning this mailbox, or null","type":["string","null"]},"deletedAt":{"description":"Deletion timestamp in epoch seconds","format":"int64","type":"integer"},"id":{"description":"Unique mailbox ULID","type":"string"},"primaryAddress":{"description":"Primary email address assigned to this mailbox, or null","type":["string","null"]},"quotaBytes":{"description":"Storage quota in bytes, or null","format":"int64","type":["integer","null"]},"restorable":{"description":"True if the mailbox can still be restored","type":"boolean"},"restorableUntil":{"description":"Timestamp until which restore is allowed in epoch seconds","format":"int64","type":"integer"},"wipeDueAt":{"description":"Scheduled timestamp when data will be permanently wiped in epoch seconds","format":"int64","type":"integer"},"wipeOverdue":{"description":"True if permanent wipe is overdue","type":"boolean"}},"required":["id","accountId","primaryAddress","quotaBytes","deletedAt","restorable","wipeDueAt","wipeOverdue"],"type":"object"},"DeletedResult":{"properties":{"deleted":{"description":"True if the resource was successfully deleted","type":"boolean"}},"required":["deleted"],"type":"object"},"DeliverResult":{"oneOf":[{"properties":{"duplicate":{"description":"True if message was an idempotent duplicate","type":"boolean"},"messageId":{"description":"Assigned message ULID","type":"string"},"sentCopy":{"description":"Status of saved sent copy","enum":["saved","duplicate","over_quota"],"type":"string"},"sentThreadId":{"description":"Thread ID of saved sent copy","type":["string","null"]},"status":{"description":"Message was immediately delivered to mailbox","enum":["delivered"],"type":"string"},"threadId":{"description":"Conversation thread ULID, or null","type":["string","null"]},"uid":{"description":"IMAP UID in inbox, or null","format":"int64","type":["integer","null"]},"uidValidity":{"description":"IMAP UIDVALIDITY epoch, or null","format":"int64","type":["integer","null"]}},"required":["status","messageId","uid","uidValidity","threadId","duplicate"],"type":"object"},{"properties":{"deliveryId":{"description":"Delivery identifier","type":"string"},"sentCopy":{"description":"Status of saved sent copy","enum":["saved","duplicate","over_quota"],"type":"string"},"sentThreadId":{"description":"Thread ID of saved sent copy","type":["string","null"]},"status":{"description":"Message was silently discarded or filed by Sieve rule","enum":["filtered"],"type":"string"}},"required":["status","deliveryId"],"type":"object"},{"properties":{"deliveryId":{"description":"Delivery identifier","type":"string"},"sentCopy":{"description":"Status of saved sent copy","enum":["saved","duplicate","over_quota"],"type":"string"},"sentThreadId":{"description":"Thread ID of saved sent copy","type":["string","null"]},"status":{"description":"Message was queued for background relay or delivery","enum":["queued"],"type":"string"}},"required":["status","deliveryId"],"type":"object"}]},"DmarcBlocker":{"properties":{"code":{"description":"Blocker reason code","enum":["no_reports","low_volume","short_window","sampled_policy","platform_source_failing","unaligned_source","pass_rate_below_threshold"],"type":"string"},"detail":{"description":"Human-readable explanation of the blocker","type":"string"},"messages":{"description":"Associated affected message count, if applicable","format":"int64","type":"integer"}},"required":["code","detail"],"type":"object"},"DmarcReadiness":{"description":"Policy enforcement readiness analysis","properties":{"alignedRate":{"description":"Overall DMARC pass rate fraction (0.0 to 1.0), or null","type":["number","null"]},"blockers":{"description":"List of blocking conditions preventing stricter policy","items":{"$ref":"#/components/schemas/DmarcBlocker"},"type":"array"},"currentPolicy":{"description":"Current published DMARC policy (none, quarantine, reject), or null","type":["string","null"]},"messages":{"description":"Total message count observed in window","format":"int64","type":"integer"},"observedDays":{"description":"Number of active days with observed reports","type":"integer"},"recommendedPolicy":{"description":"Recommended next policy progression, or null","enum":["quarantine","reject"],"type":["string","null"]},"reporters":{"description":"Number of distinct reporting mail receivers","type":"integer"},"sampled":{"description":"True if domain policy uses percentage sampling (pct < 100)","type":"boolean"},"verdict":{"description":"Enforcement readiness status","enum":["no_data","insufficient_data","not_ready","ready_for_quarantine","ready_for_reject","at_enforcement"],"type":"string"},"windowDays":{"description":"Aggregate reporting window in days","type":"integer"}},"required":["verdict","currentPolicy","recommendedPolicy","alignedRate","windowDays","observedDays","messages","reporters","sampled","blockers"],"type":"object"},"DmarcReport":{"properties":{"domain":{"description":"Reported domain name","type":"string"},"id":{"description":"Report ULID","type":"string"},"messages":{"description":"Total message count in this report","format":"int64","type":"integer"},"orgEmail":{"description":"Reporting organization contact email, or null","type":["string","null"]},"orgName":{"description":"Reporting organization name (e.g. 'google.com', 'yahoo.com')","type":"string"},"passing":{"description":"Passing message count in this report","format":"int64","type":"integer"},"policyDomain":{"description":"Published policy domain, or null","type":["string","null"]},"policyP":{"description":"Published domain policy (p=none, quarantine, reject)","type":["string","null"]},"policyPct":{"description":"Published policy percentage (pct=...), or null","type":["integer","null"]},"policySp":{"description":"Published subdomain policy (sp=...), or null","type":["string","null"]},"rangeBegin":{"description":"Report window start timestamp in epoch seconds","format":"int64","type":"integer"},"rangeEnd":{"description":"Report window end timestamp in epoch seconds","format":"int64","type":"integer"},"receivedAt":{"description":"Ingestion timestamp in epoch seconds","format":"int64","type":"integer"},"reportId":{"description":"Original report ID from sender XML","type":"string"},"truncated":{"description":"True if report records exceeded storage limit and were truncated","type":"boolean"}},"required":["id","domain","policyDomain","orgName","orgEmail","reportId","rangeBegin","rangeEnd","policyP","policySp","policyPct","receivedAt","messages","passing","truncated"],"type":"object"},"DmarcSource":{"properties":{"class":{"description":"Classification of source ('platform', 'aligned_third_party', or 'unaligned')","enum":["platform","aligned_third_party","unaligned"],"type":"string"},"dkimDomain":{"description":"DKIM signing domain name, or null","type":["string","null"]},"dkimPass":{"description":"Count of messages passing DKIM authentication","format":"int64","type":"integer"},"dkimSelector":{"description":"DKIM selector, or null","type":["string","null"]},"firstSeen":{"description":"First observed timestamp in epoch seconds","format":"int64","type":"integer"},"headerFrom":{"description":"From header domain, or null","type":["string","null"]},"lastSeen":{"description":"Last observed timestamp in epoch seconds","format":"int64","type":"integer"},"messages":{"description":"Total message count sent from this IP","format":"int64","type":"integer"},"passRate":{"description":"Fraction of passing messages (0.0 to 1.0), or null","type":["number","null"]},"passing":{"description":"Count of messages passing DMARC alignment","format":"int64","type":"integer"},"quarantined":{"description":"Count of messages quarantined by receiving servers","format":"int64","type":"integer"},"rejected":{"description":"Count of messages rejected by receiving servers","format":"int64","type":"integer"},"share":{"description":"Fraction of total domain mail from this IP (0.0 to 1.0)","type":"number"},"sourceIp":{"description":"Source sending IP address","type":"string"},"spfDomain":{"description":"SPF authenticated domain, or null","type":["string","null"]},"spfPass":{"description":"Count of messages passing SPF authentication","format":"int64","type":"integer"}},"required":["sourceIp","messages","passing","passRate","share","dkimPass","spfPass","quarantined","rejected","class","dkimDomain","dkimSelector","spfDomain","headerFrom","firstSeen","lastSeen"],"type":"object"},"DnsRecord":{"properties":{"accept":{"description":"Alternative accepted DNS record values","items":{"type":"string"},"type":"array"},"kind":{"description":"Record category","enum":["ownership","mx","spf","dkim","dmarc","jmap","dav"],"type":"string"},"name":{"description":"Fully-qualified DNS record host to create","type":"string"},"port":{"description":"SRV record target port (RFC 2782)","type":"integer"},"priority":{"description":"MX preference or SRV priority","type":"integer"},"purpose":{"description":"Human-readable explanation of why this DNS record is required","type":"string"},"required":{"description":"True if this record is required for normal mail delivery","type":"boolean"},"type":{"description":"DNS record type","enum":["MX","TXT","CNAME","SRV"],"type":"string"},"value":{"description":"Expected DNS record target value","type":"string"},"weight":{"description":"SRV record weight (RFC 2782)","type":"integer"}},"required":["kind","type","name","value","purpose","required"],"type":"object"},"DnsRecordCheck":{"allOf":[{"$ref":"#/components/schemas/DnsRecord"},{"properties":{"found":{"description":"Normalized values seen at `name`; empty when absent","items":{"type":"string"},"type":"array"},"ok":{"description":"Absent = liveness unknown (resolver unreachable), distinct from false","type":"boolean"},"policy":{"description":"DMARC only: the published p= value (none | quarantine | reject)","type":["string","null"]},"reportingToUs":{"description":"DMARC only: the published rua sends aggregate reports to this platform","type":"boolean"}},"required":["found"],"type":"object"}]},"DnsStatus":{"properties":{"dav":{"description":"True if CalDAV/CardDAV SRV records are configured (when DAV is enabled)","type":"boolean"},"dkim":{"description":"True if DKIM CNAME records are correctly configured","type":"boolean"},"dmarc":{"description":"True if DMARC TXT record is present","type":"boolean"},"jmap":{"description":"True if JMAP SRV record is configured (when JMAP is enabled)","type":"boolean"},"mx":{"description":"True if MX DNS records are correctly configured","type":"boolean"},"spf":{"description":"True if SPF TXT record is correctly configured","type":"boolean"}},"type":"object"},"Domain":{"properties":{"accountId":{"description":"Account ID owning this domain, or null","type":["string","null"]},"aliasOf":{"description":"Target domain if this domain is an alias, otherwise null","type":["string","null"]},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"dav":{"description":"True if CalDAV and CardDAV service discovery is enabled","type":"boolean"},"dmarc":{"description":"True if DMARC aggregate report processing is enabled","type":"boolean"},"dnsCheckedAt":{"description":"Timestamp when DNS was last checked in epoch seconds","format":"int64","type":["integer","null"]},"dnsStatus":{"anyOf":[{"$ref":"#/components/schemas/DnsStatus"},{"type":"null"}],"description":"DNS verification status for mail records"},"domain":{"description":"Fully qualified domain name","type":"string"},"enabled":{"description":"True if the domain is in service (both directions) — the owner's switch","type":"boolean"},"fbl":{"description":"True if Feedback Loop (FBL) complaint processing is enabled","type":"boolean"},"itip":{"description":"True if calendar invites received via email are automatically processed","type":"boolean"},"jmap":{"description":"True if JMAP service discovery is enabled","type":"boolean"},"mailboxCount":{"description":"Count of mailboxes on this domain (when requested with ?mailboxCounts=true)","format":"int64","type":"integer"},"pimBytes":{"description":"Sampled calendar/contacts storage in bytes (when requested with ?usage=true)","format":"int64","type":["integer","null"]},"receiveOnly":{"description":"True for the RECEIVE-ONLY mode, the mirror of sendOnly: the domain receives here and its outbound mail goes through somebody else, so the send-authentication records (bounce CNAME + both DKIM CNAMEs) leave the DNS checklist AND the verdict and sending is never activated. The owner's choice, not an enforcement state; mutually exclusive with sendOnly","type":"boolean"},"receiving":{"description":"This domain receives here (enabled && !sendOnly)","type":"boolean"},"sendHold":{"anyOf":[{"enum":["disabled","paused"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"This domain's own operator enforcement: 'disabled' = permanent stop (403 sending_disabled), 'paused' = reversible hold (429 sending_paused), null = neither. System-written only; the account's hold is reported on the Account"},"sendOnly":{"description":"True for the SEND-ONLY mode: the tenant sends as the domain while its inbound MX stays at another provider, so nothing on it is a local recipient — the owner's choice of where their mail lives, not an enforcement state","type":"boolean"},"sendVerified":{"description":"True once the send records (bounce CNAME + both DKIM CNAMEs) were proven live by POST /domains — the EARNED half of sendability; false means 'publish DNS', never 'stopped'. Always false for a receiveOnly domain, which is never offered those records","type":"boolean"},"sending":{"description":"This domain may send by its own switches (enabled && sendVerified && sendHold === null). The account's hold is not folded in — read it from the Account; /auth/verify reports the effective fold for a login","type":"boolean"},"srs":{"description":"True if the SRS0=/SRS1= local-part namespace at this domain is the platform's forwarding bounce-return path (system-managed)","type":"boolean"},"subaddressing":{"description":"Whether `+` is a tag delimiter on this domain (default true): mail to `alice+anything@` reaches `alice@`, and `alice+*@` is a permitted sender family. False makes `+` an ordinary character — no stripping, no tag recorded, no `+*` family advertised","type":"boolean"},"unicodeName":{"description":"The Unicode presentation of the domain (D4): `domainToUnicode` of the stored A-label, equal to `domain` when it is pure ASCII. A display form only - never an identifier; DNS instructions and all routing use `domain`","type":"string"},"usageAt":{"description":"Timestamp when usage was sampled in epoch seconds","format":"int64","type":"integer"},"usageStale":{"description":"True if sampled usage figures could not be refreshed recently","type":"boolean"},"usedBytes":{"description":"Sampled mail storage in bytes (when requested with ?usage=true)","format":"int64","type":"integer"}},"required":["domain","enabled","sendOnly","receiveOnly","sendVerified","sendHold","aliasOf","unicodeName","fbl","dmarc","jmap","dav","itip","subaddressing","srs","dnsStatus","dnsCheckedAt","accountId","createdAt","receiving","sending"],"type":"object"},"DomainBranding":{"properties":{"brandName":{"description":"Display name shown with the logo; null = default","type":["string","null"]},"domain":{"description":"Domain name","type":"string"},"hasLogo":{"description":"True if a custom logo image has been uploaded","type":"boolean"},"logoType":{"description":"Media MIME type of the stored logo, or null","type":["string","null"]},"logoUpdatedAt":{"description":"Epoch seconds of the last logo write; also acts as cache version","format":"int64","type":["integer","null"]}},"required":["domain","brandName","hasLogo","logoType","logoUpdatedAt"],"type":"object"},"DomainBrandingPatch":{"properties":{"brandName":{"description":"Display name (1–64 characters), or null to clear","maxLength":64,"minLength":1,"type":["string","null"]}},"required":["brandName"],"type":"object"},"DomainDmarc":{"properties":{"domain":{"description":"Domain name","type":"string"},"readiness":{"$ref":"#/components/schemas/DmarcReadiness"},"topSources":{"description":"Highest volume sending sources","items":{"$ref":"#/components/schemas/DmarcSource"},"type":"array"},"totals":{"properties":{"dkimAligned":{"description":"Messages with DKIM alignment","format":"int64","type":"integer"},"firstSeen":{"description":"Earliest report timestamp in epoch seconds, or null","format":"int64","type":["integer","null"]},"lastSeen":{"description":"Latest report timestamp in epoch seconds, or null","format":"int64","type":["integer","null"]},"messages":{"description":"Total messages reported","format":"int64","type":"integer"},"passing":{"description":"Total messages passing DMARC","format":"int64","type":"integer"},"quarantined":{"description":"Messages quarantined by receivers","format":"int64","type":"integer"},"rejected":{"description":"Messages rejected by receivers","format":"int64","type":"integer"},"reporters":{"description":"Number of distinct reporting organizations","type":"integer"},"reports":{"description":"Total number of ingested XML reports","type":"integer"},"sources":{"description":"Number of distinct source sending IPs","type":"integer"},"spfAligned":{"description":"Messages with SPF alignment","format":"int64","type":"integer"}},"required":["reports","reporters","sources","messages","passing","dkimAligned","spfAligned","quarantined","rejected","firstSeen","lastSeen"],"type":"object"},"windowDays":{"description":"Lookback window in days","type":"integer"}},"required":["domain","windowDays","totals","readiness","topSources"],"type":"object"},"DomainDmarcReports":{"properties":{"domain":{"description":"Domain name","type":"string"},"nextCursor":{"description":"Pagination cursor for next page of reports","type":"string"},"reports":{"description":"List of ingested DMARC reports","items":{"$ref":"#/components/schemas/DmarcReport"},"type":"array"}},"required":["domain","reports"],"type":"object"},"DomainDmarcSources":{"properties":{"domain":{"description":"Domain name","type":"string"},"messages":{"description":"Total messages across all sources","format":"int64","type":"integer"},"sources":{"description":"List of all sending sources","items":{"$ref":"#/components/schemas/DmarcSource"},"type":"array"},"windowDays":{"description":"Lookback window in days","type":"integer"}},"required":["domain","windowDays","messages","sources"],"type":"object"},"DomainDnsCheck":{"properties":{"cached":{"description":"true = a stored verdict, not a fresh query","type":"boolean"},"checkedAt":{"format":"int64","type":["integer","null"]},"domain":{"type":"string"},"records":{"description":"The records this domain needs, plus liveness where known","items":{"$ref":"#/components/schemas/DnsRecordCheck"},"type":"array"},"resolverUnavailable":{"description":"true = DNS could not be queried; records are still returned, nothing stored","type":"boolean"},"status":{"$ref":"#/components/schemas/DnsStatus"}},"required":["domain","checkedAt","cached","status","records"],"type":"object"},"DomainEvents":{"properties":{"domain":{"description":"Domain name","type":"string"},"estimated":{"description":"True if numbers are estimated (false for authoritative logs)","type":"boolean"},"events":{"description":"List of authoritative traffic events","items":{"$ref":"#/components/schemas/TrafficEvent"},"type":"array"},"nextCursor":{"description":"Pagination cursor for next page of events","type":"string"},"range":{"description":"Time range queried (e.g. '24h', '7d')","type":"string"}},"required":["domain","range","events","estimated"],"type":"object"},"DomainHostname":{"properties":{"checkedAt":{"description":"Timestamp of the most recent verification check in epoch seconds","format":"int64","type":["integer","null"]},"createdAt":{"description":"Timestamp when hostname was configured in epoch seconds","format":"int64","type":["integer","null"]},"directOnly":{"description":"True if CNAME must resolve directly without HTTP proxying (mail/smtp)","type":"boolean"},"domain":{"description":"Domain name","type":"string"},"hostname":{"description":"Configured custom hostname, or null when unclaimed","type":["string","null"]},"nsTargets":{"description":"mx only: the platform nameserver hostnames the customer must publish as NS records at the claimed name (instead of a CNAME)","items":{"type":"string"},"type":"array"},"service":{"$ref":"#/components/schemas/HostnameService"},"status":{"$ref":"#/components/schemas/HostnameCheckStatus"},"target":{"description":"Expected CNAME target host to point DNS to (null for the NS-delegated mx service)","type":["string","null"]},"verifiedAt":{"description":"Timestamp when hostname was successfully verified in epoch seconds","format":"int64","type":["integer","null"]}},"required":["service","domain","hostname","target","directOnly","verifiedAt","checkedAt","status","createdAt"],"type":"object"},"DomainHostnameList":{"properties":{"canClaim":{"description":"True if this account plan permits claiming vanity hostnames","type":"boolean"},"domain":{"description":"Domain name","type":"string"},"hostnames":{"description":"Custom hostname configurations for every service slot","items":{"$ref":"#/components/schemas/DomainHostname"},"type":"array"}},"required":["domain","canClaim","hostnames"],"type":"object"},"DomainTraffic":{"properties":{"byOutcome":{"additionalProperties":{"format":"int64","type":"integer"},"description":"Breakdown of event counts by outcome","type":"object"},"domain":{"description":"Domain name","type":"string"},"estimated":{"description":"True if metrics are sampled estimates","type":"boolean"},"range":{"description":"Time range of statistics","type":"string"},"retentionDays":{"description":"Analytics retention window in days","type":"integer"},"rows":{"description":"Breakdown rows grouped by outcome and route kind","items":{"$ref":"#/components/schemas/TrafficRow"},"type":"array"},"series":{"description":"Time-series buckets for charting","items":{"$ref":"#/components/schemas/TrafficSeriesPoint"},"type":"array"},"totals":{"properties":{"bytes":{"description":"Total message size bytes","format":"int64","type":"integer"},"bytesIn":{"description":"Bytes received across the window, by daily usage's `inboundBytes` rule (see the series point)","format":"int64","type":"integer"},"bytesOut":{"description":"Bytes sent across the window, by daily usage's `outboundBytes` rule (see the series point)","format":"int64","type":"integer"},"events":{"description":"Total events count","format":"int64","type":"integer"},"forwarded":{"description":"Inbound-driven egress events — the forwarded subset of outbound","format":"int64","type":"integer"}},"required":["events","bytes","forwarded","bytesIn","bytesOut"],"type":"object"}},"required":["domain","range","totals","byOutcome","rows","estimated","retentionDays"],"type":"object"},"DomainUsage":{"properties":{"days":{"description":"Daily storage usage for this domain","items":{"$ref":"#/components/schemas/DomainUsageDay"},"type":"array"},"domain":{"description":"Domain name","type":"string"},"from":{"description":"Start date of range (YYYY-MM-DD)","type":"string"},"to":{"description":"End date of range (YYYY-MM-DD)","type":"string"}},"required":["domain","from","to","days"],"type":"object"},"DomainUsageDay":{"properties":{"day":{"description":"UTC date string (YYYY-MM-DD)","type":"string"},"estimated":{"description":"True if metrics were estimated or carried forward","type":"boolean"},"mailBytes":{"description":"Mail storage bytes for mailboxes on this domain, or null","format":"int64","type":["integer","null"]},"mailboxes":{"description":"Count of mailboxes on this domain","format":"int64","type":"integer"},"pimBytes":{"description":"Calendar and contacts storage bytes for this domain, or null","format":"int64","type":["integer","null"]}},"required":["day","mailBytes","pimBytes","mailboxes","estimated"],"type":"object"},"EmailSearchComparator":{"additionalProperties":{},"description":"An RFC 8620 §5.5 Comparator: {property, isAscending?, keyword?}. property is one of receivedAt|size|sentAt|from|subject|hasKeyword (a hasKeyword comparator also needs `keyword`).","type":"object"},"EmailSearchCondition":{"additionalProperties":{},"description":"An RFC 8621 §4.4 FilterCondition; every key optional, conditions in one object AND together. At most one full-text condition (text/subject/body) per filter, never under OR/NOT. A full-text condition is at most 512 characters and 64 words; a substring needle (from/to/cc/bcc/header) at most 50 bytes. $deleted is refused.","properties":{"after":{"description":"Received at or after this RFC 8620 UTCDate (e.g. 2026-08-01T00:00:00Z)","type":"string"},"allInThreadHaveKeyword":{"description":"Every live message in the conversation carries this keyword","type":"string"},"bcc":{"description":"Substring of the Bcc addresses (max 50 bytes)","type":"string"},"before":{"description":"Received strictly before this RFC 8620 UTCDate (e.g. 2026-08-01T00:00:00Z), the one place this API departs from epoch seconds","type":"string"},"body":{"description":"Full-text match over the body parts","type":"string"},"cc":{"description":"Substring of the Cc addresses (max 50 bytes)","type":"string"},"from":{"description":"Substring of the From addresses (max 50 bytes)","type":"string"},"hasAttachment":{"description":"Whether the message has file attachments","type":"boolean"},"hasKeyword":{"description":"The message carries this keyword or flag (e.g. $seen, $flagged, $forwarded)","type":"string"},"header":{"description":"[name] = the header is present; [name, value] = the header contains value. Indexed names only: subject, message-id, in-reply-to, from, to, cc, list-id","items":{"type":"string"},"maxItems":2,"minItems":1,"type":"array"},"inMailbox":{"description":"Only messages in this Mailbox, as L<labelId>: the `id` from GET /mailboxes/{mailboxId}/labels prefixed with L (INBOX is usually L1)","type":"string"},"inMailboxOtherThan":{"description":"Only messages in at least one Mailbox NOT listed (same L<labelId> ids)","items":{"type":"string"},"type":"array"},"maxSize":{"description":"Size in bytes is strictly below this","type":"integer"},"minSize":{"description":"Size in bytes is at least this","type":"integer"},"noneInThreadHaveKeyword":{"description":"No live message in the conversation carries this keyword","type":"string"},"notKeyword":{"description":"The message does NOT carry this keyword","type":"string"},"someInThreadHaveKeyword":{"description":"At least one live message in the conversation carries this keyword","type":"string"},"subject":{"description":"Full-text match over the Subject header","type":"string"},"text":{"description":"Full-text match over the whole message (subject and bodies)","type":"string"},"to":{"description":"Substring of the To addresses (max 50 bytes)","type":"string"}},"type":"object"},"EmailSearchFilter":{"anyOf":[{"$ref":"#/components/schemas/EmailSearchFilterOperator"},{"$ref":"#/components/schemas/EmailSearchCondition"}],"description":"An RFC 8621 §4.4 FilterCondition, or a boolean tree of them ({operator: AND|OR|NOT, conditions: [...]}). Bounded, and refused (never truncated) past the bound: the tree at most 32 levels deep and 512 nodes, and at most 64 bound values in total (an inMailboxOtherThan element costs one each)."},"EmailSearchFilterOperator":{"description":"A boolean combination of nested EmailSearchFilter nodes. Full-text conditions may not appear under OR or NOT.","properties":{"conditions":{"description":"Nested filters: each is itself an EmailSearchFilter (condition or operator)","items":{"$ref":"#/components/schemas/EmailSearchFilter"},"type":"array"},"operator":{"description":"How the nested conditions combine (RFC 8620 §5.5 FilterOperator)","enum":["AND","OR","NOT"],"type":"string"}},"required":["operator","conditions"],"type":"object"},"EmailSearchRequest":{"properties":{"calculateTotal":{"description":"Also return the total number of matches (an extra count).","type":"boolean"},"collapseThreads":{"description":"Return one representative message per conversation.","type":"boolean"},"excludeRoles":{"description":"System label roles whose mail this query must not return — e.g. `[\"trash\", \"junk\"]` for an All-Mail view. A message carrying ANY label with one of these roles is excluded, whatever else it carries. Says in one argument what a filter would need a label lookup and one bound value per label to say; a role no label answers to is simply not excluded.","items":{"enum":["inbox","sent","drafts","trash","archive","junk"],"type":"string"},"type":"array"},"fields":{"description":"`ids`: answer the matching message IDS only, in query order, under `ids` — no metadata rows, page cap 2000. For a client that needs an id set (an IMAP SEARCH with header or BODY criteria) and would otherwise download bodies to decide. Not combinable with `snippet`.","enum":["ids"],"type":"string"},"filter":{"$ref":"#/components/schemas/EmailSearchFilter"},"limit":{"description":"Page size; capped at 200, defaults to 25 — or up to 2000 with `fields: \"ids\"`.","maximum":2000,"minimum":1,"type":"integer"},"position":{"description":"Zero-based offset into the result list. A negative value counts back from the end (RFC 8620 §5.5).","type":"integer"},"snippet":{"description":"Also return highlighted <mark> excerpts (subject + body preview) for the matched text terms of this page's results. Each excerpt costs a body read, so at most the first 50 results carry one.","type":"boolean"},"sort":{"description":"Up to 4 comparators; an id tiebreak is always appended so the order is total.","items":{"$ref":"#/components/schemas/EmailSearchComparator"},"maxItems":4,"type":"array"}},"type":"object"},"EmailSearchResult":{"properties":{"ids":{"description":"With `fields: \"ids\"`: the matching message IDs in query order (`results` is then empty)","items":{"type":"string"},"type":"array"},"limit":{"description":"Effective page size limit applied by the server","format":"int64","type":"integer"},"position":{"description":"Zero-based index of the first result within total matches","format":"int64","type":"integer"},"results":{"description":"List of matching messages for the current page","items":{"$ref":"#/components/schemas/MessageMeta"},"type":"array"},"scanWindow":{"description":"The cap that clipped: the collapsed results were drawn from the newest this-many matching messages. Present only beside `truncated`, so a client can say \"more than N matches\" with the N the server applied.","format":"int64","type":"integer"},"snippets":{"description":"List of search term highlighted snippets for results","items":{"$ref":"#/components/schemas/EmailSearchSnippet"},"type":"array"},"total":{"description":"Total number of matching messages (when calculateTotal was true)","format":"int64","type":"integer"},"truncated":{"description":"Present (true) only on a collapseThreads query whose scan hit the server's row cap: the collapsed result set covers the newest matches, not all of them, and positional paging ends when that set does even though `total` (when requested) counts the whole match set. Present on EVERY page of such a query, not only the last, so a client can say so from page one.","type":"boolean"}},"required":["results","position"],"type":"object"},"EmailSearchSnippet":{"properties":{"id":{"description":"Message ULID this snippet belongs to","type":"string"},"preview":{"description":"Highlighted HTML snippet for the message body, or null if not matched","type":["string","null"]},"subject":{"description":"Highlighted HTML snippet for the subject line, or null if not matched","type":["string","null"]}},"required":["id","subject","preview"],"type":"object"},"EmailSearchSnippetsRequest":{"properties":{"filter":{"$ref":"#/components/schemas/EmailSearchFilter"},"ids":{"description":"Message ULIDs to excerpt — the `id` of each result row, at most 50 per call (each excerpt is a body read). An id the caller cannot see is omitted from the answer, never named.","items":{"type":"string"},"maxItems":50,"minItems":1,"type":"array"}},"required":["ids","filter"],"type":"object"},"EmailSearchSnippetsResult":{"properties":{"snippets":{"description":"One per visible id, in request order. A field is null when nothing in it matched — render the stored value.","items":{"$ref":"#/components/schemas/EmailSearchSnippet"},"type":"array"}},"required":["snippets"],"type":"object"},"EmptyTrashResult":{"properties":{"purgedCount":{"description":"Number of messages permanently removed from trash","format":"int64","type":"integer"}},"required":["purgedCount"],"type":"object"},"ErrorBody":{"additionalProperties":{},"properties":{"error":{"description":"Machine-readable snake_case error code","type":"string"}},"required":["error"],"type":"object"},"ErrorOrValidation":{"anyOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/ErrorBody"}]},"EventWebhook":{"properties":{"consecutiveFailures":{"description":"Consecutive delivery failures; reset by any success or PUT","type":"integer"},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"degraded":{"description":"Platform domains only: true while attempts above the hook's supported rate are queued on their retry ladder (never dropped). The health fields of a platform hook are a projection published at a fixed cadence of about a minute","type":"boolean"},"disabledReason":{"description":"'failing' after the 24h auto-disable; any PUT re-enables","type":["string","null"]},"domain":{"description":"Present on the domain scope","type":"string"},"enabled":{"type":"boolean"},"failingSince":{"description":"When the current failing streak began, epoch seconds","format":"int64","type":["integer","null"]},"hasSecret":{"description":"Whether a signing secret is set (write-only)","type":"boolean"},"lastDeliveredAt":{"description":"Last successful delivery, epoch seconds","format":"int64","type":["integer","null"]},"lastFailure":{"type":["string","null"]},"lastFailureAt":{"description":"Last failed delivery, epoch seconds","format":"int64","type":["integer","null"]},"mailboxId":{"description":"Present on the mailbox scope","type":"string"},"retryAfter":{"description":"Platform domains only: when the degraded hook has room again, epoch seconds","format":"int64","type":["integer","null"]},"scope":{"enum":["mailbox","domain"],"type":"string"},"updatedAt":{"description":"Last update timestamp in epoch seconds","format":"int64","type":"integer"},"url":{"type":"string"}},"required":["scope","url","hasSecret","enabled","disabledReason","failingSince","consecutiveFailures","lastDeliveredAt","lastFailureAt","lastFailure","createdAt","updatedAt"],"type":"object"},"EventWebhookActor":{"description":"Who caused it, or null when the platform did (a delivery, a retention sweep)","properties":{"id":{"description":"The acting principal's id (key id or mailbox ULID)","type":"string"},"mailbox":{"description":"Acting mailbox ULID, when the actor is a mailbox","type":"string"},"type":{"description":"Credential scope of the actor","enum":["system","account","mailbox"],"type":"string"}},"required":["type","id"],"type":["object","null"]},"EventWebhookEvent":{"properties":{"actor":{"$ref":"#/components/schemas/EventWebhookActor"},"data":{"description":"Event-specific identifiers (message id, label name, state tokens, ...), never message content. A state.changed event's data carries the current state token per type ({ Email, Mailbox, Thread, EmailDelivery }); its Email value is a valid `since` for GET /mailboxes/{mailboxId}/messages/changes"},"seq":{"description":"Mailbox outbox sequence number: present on store events (message.new, message.updated, ...), absent on worker-tier events (email.relayed, webhook.test, ...). Strictly increasing per mailbox; a gap you did not observe means a batch you missed","format":"int64","type":"integer"},"ts":{"description":"When the event happened, epoch seconds","format":"int64","type":"integer"},"type":{"description":"Event name. The vocabulary is ADDITIVE and shared with the live WebSocket feed (GET /mailboxes/{mailboxId}/events): message.new, message.imported, message.updated, message.expunged, message.restored, message.purged, label.created, label.renamed, label.updated, label.deleted, label.expunged, label.messages_updated, query.messages_updated, trash.emptied, thread.merged, state.changed, email.relayed, email.failed, webhook.test, ... Treat an unrecognized type as a generic 'something changed' nudge, never as an error","type":"string"}},"required":["type","ts","actor"],"type":"object"},"EventWebhookPayload":{"properties":{"accountId":{"description":"Owning account id, when known","type":"string"},"domain":{"description":"The batch's domain, when known","type":"string"},"events":{"description":"The batch's events, in order","items":{"$ref":"#/components/schemas/EventWebhookEvent"},"type":"array"},"id":{"description":"Batch id (ULID): the receiver's idempotency key. Constant across retries and across the mailbox/domain copies; dedupe on (id, scope)","type":"string"},"mailboxId":{"description":"The mailbox the batch is about, for store batches","type":"string"},"scope":{"description":"Which hook this copy addresses: the mailbox's own, or its domain's","enum":["mailbox","domain"],"type":"string"},"sentAt":{"description":"THIS attempt's clock, epoch seconds. Inside the signed body, so a freshness-tolerance check still holds for a day-three retry while `id` stays the dedupe constant","format":"int64","type":"integer"},"sequence":{"description":"The contiguous outbox range this batch drains; store batches only","properties":{"from":{"description":"First outbox sequence number in this batch","format":"int64","type":"integer"},"to":{"description":"Last outbox sequence number in this batch","format":"int64","type":"integer"}},"required":["from","to"],"type":"object"},"states":{"additionalProperties":{"type":"string"},"description":"Current sync state token per type ({ Email, Mailbox, Thread, EmailDelivery }); store batches only. The Email value is a valid `since` for GET /mailboxes/{mailboxId}/messages/changes, so a receiver can re-sync incrementally instead of re-listing","type":"object"}},"required":["id","scope","sentAt","events"],"type":"object"},"EventWebhookTestResult":{"properties":{"batchId":{"description":"The queued test batch's id — its outcome shows on the resource and in traffic","type":"string"}},"required":["batchId"],"type":"object"},"ExpungeNotice":{"properties":{"expunged":{"description":"True if the message was expunged (Recently deleted tier)","type":"boolean"},"expungedAt":{"description":"Timestamp when the message was expunged, in epoch seconds","format":"int64","type":"integer"},"purgeAfter":{"description":"Timestamp when permanent wipe will occur in epoch seconds","format":"int64","type":"integer"}},"required":["expunged","expungedAt","purgeAfter"],"type":"object"},"ExpungeResult":{"properties":{"expunged":{"description":"List of expunged message UIDs and IDs","items":{"$ref":"#/components/schemas/ExpungedUID"},"type":"array"},"messagesExpunged":{"description":"Total count of messages removed from this label","format":"int64","type":"integer"}},"required":["expunged","messagesExpunged"],"type":"object"},"ExpungedMessageMeta":{"allOf":[{"$ref":"#/components/schemas/MessageMeta"},{"properties":{"expungedAt":{"description":"Timestamp when the message was expunged, in epoch seconds","format":"int64","type":"integer"},"expungedLabels":{"description":"The labels this row literally held at the moment it was expunged. For a message deleted the ordinary way that is [\"Trash\"], because the delete moved it there first. To show or act on where it will actually go, read restoresTo.","items":{"type":"string"},"type":"array"},"purgeAfter":{"description":"Timestamp after which message will be permanently purged in epoch seconds","format":"int64","type":"integer"}},"required":["expungedAt","purgeAfter","expungedLabels"],"type":"object"}]},"ExpungedUID":{"properties":{"messageId":{"description":"Expunged message ULID","type":"string"},"uid":{"description":"Expunged message UID","format":"int64","type":"integer"}},"required":["uid","messageId"],"type":"object"},"FilterRule":{"additionalProperties":false,"properties":{"actions":{"items":{"$ref":"#/components/schemas/RuleAction"},"maxItems":8,"minItems":1,"type":"array"},"conditions":{"items":{"$ref":"#/components/schemas/RuleCondition"},"maxItems":8,"minItems":1,"type":"array"},"enabled":{"default":true,"type":"boolean"},"match":{"default":"all","enum":["all","any"],"type":"string"},"name":{"description":"Display label; also emitted as a comment in the compiled script","maxLength":128,"minLength":0,"type":"string"},"stop":{"default":false,"description":"Stop processing further rules when this one matches","type":"boolean"}},"required":["conditions","actions"],"type":"object"},"FilterRulesDeleted":{"properties":{"deleted":{"description":"True if filter rules document was deleted","type":"boolean"}},"required":["deleted"],"type":"object"},"FilterRulesPutResult":{"properties":{"created":{"description":"True if rules document was newly created (false if replaced)","type":"boolean"},"rules":{"description":"Saved filter rules","items":{"$ref":"#/components/schemas/FilterRule"},"type":"array"},"script":{"description":"Compiled Sieve script generated from the rules","type":"string"},"state":{"description":"Always 'active' when successfully saved","enum":["active"],"type":"string"}},"required":["rules","state","created","script"],"type":"object"},"FilterRulesState":{"properties":{"activeScript":{"description":"Name of the currently active Sieve script, or null","type":["string","null"]},"rules":{"description":"List of configured filter rules","items":{"$ref":"#/components/schemas/FilterRule"},"type":"array"},"script":{"description":"Compiled Sieve script code generated from these rules","type":"string"},"state":{"description":"Whether these JSON rules are currently the active filter","enum":["active","inactive"],"type":"string"},"updatedAt":{"description":"Timestamp when rules were last updated in epoch seconds","format":"int64","type":"integer"}},"required":["rules","state","activeScript","script","updatedAt"],"type":"object"},"FilteringBody":{"properties":{"discardIncoming":{"description":"Store nothing this mailbox receives (see FilteringSettings). An account key or system key only: an app password is refused 403 insufficient_scope","type":"boolean"},"trustContacts":{"description":"Trust the mailbox's own address book as an implicit allow list","type":"boolean"}},"type":"object"},"FilteringSettings":{"properties":{"discardIncoming":{"description":"When true, the mailbox stores nothing it receives: every message that arrives from someone else (inbound mail, mail from other mailboxes here, group copies, forwarded copies, delivery-status notices, platform notices) is accepted, passed to the mailbox's message webhook (GET/PUT /mailboxes/{mailboxId}/message-webhook) and the address's forward tap, counted as a receive, and then discarded, with no spam check, Sieve, vacation reply, forward-all, push or message.new event. The mailbox's own writes are still kept: its Sent copies and drafts, APPEND and Email/import, POP3 pickups. A blocked sender is still refused, and a receive hold still applies first. False by default; only the account (or the platform) may change it. Without a message webhook, a discard keeps no copy anywhere.","type":"boolean"},"trustContacts":{"description":"When true (the default), mail from a sender in this mailbox's own address book is delivered to the inbox even when the spam filter would have filed it to Junk, provided the sender identity was authenticated (DMARC for the From, SPF for the envelope). Explicit block lists still win.","type":"boolean"}},"required":["trustContacts","discardIncoming"],"type":"object"},"Forwarding":{"properties":{"destinations":{"description":"Every destination this mailbox has named","items":{"$ref":"#/components/schemas/ForwardingDestination"},"type":"array"},"forwardAll":{"$ref":"#/components/schemas/ForwardingSetting"}},"required":["destinations","forwardAll"],"type":"object"},"ForwardingDestination":{"properties":{"address":{"description":"The destination address, lowercased","type":"string"},"codeExpiresAt":{"description":"When the outstanding confirmation code expires, in epoch seconds, or null when none is outstanding","format":"int64","type":["integer","null"]},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"id":{"description":"Destination ULID — the handle every route uses, so no address is path-encoded","type":"string"},"state":{"description":"Verification state; only 'verified' forwards","enum":["pending","verified","revoked_by_recipient"],"type":"string"},"verifiedAt":{"description":"When the code was consumed, in epoch seconds, or null","format":"int64","type":["integer","null"]}},"required":["id","address","state","codeExpiresAt","verifiedAt","createdAt"],"type":"object"},"ForwardingDestinationPending":{"properties":{"address":{"description":"The destination address, masked (j••@ex•••.com)","type":"string"},"expiresAt":{"description":"When the mailed code expires, in epoch seconds","format":"int64","type":"integer"},"id":{"description":"Destination ULID","type":"string"},"state":{"description":"Always 'pending' immediately after a code is mailed","enum":["pending","verified","revoked_by_recipient"],"type":"string"}},"required":["id","address","state","expiresAt"],"type":"object"},"ForwardingDestinationVerified":{"properties":{"address":{"description":"The destination address, masked","type":"string"},"id":{"description":"Destination ULID","type":"string"},"state":{"description":"'verified'","enum":["pending","verified","revoked_by_recipient"],"type":"string"}},"required":["id","address","state"],"type":"object"},"ForwardingSetting":{"description":"The forward-everything setting","properties":{"address":{"description":"That destination's address, or null when off","type":["string","null"]},"destinationId":{"description":"The destination receiving a copy of all mail, or null when off","type":["string","null"]},"paused":{"description":"True while forwarding is paused; the destination stays verified","type":"boolean"}},"required":["destinationId","address","paused"],"type":"object"},"FreeBusy":{"properties":{"busy":{"description":"Busy intervals, clamped to the window and sorted. Intervals of the SAME type are merged — a client reads 'busy from, busy to', and handing it the fragments would leak how many meetings overlap — while a BUSY and a BUSY-TENTATIVE interval may overlap each other (RFC 4791 §7.10)","items":{"properties":{"end":{"description":"Busy until, unix seconds (exclusive)","format":"int64","type":"integer"},"start":{"description":"Busy from, unix seconds","format":"int64","type":"integer"},"type":{"description":"RFC 5545 §3.2.9 FBTYPE: BUSY, or BUSY-TENTATIVE for time only tentatively taken","enum":["BUSY","BUSY-TENTATIVE"],"type":"string"}},"required":["start","end","type"],"type":"object"},"type":"array"},"end":{"description":"Window end actually answered, unix seconds (exclusive)","format":"int64","type":"integer"},"start":{"description":"Window start actually answered, unix seconds","format":"int64","type":"integer"}},"required":["start","end","busy"],"type":"object"},"FreeBusyBatchResult":{"properties":{"end":{"description":"Window end actually answered, unix seconds (exclusive)","format":"int64","type":"integer"},"results":{"description":"One entry per requested address, in the order requested","items":{"properties":{"address":{"description":"The address as it was asked about, echoed back","type":"string"},"busy":{"description":"Busy intervals; absent when `visible` is false","items":{"properties":{"end":{"format":"int64","type":"integer"},"start":{"format":"int64","type":"integer"},"type":{"description":"RFC 5545 §3.2.9 FBTYPE: BUSY, or BUSY-TENTATIVE for time only tentatively taken","enum":["BUSY","BUSY-TENTATIVE"],"type":"string"}},"required":["start","end","type"],"type":"object"},"type":"array"},"visible":{"description":"False for a subject this caller may not see AND for an address that does not exist — deliberately the same answer, so this cannot be used to discover who exists","type":"boolean"}},"required":["address","visible"],"type":"object"},"type":"array"},"start":{"description":"Window start actually answered, unix seconds","format":"int64","type":"integer"}},"required":["start","end","results"],"type":"object"},"HeadBatch":{"properties":{"heads":{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/HeadEntry"},{"type":"null"}]},"description":"Map of message ID to its header block, one entry per distinct requested id. Null means the message is unknown, not live (pending or in the trash tier), outside the caller's folder scope, or its blob is unreadable — in every case, read the whole message instead.","type":"object"}},"required":["heads"],"type":"object"},"HeadEntry":{"properties":{"header":{"description":"Base64 of the message's raw header block as stored — every header line byte-for-byte, line endings preserved, up to and including the blank separator line (what IMAP BODY[HEADER] returns). The separator is the first empty line, LF or CRLF on either side; a message with no blank line at all is all headers and is returned whole. Null when truncated.","type":["string","null"]},"truncated":{"description":"True when the header block runs past the 64 KB head window this read is bounded to; the caller must read the whole message (/raw) for it. Header is null in that case.","type":"boolean"}},"required":["header","truncated"],"type":"object"},"HostnameCheckStatus":{"description":"Verification details from the latest check","properties":{"caa":{"description":"CAA certificate authorization status (mail/smtp only)","enum":["ok","blocked","unknown"],"type":"string"},"certificate":{"description":"TLS certificate issuance status on edge nodes (mail/smtp only)","enum":["live","pending","unknown"],"type":"string"},"cf":{"description":"Cloudflare SaaS status (webmail/dav only)","properties":{"configured":{"description":"True if SaaS routing zone is configured","type":"boolean"},"provisioned":{"description":"True if Cloudflare custom hostname was provisioned","type":"boolean"},"ready":{"description":"True if custom hostname is active and ready to serve traffic","type":"boolean"},"sslStatus":{"description":"Cloudflare SSL certificate state","type":["string","null"]},"status":{"description":"Cloudflare hostname verification state","type":["string","null"]}},"required":["status","sslStatus","ready","configured","provisioned"],"type":"object"},"cname":{"description":"CNAME resolution status against the expected platform target (CNAME services only)","enum":["ok","mismatch","missing","unknown","proxied"],"type":"string"},"delegationSource":{"description":"mx only: which side of the zone cut the compared NS set came from. 'parent' = the delegation the customer published, read from their own nameservers. 'responder' = the parent zone could not be read (a Cloudflare-hosted zone is the common case), so the platform responder's own answer was used: it proves the delegation reaches us, not that the set is complete or exclusive","enum":["parent","responder"],"type":"string"},"found":{"description":"Values returned by the DNS resolver","items":{"type":"string"},"type":"array"},"ns":{"description":"NS delegation status against the platform nameserver set (mx only). What it proves depends on delegationSource: with 'parent' the published delegation set was compared, so a partial delegation or a foreign nameserver beside ours is 'mismatch'; with 'responder' only reachability of the platform nameservers through the delegation was proven","enum":["ok","mismatch","missing","unknown"],"type":"string"},"resolution":{"description":"mx only, display: whether an address query through the delegation answers — proof the platform responder serves this name. Never gates verification","enum":["ok","none","unknown"],"type":"string"}},"required":["found"],"type":["object","null"]},"HostnameService":{"description":"Platform service name","enum":["mail","smtp","webmail","dav","mx"],"type":"string"},"Identity":{"allOf":[{"$ref":"#/components/schemas/Mailbox"},{"properties":{"activityDay":{"description":"The UTC date (YYYY-MM-DD) of this identity's latest recorded client activity, kept for the identity's lifetime; null means no recorded activity. Show it as returned, not converted to a local timezone. Omitted for a grant holder reading a mailbox shared with them and for a credential scoped below `full`: the owner's client history is theirs alone, like the client list itself","format":"date","type":["string","null"]},"facets":{"$ref":"#/components/schemas/IdentityFacets"}},"required":["facets"],"type":"object"}]},"IdentityActivity":{"properties":{"activityDay":{"description":"The UTC date (YYYY-MM-DD) of the identity's latest recorded client activity; null means no recorded activity. Show it as returned, not converted to a local timezone","format":"date","type":["string","null"]},"id":{"description":"Identity ULID","type":"string"},"primaryAddress":{"description":"The identity's primary address, or null for one without","type":["string","null"]}},"required":["id","primaryAddress","activityDay"],"type":"object"},"IdentityAddresses":{"properties":{"addresses":{"description":"Lowercased addresses routed to this identity — its primary address first, then its route rows, deduplicated. Empty for an identity with no addresses at all (a calendar-only identity), which is an honest answer and not an error","items":{"type":"string"},"type":"array"}},"required":["addresses"],"type":"object"},"IdentityClient":{"properties":{"accountId":{"description":"The identity's account at first sighting, or null","type":["string","null"]},"asOrg":{"description":"Autonomous system organisation, or null (same rule)","type":["string","null"]},"asn":{"description":"Autonomous system number, or null (same rule)","format":"int64","type":["integer","null"]},"city":{"description":"City, or null (same rule as country)","type":["string","null"]},"client":{"description":"The client's self-description (User-Agent, IMAP ID) as last seen, or null","type":["string","null"]},"country":{"description":"ISO 3166-1 alpha-2 country, or null when NOBODY LOOKED — never 'unknown'. Mail-protocol rows carry null until the fleet resolves locations","type":["string","null"]},"credentialActive":{"description":"Whether the credential would still be accepted now: true while it exists, is not revoked and is not past its expiry; false once revoked, expired or purged; null when unattributed. Each webmail sign-in mints its own credential, so a `webmail` row whose value is false is a session that has ended","type":["boolean","null"]},"credentialId":{"description":"The credential the client presented — the thing to revoke — or null when the reporting surface could not attribute one. Never render null as 'your password'","type":["string","null"]},"credentialKind":{"description":"`password` (the identity's own password) or `app_password`; null when unattributed or purged","type":["string","null"]},"credentialName":{"description":"The credential's label as its owner gave it (\"old-phone\"; webmail names its sessions \"webmail session\"), so a reader can say which app password to revoke without a lookup per row. null when unattributed, unnamed, or purged; a revoked credential keeps its name","type":["string","null"]},"facets":{"description":"What the client TOUCHED — `mail`, `pim` (calendars, contacts, tasks) or both — never what the identity owns. A JMAP client that read a mailbox and a calendar carries both","items":{"enum":["mail","pim"],"type":"string"},"type":"array"},"firstSeenAt":{"description":"First sighting, epoch seconds","format":"int64","type":"integer"},"id":{"description":"Client row ULID — the FIRST sighting's; not the sort key","type":"string"},"identityId":{"description":"The identity this client reached","type":"string"},"ip":{"description":"The client's address as LAST seen, canonical (RFC 5952 for v6). An IPv6 client is one row per /64: the address here is the most recent host within it","type":"string"},"lastSeenAt":{"description":"Last sighting, epoch seconds — coalesced hourly, so exact for a first sighting and up to one hour stale after it. 'Connected now' is a presentation rule over this, not a fact the row asserts","format":"int64","type":"integer"},"notifiedAt":{"description":"When this client was flagged as a NEW LOCATION — a network or (country, network operator) the identity had not been reached from before — and the notice raised: mail to the identity's inbox and verified recovery address (unless the identity's prefs carry notifyNewClient: false) and an identity.client.new event. null for the first client an identity ever had, for a known network or location, and past the daily cap","format":"int64","type":["integer","null"]},"protocol":{"description":"How the client reached the platform. `dav` is a CalDAV/CardDAV request on neither half (a principal PROPFIND); `api` is the REST surface; `webmail` is a browser session reported by the webmail frontend","enum":["imap","pop3","sieve","smtp","caldav","carddav","dav","jmap","webmail","api"],"type":"string"},"touchCount":{"description":"How many coalesced sightings were recorded, not how many connections were made","format":"int64","type":"integer"}},"required":["id","identityId","accountId","protocol","facets","ip","credentialId","credentialName","credentialKind","credentialActive","client","country","city","asn","asOrg","firstSeenAt","lastSeenAt","touchCount","notifiedAt"],"type":"object"},"IdentityFacets":{"properties":{"mail":{"description":"Mail store details if bound","properties":{"expungedBytes":{"description":"Storage used by trash in bytes. Omitted when `unavailable` is true","format":"int64","type":"integer"},"expungedCount":{"description":"Number of messages in trash. Omitted when `unavailable` is true","format":"int64","type":"integer"},"messageCount":{"description":"Total number of active messages. Omitted when `unavailable` is true","format":"int64","type":"integer"},"provisioned":{"description":"True if the mail store has been initialized and may contain data. Omitted when `unavailable` is true","type":"boolean"},"storeId":{"description":"Mail store identifier","type":"string"},"unavailable":{"description":"True when the store did not report its usage in time (a storage fault, or a slow start); `provisioned` and the counts are then omitted, never zero. The store is still bound. Retry later for the counts. Absent otherwise","type":"boolean"},"usedBytes":{"description":"Total mail storage used in bytes. Omitted when `unavailable` is true","format":"int64","type":"integer"}},"required":["storeId"],"type":"object"},"pim":{"description":"PIM (calendar and contacts) store details if bound","properties":{"bytes":{"description":"Total storage used by calendar and contact objects in bytes. Omitted when `unavailable` is true","format":"int64","type":"integer"},"collections":{"description":"Total number of calendar and addressbook collections. Omitted when `unavailable` is true","format":"int64","type":"integer"},"objects":{"description":"Total number of calendar events and contact cards. Omitted when `unavailable` is true","format":"int64","type":"integer"},"provisioned":{"description":"True if the PIM store has been initialized and may contain data. Omitted when `unavailable` is true","type":"boolean"},"storeId":{"description":"PIM (calendar/contacts) store identifier","type":"string"},"unavailable":{"description":"True when the store did not report its usage in time (a storage fault, or a slow start); `provisioned` and the counts are then omitted, never zero. The store is still bound. Retry later for the counts. Absent otherwise","type":"boolean"}},"required":["storeId"],"type":"object"}},"type":"object"},"KeywordCount":{"properties":{"count":{"description":"How many of this mailbox's live messages carry it","format":"int64","type":"integer"},"keyword":{"description":"The keyword, canonical lowercase (JMAP keywords are case-insensitive)","type":"string"}},"required":["keyword","count"],"type":"object"},"KeywordListPage":{"properties":{"keywords":{"description":"Distinct keywords, most-used first, then alphabetical","items":{"$ref":"#/components/schemas/KeywordCount"},"type":"array"}},"required":["keywords"],"type":"object"},"LabelDeleteResult":{"properties":{"archived":{"description":"Messages left with no other label that fell back to the Archive label","type":"integer"},"deleted":{"enum":[true],"type":"boolean"}},"required":["deleted"],"type":"object"},"LabelInfo":{"properties":{"bytes":{"description":"Total storage size of live messages in this label in bytes","format":"int64","type":"integer"},"color":{"description":"Hex color code (#rrggbb) or null","type":["string","null"]},"deletedCount":{"description":"Number of live messages marked with \\Deleted flag","format":"int64","type":"integer"},"highestModseq":{"description":"Current RFC 7162 HIGHESTMODSEQ change tracker for this label","format":"int64","type":"integer"},"id":{"description":"Internal label numeric ID","format":"int64","type":"integer"},"isSubscribed":{"description":"True if folder is subscribed for client synchronization","type":"boolean"},"messageCount":{"description":"Total number of live messages in this label","format":"int64","type":"integer"},"name":{"description":"Label or folder name (e.g. INBOX, Archive, custom name)","type":"string"},"role":{"description":"System role if special folder, or null for custom user labels","enum":["inbox","sent","drafts","trash","archive","junk"],"type":["string","null"]},"sortOrder":{"description":"Display sort order index for mailbox list","format":"int64","type":"integer"},"uidNext":{"description":"Next message UID that will be assigned in this label","format":"int64","type":"integer"},"uidValidity":{"description":"IMAP UIDVALIDITY epoch for this label","format":"int64","type":"integer"},"unseenCount":{"description":"Number of unread messages in this label","format":"int64","type":"integer"}},"required":["id","name","role","uidValidity","uidNext","messageCount","unseenCount","deletedCount","bytes","sortOrder","isSubscribed","highestModseq","color"],"type":"object"},"LabelListPage":{"properties":{"labels":{"description":"All labels visible to this caller","items":{"$ref":"#/components/schemas/LabelInfo"},"type":"array"},"scheduledPending":{"description":"Number of sends scheduled and not yet released. Present only for the owner identity; absent (not zero) for a shared-mailbox viewer.","format":"int64","type":"integer"}},"required":["labels"],"type":"object"},"LabelMessagesUpdateResult":{"properties":{"archived":{"description":"Messages whose last label this patch removed that fell back to the Archive label instead of being expunged. Unlike `expunged`, this is a SUBSET of `updated`, not an alternative to it: an archived message was still updated, so `examined` equals `updated + unchanged + expunged + failed` and adding `archived` to `updated` double counts. Only present when the patch carried `orphans: \"archive\"`.","type":"integer"},"examined":{"description":"Memberships this call looked at, filtered-out ones included","type":"integer"},"expunged":{"description":"Messages whose last label this patch removed: they moved to the Recently-deleted tier, restorable until purge. Counted here rather than in `updated`.","type":"integer"},"failed":{"description":"Per-message refusals — a keyword cap, or a row that left the label between this call's scan and its write. Not an error: the rest of the call applied.","type":"integer"},"nextAfter":{"description":"Continuation cursor: call again with `after` set to this, the same `uidMax`, and the same patch. `null` means the range is drained. Repeating a call is harmless — a patch that changes nothing writes nothing, and a filing patch's earlier pages have already left the range.","format":"int64","type":["integer","null"]},"remaining":{"description":"Memberships left in the range this call did not reach, 0 when it finished. This counts what is UNEXAMINED, not what would match a flag filter — it is the figure a progress bar needs, and it is exact.","type":"integer"},"uidMax":{"description":"The resolved ceiling this call worked under. Send it back UNCHANGED on a continuation: it is what keeps the selection the one the user saw, and re-resolving it would let mail that arrived since drift into the gesture.","format":"int64","type":"integer"},"uidValidity":{"description":"UIDVALIDITY epoch of the label the patch ran against","format":"int64","type":"integer"},"unchanged":{"description":"Messages in the selection the patch provably would not have changed, so they were skipped","type":"integer"},"updated":{"description":"Messages the patch changed","type":"integer"}},"required":["uidValidity","uidMax","examined","updated","unchanged","expunged","archived","failed","remaining","nextAfter"],"type":"object"},"LabelUidEntry":{"properties":{"blobHash":{"description":"Storage blob SHA-256 hash","type":"string"},"flags":{"description":"System flags (seen, answered, flagged, draft, deleted)","items":{"type":"string"},"type":"array"},"id":{"description":"Message ULID","type":"string"},"keywords":{"description":"Custom keywords (e.g. $forwarded)","items":{"type":"string"},"type":"array"},"modseq":{"description":"RFC 7162 MODSEQ change sequence number","format":"int64","type":"integer"},"receivedAt":{"description":"Server receive timestamp in epoch seconds","format":"int64","type":"integer"},"sentAt":{"description":"Sent timestamp from Date header in epoch seconds, or null","format":"int64","type":["integer","null"]},"size":{"description":"Message size in bytes","format":"int64","type":"integer"},"uid":{"description":"Message UID inside this label","format":"int64","type":"integer"}},"required":["id","uid","modseq","flags","keywords","size","receivedAt","sentAt","blobHash"],"type":"object"},"LabelUidPage":{"properties":{"messages":{"description":"List of message summaries ordered by UID","items":{"$ref":"#/components/schemas/LabelUidEntry"},"type":"array"},"uidValidity":{"description":"UIDVALIDITY epoch of the label","format":"int64","type":"integer"}},"required":["messages","uidValidity"],"type":"object"},"LimitIncident":{"properties":{"accountId":{"description":"The account the limit belongs to","type":"string"},"axis":{"description":"The axis that refused (e.g. msgs_per_day, msgs_per_hour, bytes_day, mailbox_creates_day)","type":"string"},"direction":{"description":"The limit family","enum":["send","recv","forward","storage","mint"],"type":"string"},"firstAt":{"description":"When the episode opened (ms since epoch)","format":"int64","type":"integer"},"id":{"description":"Incident ULID","type":"string"},"ledgerId":{"description":"Originating ledger, present only on operator near rows when known. Account near rows measure this ledger's enforced shard slice, not aggregate account usage at 80% or 90% of the full displayed plan cap","type":"string"},"level":{"description":"Present only on a NEAR episode (operator-facing, and only when asked for): the per-cent level of `limit` that a check which PASSED left the count at or above, 80 or 90. Absent on an at-limit episode; an account's own feed lists only those. A near row is never noticed (notifiedAt stays null) and settles like any other: resolvedAt is stamped once a check has found the count back below the level and an hour has gone by without it rising again, on the store's next wake point","enum":[80,90],"type":"integer"},"limit":{"description":"The number in force when it fired","format":"int64","type":["integer","null"]},"notifiedAt":{"description":"When the tenant notice was CLAIMED for delivery into the notice mailbox — stamped before the local delivery, so a delivery cut short between the two leaves a stamp with no mail in rare cases (null = not noticed: shadow, no notice mailbox, inside the per-axis-per-scope daily floor, or a delivery that failed outright — which releases the stamp)","format":"int64","type":["integer","null"]},"resolvedAt":{"description":"When the episode ENDED: the instant a check last passed, stamped once the refusing store's reopen floor (one hour) has elapsed without another refusal, on its next wake point. Near rows also expire at firstAt plus seven days, even if a retired ledger never wakes again. null = still open or awaiting settlement","format":"int64","type":["integer","null"]},"scope":{"description":"Which scope's limit fired","enum":["mailbox","account","domain"],"type":"string"},"scopeId":{"description":"The scope's identity when narrower than the account: a mailbox ULID, or — for the receive allowance's door-charged subjects — `list:<address>` (a group judged at the weight of its fan-out) or `wh:<address>` (a webhook route); a domain for the forwarding family. A console must not assume a `mailbox` scope links to /mailboxes/:id","type":["string","null"]},"shadow":{"description":"True for a would-refuse under a LOG_ONLY flag (operator-facing only)","type":"boolean"}},"required":["id","accountId","scope","scopeId","direction","axis","limit","shadow","firstAt","resolvedAt","notifiedAt"],"type":"object"},"MailAddress":{"properties":{"email":{"description":"Email address (e.g. alice@example.com)","maxLength":320,"minLength":3,"type":"string"},"name":{"description":"Display name (e.g. Alice Smith)","maxLength":320,"type":["string","null"]}},"required":["email"],"type":"object"},"MailShare":{"properties":{"createdAt":{"description":"When the grant was first created, in epoch seconds","format":"int64","type":"integer"},"granteeAddress":{"description":"Primary email address of the identity that was given access, or null if it has none. Returned alongside the ULID so a client (notably IMAP GETACL, whose identifiers are addresses) does not have to look up each grantee separately","type":["string","null"]},"granteeIdentityId":{"description":"ULID of the identity that was given access","type":"string"},"labelScope":{"description":"Restrict the grant to specific FOLDERS, by name. Send `null` to share the whole mailbox — and note that OMITTING the field is a different request from sending null; see below.\n\nA folder-scoped grant may carry up to `lrswit` — everything `read_write` means. Within the granted folders it reads, marks read/unread privately, changes flags, files messages in, and trashes them. Two letters are rejected, naming themselves: `e` (permanently delete trashed messages), because a purge is irreversible and reaches messages filed in folders the holder cannot see; and `k` (create and rename folders), because a folder they created would not be inside their own grant.\n\n**What trashing means on a folder-scoped grant.** It removes the message from the folders they were granted — never from the mailbox. A message filed elsewhere as well stays exactly where you put it and simply leaves their view; a message that was only in their folders goes to Trash, where your normal 14-day undo reaches it. They can never permanently delete anything.\n\n**Filing in.** They must name one of their folders; there is no default (yours is INBOX, which is usually not one of theirs). Your filters do not run on what they file — a rule of yours could otherwise move it somewhere they cannot see, forward it, or send an auto-reply in your name.\n\nThe grant follows the folder if it is RENAMED, and does not follow the name: deleting a folder and creating a new one with the same name does not revive an old grant. The grant follows the folder into DELETION too: deleting a folder removes it from every grant that names it, and a grant left naming no folders is revoked outright — a share dies with its last folder. An empty list is rejected on WRITE — revoke with DELETE instead.\n\n**Omitting the field and sending `null` are different requests.** On a grant that is already folder-scoped, omitting `labelScope` PRESERVES the existing folders and changes only the rights; sending an explicit `null` is what widens the grant to the whole mailbox. Widening is a deliberate act, so it has to be spelled — otherwise any client that does not know about folder scopes (IMAP `SETACL` among them, since the ACL wire format cannot express one) would silently replace a one-folder grant with a whole-store grant, and drop the `lrs` cap along with it.\n\nOn READ an empty list can appear only on the OWNER's listing, and only as residue: it means every folder the grant named has since been deleted and the automatic revocation above could not run. Such a grant is dead — it matches nothing and gives access to nothing — and the owner's listing shows it so you can see it and remove it, while the shared-with-me listing never lists it. It is the one value you cannot send back unchanged: send DELETE, which is what a grant scoped to no folders already means.\n\nA folder-scoped viewer sees only these folders, and only their messages: listings, searches and conversations are all confined to them. Reachable over IMAP, the REST API and JMAP alike.\n\n**Changing a grant signs their clients out of sync.** Sync tokens on a folder-scoped grant are tied to the grant itself, so editing the folders or the rights makes every outstanding token stale exactly once: their clients re-list and carry on. Any live event stream they hold is closed at the same moment, so a narrowed grant takes effect immediately rather than when their connection happens to drop.\n\nNull means the whole mailbox is shared.","items":{"type":"string"},"type":["array","null"]},"mailboxId":{"description":"ULID of the mailbox being shared (the owner's store)","type":"string"},"rights":{"description":"What the person you shared with is allowed to do, written as a set of letters in any order (stored and returned in the canonical order below).\n\n| Letter | Allows |\n| --- | --- |\n| `l` | See the mailbox in folder listings |\n| `r` | Read messages |\n| `s` | Change the read/unread mark — each person's own, never shared |\n| `w` | Change other flags, such as flagged or answered |\n| `i` | Put messages in: append, copy in, move in |\n| `k` | Create and rename labels |\n| `t` | Move messages to trash |\n| `e` | Permanently delete trashed messages |\n\nInstead of letters you may send a preset name, which is usually what you want: `read` or `read_only` (= `lrs`), `read_write` (= `lrswit`), or `admin` / `full` (= `lrswikte`, everything a grant can carry). Hyphenated spellings work too (`read-only`, `read-write`).\n\n**Three things no grant ever allows.** It does not allow sending mail as the mailbox owner. It does not allow deleting labels (`x`): that sends every message whose only label it was to the trash, which the owner may do with their own credentials but not hand to a delegate. And it does not allow re-sharing (`a`, RFC 4314's administration right): only the mailbox owner and account administrators can change who has access. Asking for `x` or `a` is refused with the letters named (an invalid_rights error), never quietly dropped.\n\nLetters outside the table (RFC 4314's `p`, and the obsolete `c` and `d`) are rejected and named back to you rather than ignored, so a grant never quietly means less than what you asked for. A repeated letter is rejected for the same reason.","type":"string"}},"required":["mailboxId","granteeIdentityId","granteeAddress","rights","labelScope","createdAt"],"type":"object"},"MailTemplate":{"properties":{"createdAt":{"type":"integer"},"defaultLang":{"type":"string"},"from":{"description":"The From address; always set on a template this API created","type":["string","null"]},"languages":{"description":"The languages this template has copy for","items":{"type":"string"},"type":"array"},"name":{"type":"string"},"replyTo":{"type":["string","null"]},"slug":{"type":"string"},"updatedAt":{"type":"integer"},"variables":{"additionalProperties":{"properties":{"description":{"type":"string"},"sample":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Dummy data for the preview. A flag's sample is a boolean: the string \"false\" is truthy"}},"type":"object"},"type":"object"},"version":{"description":"Bumped by every write that changes what a send would produce","type":"integer"}},"required":["slug","name","from","replyTo","variables","defaultLang","version","languages","createdAt","updatedAt"],"type":"object"},"MailTemplateDetail":{"allOf":[{"$ref":"#/components/schemas/MailTemplate"},{"properties":{"variants":{"items":{"$ref":"#/components/schemas/MailTemplateVariant"},"type":"array"}},"required":["variants"],"type":"object"}]},"MailTemplateList":{"properties":{"templates":{"items":{"$ref":"#/components/schemas/MailTemplate"},"type":"array"}},"required":["templates"],"type":"object"},"MailTemplateRender":{"properties":{"html":{"type":["string","null"]},"langUsed":{"type":"string"},"slug":{"type":"string"},"source":{"description":"`draft` when the call carried copy to preview, `stored` when it rendered the template's own copy","enum":["stored","draft"],"type":"string"},"subject":{"type":"string"},"templateVersion":{"type":"integer"},"text":{"type":"string"},"variables":{"items":{"$ref":"#/components/schemas/MailTemplateVariable"},"type":"array"}},"required":["slug","langUsed","templateVersion","subject","text","html","variables","source"],"type":"object"},"MailTemplateSend":{"properties":{"deliveryId":{"description":"The batch id; retry with it to converge only the failures","type":"string"},"langUsed":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/MailTemplateSendRow"},"type":"array"},"slug":{"type":"string"},"templateVersion":{"type":"integer"}},"required":["slug","langUsed","templateVersion","deliveryId","results"],"type":"object"},"MailTemplateSendRow":{"properties":{"address":{"type":"string"},"deliveryId":{"description":"This recipient's leg key, the same shape /send answers","type":"string"},"error":{"description":"Why, when failed. 'sending_paused' and 'sending_disabled' mean a hold on the sender (mailbox, domain or account) landed while the request was running: recipients already handled keep their status and the rest are refused. 'sending_paused' is temporary: retry with the same delivery id once the hold lifts. 'sending_disabled' is permanent. A sending_paused row is temporary even where it carries no `retryAfterSeconds`.","type":"string"},"retryAfterSeconds":{"description":"Set on the rows a temporary refusal stopped: retry this recipient after this long","type":"integer"},"sentCopy":{"enum":["saved","duplicate","over_quota"],"type":"string"},"status":{"enum":["delivered","queued","filtered","failed"],"type":"string"}},"required":["address","status","deliveryId"],"type":"object"},"MailTemplateVariable":{"properties":{"bodies":{"description":"Which fields reference it","items":{"enum":["subject","text","html"],"type":"string"},"type":"array"},"description":{"type":["string","null"]},"filledFromSample":{"description":"True when the preview's sample stood in for a value not passed","type":"boolean"},"name":{"type":"string"},"sample":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"required":["name","description","sample","bodies","filledFromSample"],"type":"object"},"MailTemplateVariant":{"properties":{"html":{"type":["string","null"]},"lang":{"type":"string"},"subject":{"type":"string"},"text":{"type":"string"},"updatedAt":{"type":"integer"}},"required":["lang","subject","text","html","updatedAt"],"type":"object"},"Mailbox":{"properties":{"accountId":{"description":"Account ID owning this mailbox, or null","type":["string","null"]},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"ephemeral":{"description":"Whether the mailbox was created DISPOSABLE (ephemeral: true at creation, immutable afterwards): its DELETE destroys it at once — no undo record, no 7-day window, the address free again immediately. False for every ordinary mailbox, whose DELETE keeps the window","type":"boolean"},"groupAddress":{"description":"When this identity is a GROUP PERSONA, the group address whose archive it keeps and which it may send as; null for every other identity. A persona has no primaryAddress, cannot be a route target, refuses its own DELETE (delete the group route instead) and its Sieve/rules writes, and is exempt from max_mailboxes","type":["string","null"]},"hasMailStore":{"description":"Whether this identity has the mail capability. False for a calendar/contacts-only identity; true may also have a null primaryAddress. Derived from the directory row without reading or provisioning a store, not an indication that the store has been initialized or contains messages","type":"boolean"},"id":{"description":"Unique mailbox ULID","type":"string"},"permittedRecipients":{"description":"This mailbox's outbound recipient allowlist, written by system callers only. Entries are exact addresses (`jo@acme.dev`) or domain wildcards (`*@acme.dev`). null = unrestricted (the default); [] = may send to nobody. A submission outside the list is refused with 403 recipient_not_permitted (SMTP 550). Egress only: receiving is unaffected. A credential's own permittedRecipients may restrict sending further","items":{"type":"string"},"type":["array","null"]},"primaryAddress":{"description":"Primary email address assigned to this mailbox, or null if none","type":["string","null"]},"provisioningPending":{"description":"Present, true, only while this identity's creation with messageWebhook or eventWebhook is still setting up: mail to its address and its calendar and contact writes are refused as temporary (503 temporary_failure) until it is, and the setup completes in the background. Absent for every other identity","type":"boolean"},"quotaBytes":{"description":"Storage quota in bytes, or null for unlimited","format":"int64","type":["integer","null"]},"receiveHold":{"anyOf":[{"enum":["paused","disabled"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"The account owner's hold on this mailbox's RECEIVING, independent of suspension and of sendHold: 'paused' = senders are told to retry later (429 receiving_paused, SMTP 451; they give up after about four to five days, so a pause is for short interruptions), 'disabled' = mail to it is rejected at once (403 receiving_disabled, SMTP 550), null = receiving. Set with PATCH {\"receiveHold\": \"paused\"|\"disabled\"|null}, or on create"},"receiveHoldAt":{"description":"When the current receiveHold was set (epoch seconds), restamped when the mode changes; null while receiving. The age of a pause is what decides whether it is still a pause: warn from the third day","format":"int64","type":["integer","null"]},"receiveHoldPending":{"description":"Whether the current receiveHold has not yet reached the mailbox's store: true right after a change still being applied (PATCH answered 202), false once it holds. Poll until false","type":"boolean"},"retentionDays":{"description":"The mailbox's OWN time-based retention window in days (null = none; the account default applies if one is set). The window in force, with a preview, is GET /mailboxes/:id/retention","type":["integer","null"]},"semantic":{"description":"Whether SEMANTIC (meaning-based) search is enabled for this mailbox: messages are embedded after delivery and GET /mailboxes/:id/search/semantic and …/messages/:id/similar answer. Tenant-set, gated by the account's plan; off by default. Turning it off DELETES the mailbox's embeddings","type":"boolean"},"sendHold":{"anyOf":[{"enum":["disabled","paused"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"This mailbox's own operator enforcement: 'disabled' = permanent stop (403 sending_disabled), 'paused' = reversible hold (429 sending_paused), null = neither. System-written only"},"sendMsgsPerDay":{"description":"Daily outbound message limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"sendMsgsPerHour":{"description":"Hourly (burst) outbound message limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"sendRcptsPerDay":{"description":"Daily outbound recipient limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"sendRcptsPerHour":{"description":"Hourly (burst) outbound recipient limit (null = platform default, 0 = unlimited)","format":"int64","type":["integer","null"]},"suspendedAt":{"description":"When the account owner suspended this mailbox (epoch seconds), null when it is not suspended. While suspended its logins are refused as a wrong password is, its sending is held (429 sending_paused) and its open sessions end; it still receives mail, and its owner keys can still read and administer it. Set with PATCH {\"suspended\": true|false}","format":"int64","type":["integer","null"]},"suspensionPending":{"description":"Whether the current suspendedAt has not yet reached every core gate it must: true right after a change whose enforcement is still being applied (PATCH answered 202), false once it holds everywhere. Poll until false","type":"boolean"}},"required":["id","primaryAddress","hasMailStore","quotaBytes","accountId","createdAt","sendHold","permittedRecipients","suspendedAt","suspensionPending","receiveHold","receiveHoldAt","receiveHoldPending","sendMsgsPerDay","sendRcptsPerDay","sendMsgsPerHour","sendRcptsPerHour","retentionDays","groupAddress","semantic","ephemeral"],"type":"object"},"MailboxDeleteResult":{"properties":{"deleted":{"description":"True if the mailbox was deleted","type":"boolean"},"purged":{"description":"True if the mailbox was permanently purged immediately","type":"boolean"},"restorable":{"description":"True if the mailbox can still be restored","type":"boolean"},"restorableUntil":{"description":"Timestamp until which restore is allowed in epoch seconds","format":"int64","type":"integer"}},"required":["deleted","restorable"],"type":"object"},"MailboxRestoreResult":{"properties":{"accountId":{"description":"Account ID, or null","type":["string","null"]},"addressChanged":{"description":"True if the primary address had to be cleared because it was claimed while deleted","type":"boolean"},"id":{"description":"Mailbox ULID","type":"string"},"primaryAddress":{"description":"Restored primary address, or null","type":["string","null"]},"quotaBytes":{"description":"Storage quota in bytes, or null","format":"int64","type":["integer","null"]},"restored":{"description":"True if the mailbox was restored","type":"boolean"}},"required":["restored","id","accountId","quotaBytes","primaryAddress","addressChanged"],"type":"object"},"MailboxRouting":{"properties":{"addresses":{"description":"Primary address first, then routes and their alias-domain spellings, catch-alls, patterns, and groups; at most 200 eligible, distinct entries. An address that neither receives nor sends is left out. Not recognised as membership: a member only a pattern or catch-all brings here, a nested group, and a group on another account's domain","items":{"properties":{"address":{"description":"Lowercased. An exact address, or `<pattern>@domain` for a wildcard: `*@domain` for a catch-all, `sales-*@domain` for a narrower pattern","type":"string"},"canSend":{"description":"Whether this mailbox may send as it: its domain may send, and for a group, this mailbox is the persona. Mailbox-wide holds are reported by send-state, not here","type":"boolean"},"kind":{"description":"`primary`: the mailbox's own address. `address`: another route to it, or an alias domain's spelling of one. `catch_all`: a bare `*` pattern. `pattern`: a narrower wildcard. `group`: a group this mailbox is a member of or the persona of. A member counts when routing would bring it here through one of the mailbox's own addresses: written exactly, on an alias domain, or as a `+tag` form where the domain splits tags","enum":["primary","address","catch_all","pattern","group"],"type":"string"},"receives":{"description":"Whether mail to this address arrives here: its domain is enabled and receives here (not send-only), and for a group, this mailbox is a member or its persona archive. An alias spelling also requires its canonical domain to receive","type":"boolean"},"subaddressing":{"description":"Whether `local+tag@domain` forms reach it too. Follows the canonical domain for an alias spelling. Always false on a wildcard, which already covers every local part","type":"boolean"}},"required":["address","kind","receives","canSend","subaddressing"],"type":"object"},"type":"array"},"truncated":{"description":"True when the caller can see more than 200 eligible, distinct entries","type":"boolean"}},"required":["addresses","truncated"],"type":"object"},"MailboxWithStats":{"allOf":[{"$ref":"#/components/schemas/Mailbox"},{"properties":{"databaseLimitBytes":{"description":"Ceiling limit for metadata database size in bytes","format":"int64","type":"integer"},"databaseSize":{"description":"SQLite metadata database size in bytes","format":"int64","type":"integer"},"expungedBytes":{"description":"Storage recoverable by emptying trash in bytes","format":"int64","type":"integer"},"expungedCount":{"description":"Number of soft-deleted messages in trash","format":"int64","type":"integer"},"liveSockets":{"description":"Currently connected live-events WebSocket connections","type":"integer"},"messageCount":{"description":"Total number of active messages","format":"int64","type":"integer"},"semanticFloor":{"description":"When semantic search is on: the earliest arrival time (epoch seconds) the backfill embeds — mail received before it is lexically searchable only. 0 = everything. Lower it with PATCH /identities/:id { semanticFloor } (\"index older mail\"); null when semantic search is off","format":"int64","type":["integer","null"]},"socketCapacity":{"description":"Maximum allowed simultaneous WebSocket connections","type":"integer"},"socketsByClass":{"additionalProperties":{"type":"integer"},"description":"Active WebSocket connections broken down by client class","type":"object"},"usedBytes":{"description":"Total storage used in bytes including trash","format":"int64","type":"integer"}},"type":"object"}]},"MailboxWithUsage":{"allOf":[{"$ref":"#/components/schemas/Mailbox"},{"properties":{"databaseSize":{"description":"Sampled size of the store's own metadata database in bytes — the axis the store_metadata_full ceiling guards (metadata + search index, not message bytes); null when the sample predates this measure","format":"int64","type":["integer","null"]},"messageCount":{"description":"Total number of active messages","format":"int64","type":["integer","null"]},"pimBytes":{"description":"Storage used by calendar and contact objects in bytes","format":"int64","type":["integer","null"]},"trashBytes":{"description":"Storage used by messages in trash in bytes","format":"int64","type":["integer","null"]},"usageAt":{"description":"Timestamp when usage was sampled in epoch seconds","format":"int64","type":"integer"},"usageStale":{"description":"True if the sampled usage figures could not be refreshed recently","type":"boolean"},"usedBytes":{"description":"Total active message storage used in bytes","format":"int64","type":"integer"}},"type":"object"}]},"MessageAuth":{"description":"Stored SMTP authentication and original inbound junk verdicts. Missing verdicts are null; the object is null when none were recorded (including APPEND and local Sent copies). Junk does not follow later label changes.","properties":{"arc":{"description":"ARC verdict, or null","type":["string","null"]},"dkim":{"description":"DKIM verdict, or null","type":["string","null"]},"dmarc":{"description":"DMARC verdict, or null","type":["string","null"]},"junk":{"description":"The inbound spam verdict (X-OpenEmail-Junk), or null when none was stamped","type":["boolean","null"]},"spf":{"description":"SPF verdict (pass/fail/softfail/none/...), or null","type":["string","null"]}},"required":["spf","dkim","dmarc","arc","junk"],"type":["object","null"]},"MessageBatch":{"properties":{"messages":{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/MessageMeta"},{"type":"null"}]},"description":"Map of message ID to message metadata","type":"object"}},"required":["messages"],"type":"object"},"MessageChangesFeed":{"properties":{"created":{"description":"Message IDs that newly appeared (delivered, imported, or restored)","items":{"type":"string"},"type":"array"},"destroyed":{"description":"Message IDs that were deleted, expunged, or purged","items":{"type":"string"},"type":"array"},"hasMore":{"description":"True if more changes remain to be polled immediately","type":"boolean"},"labels":{"description":"With `include=labels`: the label vector as of `newState`, exactly `GET /labels`' shape","items":{"$ref":"#/components/schemas/LabelInfo"},"type":"array"},"newState":{"description":"New opaque state token for the next sync poll","type":"string"},"oldState":{"description":"Echo of the previous state token passed in the request","type":"string"},"sync":{"additionalProperties":{"$ref":"#/components/schemas/MessageSyncEntry"},"description":"With `include=sync`: the folder-sync projection of every `created`/`updated` id on this page, keyed by id","type":"object"},"updated":{"description":"Message IDs whose flags, keywords, labels, or thread changed","items":{"type":"string"},"type":"array"}},"required":["created","updated","destroyed","newState","hasMore"],"type":"object"},"MessageCopyEntry":{"properties":{"id":{"description":"The SOURCE message ULID","type":"string"},"newId":{"description":"The copy's message ULID in the destination (copied, duplicate)","type":"string"},"sourceRemoved":{"description":"On a move, whether the source message was then deleted. False means the move completed as a copy: the copy exists and the original is still where it was.","type":"boolean"},"status":{"description":"`copied`: stored in the destination. `duplicate`: an earlier attempt under the same gestureId already stored it — treat as copied, `newId` names that copy. `not_found`: no such message in the source, or it is outside your grant. `over_quota` / `account_over_quota` / `store_metadata_full` / `unknown_label` / `mailbox_gone` are refusals by the DESTINATION that the next message would meet too: the rest of the page carries the same status and `nextAfter` is null. `receiving_paused` / `receiving_disabled` are the same kind: the destination's receive hold, which refuses a copy into a mailbox you reach through a share grant (paused may clear; disabled will not until its owner clears it). Its own user and its account copy into it as ever. `failed` is retryable under the same gestureId.","enum":["copied","duplicate","not_found","too_large","blob_missing","over_quota","account_over_quota","store_metadata_full","unknown_label","mailbox_gone","receiving_paused","receiving_disabled","failed"],"type":"string"},"threadId":{"description":"The conversation the copy joined in the destination (copied, duplicate)","type":["string","null"]}},"required":["id","status"],"type":"object"},"MessageCopyResult":{"properties":{"nextAfter":{"description":"Pass as `after` to continue with the next page under the same operands. Null when every target has been answered, and when the destination refused a message — `remaining` is then what was never attempted.","type":["string","null"]},"remaining":{"description":"Targets still to be answered after this page","format":"int64","type":"integer"},"results":{"description":"This page's outcomes, one per source message, in ascending id order","items":{"$ref":"#/components/schemas/MessageCopyEntry"},"type":"array"}},"required":["results","nextAfter","remaining"],"type":"object"},"MessageDeleteResult":{"properties":{"blobOrphaned":{"description":"True if message blob was permanently deleted from storage","type":"boolean"},"deleted":{"description":"True if message was deleted","type":"boolean"},"expunged":{"description":"True if the message was expunged (Recently deleted tier)","type":"boolean"},"expungedAt":{"description":"Timestamp when the message was expunged, in epoch seconds","format":"int64","type":"integer"},"purgeAfter":{"description":"Timestamp when message will be permanently purged","format":"int64","type":"integer"},"purged":{"description":"True if message was permanently purged","type":"boolean"},"removedFromLabel":{"description":"Label name the message was removed from","type":"string"}},"type":"object"},"MessageDeliveryList":{"properties":{"deliveries":{"description":"List of delivery statuses in this page","items":{"$ref":"#/components/schemas/MessageDeliveryStatus"},"type":"array"},"nextCursor":{"description":"Fetch the next page with this cursor and the same selector; absent on the last page","type":"string"}},"required":["deliveries"],"type":"object"},"MessageDeliveryStatus":{"properties":{"createdAt":{"description":"Submission creation timestamp in epoch seconds","format":"int64","type":"integer"},"deliveryId":{"description":"The delivery id this submission was sent with, as returned by /send","type":"string"},"messageId":{"description":"ULID of the Sent copy this submission produced, or null when no Sent copy was kept","type":["string","null"]},"recipients":{"description":"Per-recipient delivery status","items":{"$ref":"#/components/schemas/RecipientDeliveryStatus"},"type":"array"},"sendAt":{"description":"UTC timestamp when message was sent or scheduled","type":"string"},"status":{"description":"Overall delivery status across all recipients. 'relayed' means the receiving mail system accepted the message; 'mixed' means at least one recipient failed while another did not","enum":["queued","relayed","delivered","failed","mixed"],"type":"string"},"submissionId":{"description":"Submission identifier (the JMAP EmailSubmission id)","type":"string"},"threadId":{"description":"Conversation thread identifier","type":["string","null"]}},"required":["deliveryId","submissionId","messageId","threadId","sendAt","status","recipients","createdAt"],"type":"object"},"MessageInvitation":{"properties":{"allDay":{"description":"True when DTSTART is a DATE; render the start as a UTC calendar date without a time","type":"boolean"},"attendeeCount":{"description":"Total number of attendees","type":"integer"},"attendees":{"description":"List of parsed attendees","items":{"$ref":"#/components/schemas/PimAttendee"},"type":"array"},"calendarId":{"description":"Calendar ID holding the stored copy, or null","type":["string","null"]},"canRespond":{"description":"True if the caller can submit an RSVP response","type":"boolean"},"component":{"description":"iCalendar component type","enum":["VEVENT","VTODO","VJOURNAL"],"type":["string","null"]},"dtend":{"description":"End timestamp in epoch seconds, or null","format":"int64","type":["integer","null"]},"dtstart":{"description":"Start timestamp in epoch seconds, or null","format":"int64","type":["integer","null"]},"found":{"description":"True if this event is already stored in a calendar","type":"boolean"},"href":{"description":"DAV resource path of the stored copy, or null","type":["string","null"]},"isOrganizer":{"description":"True if this mailbox is the organizer of the event","type":"boolean"},"location":{"description":"Event location","type":["string","null"]},"method":{"description":"iTIP method (REQUEST, CANCEL, REPLY), or null","type":["string","null"]},"myAddress":{"description":"Recipient address matching an attendee on this invite","type":["string","null"]},"myPartstat":{"description":"Caller's current reply status (ACCEPTED, DECLINED, TENTATIVE, NEEDS-ACTION)","type":["string","null"]},"organizer":{"description":"Organizer email address, or null","type":["string","null"]},"rrule":{"description":"Recurrence rule (RRULE), or null","type":["string","null"]},"section":{"description":"MIME section of the text/calendar part","type":"string"},"summary":{"description":"Event title or summary","type":["string","null"]},"uid":{"description":"Calendar event UID, or null","type":["string","null"]}},"required":["section","method","uid","component","summary","location","dtstart","dtend","allDay","rrule","organizer","attendees","attendeeCount","myAddress","myPartstat","isOrganizer","canRespond","found","calendarId","href"],"type":"object"},"MessageLabel":{"properties":{"deleted":{"description":"This membership's IMAP \\Deleted mark (set with `flagLabel` on PATCH, acted on by POST /labels/{label}/expunge). Always present; false when unmarked. Per label, so the same message can be marked in one folder and clean in another","type":"boolean"},"modseq":{"description":"RFC 7162 MODSEQ change sequence number","format":"int64","type":"integer"},"name":{"description":"Label name","type":"string"},"uid":{"description":"Message UID inside this label","format":"int64","type":"integer"},"uidValidity":{"description":"UID validity epoch of the label","format":"int64","type":"integer"}},"required":["name","uid","uidValidity","modseq","deleted"],"type":"object"},"MessageMeta":{"properties":{"auth":{"$ref":"#/components/schemas/MessageAuth"},"bcc":{"description":"Parsed Bcc header addresses for composed drafts, or null","items":{"$ref":"#/components/schemas/ContentAddress"},"type":["array","null"]},"blobGen":{"description":"Storage generation identifier","type":"string"},"blobHash":{"description":"SHA-256 hash of raw MIME content in storage","type":"string"},"cc":{"description":"Parsed Cc header addresses, or null if unparseable","items":{"$ref":"#/components/schemas/ContentAddress"},"type":["array","null"]},"deliveryMeta":{"additionalProperties":{},"description":"Inbound delivery audit metadata","type":["object","null"]},"deliveryState":{"anyOf":[{"enum":["queued","relayed","delivered","failed","mixed"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"What became of this message after it was SENT, for a message this mailbox sent: 'queued' (handed to the relay), 'relayed' (the receiving mail system accepted it — never 'read'), 'delivered' (committed to a local mailbox), 'failed', or 'mixed' (some recipients failed, others did not). Null for received mail, and for sent mail whose delivery record has aged out — render null as no indicator, never as a state. Per-recipient detail and the SMTP reply behind a failure are at /messages/{messageId}/delivery."},"envelopeFrom":{"description":"SMTP envelope sender address","type":"string"},"envelopeTo":{"description":"SMTP envelope recipient address","type":"string"},"flags":{"description":"System flags (seen, answered, flagged, draft, deleted)","items":{"type":"string"},"type":"array"},"from":{"description":"Parsed From header addresses, or null if unparseable","items":{"$ref":"#/components/schemas/ContentAddress"},"type":["array","null"]},"hasAttachment":{"description":"True if message has file attachments, null if not yet determined","type":["boolean","null"]},"id":{"description":"Unique message identifier (ULID)","type":"string"},"inReplyTo":{"description":"In-Reply-To header Message-ID, or null","type":["string","null"]},"keywords":{"description":"Custom JMAP keywords (e.g. $forwarded)","items":{"type":"string"},"type":"array"},"labels":{"description":"Labels attached to this message with per-label UIDs","items":{"$ref":"#/components/schemas/MessageLabel"},"type":"array"},"messageIdHeader":{"description":"Message-ID header value, or null","type":["string","null"]},"modseq":{"description":"Per-label MODSEQ (present in label UID listings)","format":"int64","type":"integer"},"receivedAt":{"description":"Timestamp when message was received by server in epoch seconds","format":"int64","type":"integer"},"referencesIds":{"description":"List of Message-IDs from References header","items":{"type":"string"},"type":"array"},"restoresTo":{"description":"Where a recovery would file this message, as label names. Present only when the message is recoverable: one carrying the Trash label (POST /messages/untrash), one carrying the Junk label with a recorded origin (POST /messages/unjunk), or one on the expunged tier (POST /messages/restore). A message in both Trash and Junk's records answers for Trash, the verb a client offers it first. Null otherwise, meaning the message is filed rather than recoverable. This is the effective destination including the Inbox fallback, not a raw snapshot, so a client can name it on a Put back or Not spam control without reimplementing the rule.","items":{"type":"string"},"type":["array","null"]},"sentAt":{"description":"Sent timestamp from Date header in epoch seconds, or null","format":"int64","type":["integer","null"]},"size":{"description":"Total message size in bytes","format":"int64","type":"integer"},"snippet":{"description":"Short plain-text preview of message body","type":["string","null"]},"subject":{"description":"Message subject line, or null","type":["string","null"]},"threadId":{"description":"Conversation thread identifier (ULID), or null","type":["string","null"]},"to":{"description":"Parsed To header addresses, or null if unparseable","items":{"$ref":"#/components/schemas/ContentAddress"},"type":["array","null"]},"uid":{"description":"Per-label UID (present in label UID listings)","format":"int64","type":"integer"}},"required":["id","labels","flags","keywords","envelopeFrom","envelopeTo","from","to","cc","bcc","subject","messageIdHeader","threadId","inReplyTo","referencesIds","sentAt","receivedAt","size","snippet","hasAttachment","blobHash","blobGen","deliveryMeta","auth","deliveryState"],"type":"object"},"MessageRestoreResult":{"properties":{"message":{"allOf":[{"$ref":"#/components/schemas/MessageMeta"},{"description":"Restored message metadata"}]},"restored":{"description":"True if message was restored from trash","type":"boolean"}},"required":["restored","message"],"type":"object"},"MessageSyncEntry":{"properties":{"blobHash":{"description":"Storage blob SHA-256 hash — what body caches key on","type":"string"},"flags":{"description":"System flags (seen, answered, flagged, draft, deleted)","items":{"type":"string"},"type":"array"},"keywords":{"description":"Custom keywords (e.g. $forwarded)","items":{"type":"string"},"type":"array"},"labels":{"description":"Per-label membership: name, UID in that label, MODSEQ, and that membership's \\Deleted","items":{"$ref":"#/components/schemas/MessageLabel"},"type":"array"},"receivedAt":{"description":"Server receive timestamp in epoch seconds","format":"int64","type":"integer"},"size":{"description":"Message size in bytes","format":"int64","type":"integer"}},"required":["labels","flags","keywords","blobHash","size","receivedAt"],"type":"object"},"MessageUpdateResult":{"anyOf":[{"$ref":"#/components/schemas/MessageUpdated"},{"$ref":"#/components/schemas/ExpungeNotice"}]},"MessageUpdated":{"properties":{"auth":{"$ref":"#/components/schemas/MessageAuth"},"bcc":{"description":"Parsed Bcc header addresses for composed drafts, or null","items":{"$ref":"#/components/schemas/ContentAddress"},"type":["array","null"]},"blobGen":{"description":"Storage generation identifier","type":"string"},"blobHash":{"description":"SHA-256 hash of raw MIME content in storage","type":"string"},"cc":{"description":"Parsed Cc header addresses, or null if unparseable","items":{"$ref":"#/components/schemas/ContentAddress"},"type":["array","null"]},"deliveryMeta":{"additionalProperties":{},"description":"Inbound delivery audit metadata","type":["object","null"]},"deliveryState":{"anyOf":[{"enum":["queued","relayed","delivered","failed","mixed"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"What became of this message after it was SENT, for a message this mailbox sent: 'queued' (handed to the relay), 'relayed' (the receiving mail system accepted it — never 'read'), 'delivered' (committed to a local mailbox), 'failed', or 'mixed' (some recipients failed, others did not). Null for received mail, and for sent mail whose delivery record has aged out — render null as no indicator, never as a state. Per-recipient detail and the SMTP reply behind a failure are at /messages/{messageId}/delivery."},"envelopeFrom":{"description":"SMTP envelope sender address","type":"string"},"envelopeTo":{"description":"SMTP envelope recipient address","type":"string"},"flags":{"description":"System flags (seen, answered, flagged, draft, deleted)","items":{"type":"string"},"type":"array"},"from":{"description":"Parsed From header addresses, or null if unparseable","items":{"$ref":"#/components/schemas/ContentAddress"},"type":["array","null"]},"hasAttachment":{"description":"True if message has file attachments, null if not yet determined","type":["boolean","null"]},"id":{"description":"Unique message identifier (ULID)","type":"string"},"inReplyTo":{"description":"In-Reply-To header Message-ID, or null","type":["string","null"]},"keywords":{"description":"Custom JMAP keywords (e.g. $forwarded)","items":{"type":"string"},"type":"array"},"labels":{"description":"Labels attached to this message with per-label UIDs","items":{"$ref":"#/components/schemas/MessageLabel"},"type":"array"},"labelsAdded":{"description":"Labels this write attached, including an Archive fallback under `orphans`","items":{"type":"string"},"type":"array"},"labelsRemoved":{"description":"Labels this write detached","items":{"type":"string"},"type":"array"},"messageIdHeader":{"description":"Message-ID header value, or null","type":["string","null"]},"modseq":{"description":"Per-label MODSEQ (present in label UID listings)","format":"int64","type":"integer"},"receivedAt":{"description":"Timestamp when message was received by server in epoch seconds","format":"int64","type":"integer"},"referencesIds":{"description":"List of Message-IDs from References header","items":{"type":"string"},"type":"array"},"restoresTo":{"description":"Where a recovery would file this message, as label names. Present only when the message is recoverable: one carrying the Trash label (POST /messages/untrash), one carrying the Junk label with a recorded origin (POST /messages/unjunk), or one on the expunged tier (POST /messages/restore). A message in both Trash and Junk's records answers for Trash, the verb a client offers it first. Null otherwise, meaning the message is filed rather than recoverable. This is the effective destination including the Inbox fallback, not a raw snapshot, so a client can name it on a Put back or Not spam control without reimplementing the rule.","items":{"type":"string"},"type":["array","null"]},"sentAt":{"description":"Sent timestamp from Date header in epoch seconds, or null","format":"int64","type":["integer","null"]},"size":{"description":"Total message size in bytes","format":"int64","type":"integer"},"snippet":{"description":"Short plain-text preview of message body","type":["string","null"]},"subject":{"description":"Message subject line, or null","type":["string","null"]},"threadId":{"description":"Conversation thread identifier (ULID), or null","type":["string","null"]},"to":{"description":"Parsed To header addresses, or null if unparseable","items":{"$ref":"#/components/schemas/ContentAddress"},"type":["array","null"]},"uid":{"description":"Per-label UID (present in label UID listings)","format":"int64","type":"integer"}},"required":["id","labels","flags","keywords","envelopeFrom","envelopeTo","from","to","cc","bcc","subject","messageIdHeader","threadId","inReplyTo","referencesIds","sentAt","receivedAt","size","snippet","hasAttachment","blobHash","blobGen","deliveryMeta","auth","deliveryState"],"type":"object"},"MessageWebhook":{"properties":{"createdAt":{"description":"When the webhook was first set (epoch seconds)","format":"int64","type":"integer"},"format":{"description":"The payload shape: parsed (decoded bodies and inlined attachments) or reference (headers plus a capability rawUrl)","enum":["parsed","reference"],"type":"string"},"hasSecret":{"description":"Whether each POST is signed (X-OpenEmail-Signature, HMAC-SHA-256 over the body); the secret itself is write-only","type":"boolean"},"updatedAt":{"description":"When it last changed (epoch seconds)","format":"int64","type":"integer"},"url":{"description":"Where each message that lands in this mailbox is POSTed (the incoming-email payload), however it got there: any of its addresses, a pattern or catch-all, a group, a forward, a delivery-status or platform notice, whether the mailbox keeps it or not","type":"string"}},"required":["url","format","hasSecret","createdAt","updatedAt"],"type":"object"},"MessageWebhookBody":{"additionalProperties":false,"properties":{"format":{"description":"The payload shape. Omit to keep (parsed for a new webhook); reference needs a deployment that mints capability URLs (400 webhook_format_unavailable)","enum":["parsed","reference"],"type":"string"},"secret":{"description":"HMAC signing secret, write-only. Omit to keep the stored one, a string to set or rotate it, null to clear it (unsigned)","maxLength":256,"minLength":1,"type":["string","null"]},"url":{"description":"HTTPS endpoint on a public host","format":"uri","type":"string"}},"required":["url"],"type":"object"},"MimeBatch":{"properties":{"mime":{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/MimeEntry"},{"type":"null"}]},"description":"Map of message ID to parsed MIME structures","type":"object"}},"required":["mime"],"type":"object"},"MimeEntry":{"properties":{"envelope":{"description":"Parsed IMAP ENVELOPE structure"},"structure":{"description":"Parsed IMAP BODYSTRUCTURE tree"},"ver":{"description":"MIME cache version","format":"int64","type":"integer"}},"required":["ver"],"type":"object"},"ObjectSchedulingLog":{"properties":{"entries":{"description":"Oldest first, the latest 500 at most. Kept 14 days like every scheduling log row; the SCHEDULE-STATUS on the event outlives them","items":{"properties":{"counterpart":{"description":"The recipient's address, lowercased","type":"string"},"createdAt":{"description":"When it was recorded, unix seconds","format":"int64","type":"integer"},"id":{"description":"Row ULID","type":"string"},"method":{"description":"iTIP METHOD this store sent: REQUEST, CANCEL or REPLY","type":"string"},"outcome":{"description":"delivered (written into a calendar on this platform), sent (handed to the relay), retryable (being retried), refused, failed (a remote server refused it after the relay took it) or skipped (never sent: a group or webhook address, one the organizer may not invite, a delegate's remote send, SCHEDULE-AGENT=CLIENT)","type":["string","null"]},"reason":{"description":"Why, when the outcome was not a delivery; for a remote failure, the remote server's reply","type":["string","null"]},"status":{"description":"The RFC 6638 SCHEDULE-STATUS this result stamped (1.0, 1.1, 1.2, 3.7, 3.8, 5.1, 5.2, 5.3), or null","type":["string","null"]}},"required":["id","method","counterpart","outcome","reason","status","createdAt"],"type":"object"},"type":"array"},"uid":{"description":"The event's UID","type":"string"}},"required":["uid","entries"],"type":"object"},"PasswordChanged":{"properties":{"changed":{"description":"Always true when password rotation succeeds","enum":[true],"type":"boolean"},"credentialId":{"description":"The credential ID whose password was rotated","type":"string"}},"required":["changed","credentialId"],"type":"object"},"Pattern":{"properties":{"aliasAddress":{"description":"Target alias pattern when destinationType='alias', otherwise null","type":["string","null"]},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"destinationType":{"description":"Destination type","enum":["mailbox","webhook","remote","alias"],"type":"string"},"domain":{"description":"Domain name this pattern applies to","type":"string"},"id":{"description":"Pattern routing rule ID","format":"int64","type":"integer"},"mailboxId":{"description":"Target mailbox ULID when destinationType='mailbox', otherwise null","type":["string","null"]},"paced":{"description":"True if inbound delivery to this pattern is rate-paced","type":"boolean"},"pattern":{"description":"Pattern wildcard match (e.g. support-*@example.com or *@example.com)","type":"string"},"priority":{"description":"Evaluation priority (higher values evaluate first)","type":"integer"},"remoteAddress":{"description":"Target remote email address when destinationType='remote', otherwise null","type":["string","null"]},"webhookFormat":{"description":"Payload format when destinationType='webhook': 'parsed' (the default — decoded bodies and inlined attachments) or 'reference' (headers plus rawUrl, no MIME walk). 'parsed' and inert on every other destination type","enum":["parsed","reference"],"type":"string"},"webhookUrl":{"description":"Target webhook URL when destinationType='webhook', otherwise null","type":["string","null"]}},"required":["id","domain","pattern","priority","destinationType","mailboxId","webhookUrl","webhookFormat","remoteAddress","aliasAddress","paced","createdAt"],"type":"object"},"PickupDispatch":{"description":"State of the last attempt to hand this source to the fetcher, read from the scheduler. Null when that read was not made (it failed, or the page exceeded the fan-out bound) — never to mean 'nothing happened', which is an object with a null outcome. ABSENT on the operator listing, which is a deliberately DO-free cross-tenant scan","properties":{"consecutiveFailures":{"description":"Dispatch attempts failed in a row; 0 once one is accepted","format":"int64","type":"integer"},"detail":{"description":"The refusal status, the transport error, the name of the blank var, or the receive hold's code — whichever the outcome implies","type":["string","null"]},"lastAttemptAt":{"description":"When the fetcher was last called, epoch ms, or null if never","format":"int64","type":["integer","null"]},"nextRunAt":{"description":"When the next attempt is armed for, epoch ms","format":"int64","type":["integer","null"]},"outcome":{"description":"dispatched = accepted; busy = a run was already in progress (also fine); rejected = the fetcher answered and said no; unreachable = no answer at all; decrypt_failed = the stored password would not decrypt (PICKUP_KEK); unconfigured = a required var is blank; receive_hold = the destination mailbox's receive hold is set (detail: receiving_paused or receiving_disabled), so nothing was collected, the source keeps its schedule and resumes once the hold is cleared. Null when nothing has been dispatched yet","enum":["dispatched","busy","rejected","unreachable","decrypt_failed","unconfigured","receive_hold"],"type":["string","null"]}},"required":["lastAttemptAt","outcome","detail","consecutiveFailures","nextRunAt"],"type":["object","null"]},"PickupRunResult":{"properties":{"status":{"description":"Trigger outcome status (e.g. 'scheduled')","type":"string"}},"required":["status"],"type":"object"},"PickupSource":{"properties":{"completedAt":{"description":"When an import completed, epoch seconds; null while it runs, and always in sync mode. A completed source is disabled and holds no password: re-enabling it needs the password again","format":"int64","type":["integer","null"]},"consecutiveFailures":{"description":"Number of consecutive failed polling attempts","format":"int64","type":"integer"},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"deleteAfterFetch":{"description":"True if messages should be deleted from remote server after fetching","type":"boolean"},"dispatch":{"$ref":"#/components/schemas/PickupDispatch"},"enabled":{"description":"True if automatic polling is enabled","type":"boolean"},"host":{"description":"Remote POP3 server hostname (e.g. 'pop.example.com')","type":"string"},"id":{"description":"Pickup source ULID","type":"string"},"importedTotal":{"description":"Messages this source has stored (replays excluded), counted as they arrive. ABSENT on the operator listing","format":"int64","type":"integer"},"intervalMinutes":{"description":"Polling interval in minutes","format":"int64","type":"integer"},"labelName":{"description":"Label (folder) fetched mail files into; null = INBOX. Created on first use if missing. An explicit destination is not spam-scored; a Sieve fileinto still wins; a blocked sender still files to Junk","type":["string","null"]},"lastError":{"description":"Error message from most recent failed run, or null","type":["string","null"]},"lastImportedCount":{"description":"Messages the fetcher uploaded on the most recent completed run (its report's uploadedCount). Null until a run has reported; 0 is a run that found nothing waiting","format":"int64","type":["integer","null"]},"lastOversizeCount":{"description":"Messages the fetcher left on the remote server on its most recent run because they are over the platform's message size limit; they are never imported and do not hold an import open. Null until a run has reported it","format":"int64","type":["integer","null"]},"lastRunAt":{"description":"Timestamp of most recent pickup attempt in epoch seconds, or null","format":"int64","type":["integer","null"]},"lastStatus":{"description":"Outcome status of most recent run, or null","enum":["ok","partial","auth_failed","error"],"type":["string","null"]},"mailboxId":{"description":"Destination mailbox ULID where fetched mail is deposited","type":"string"},"markRead":{"description":"True if every imported message lands read. False (the default): messages dated before the source was added — the backlog — land read, newer ones unread; POP3 itself carries no read state","type":"boolean"},"mode":{"description":"sync = keep collecting from this account for as long as the source exists. import = move off this account: the source completes itself once a run finds the remote mailbox drained and no new message has been stored for quietDays, then switches off and forgets the remote password","enum":["sync","import"],"type":"string"},"name":{"description":"User-assigned label for this remote account (e.g. 'Old Gmail'), or null","type":["string","null"]},"port":{"description":"Remote POP3 server port (e.g. 995 for TLS, 110 for STARTTLS)","format":"int64","type":"integer"},"quietDays":{"description":"Days without a newly stored message, after a drained run, that complete an import (1 to 90). Ignored in sync mode","format":"int64","type":"integer"},"quietSince":{"description":"When the quiet window last restarted (a message was stored, the source was re-enabled or switched to import), epoch seconds; null = since createdAt. ABSENT on the operator listing","format":"int64","type":["integer","null"]},"tls":{"description":"Transport security mode ('tls' or 'starttls')","enum":["tls","starttls"],"type":"string"},"username":{"description":"Remote POP3 account login username","type":"string"}},"required":["id","mailboxId","name","host","port","tls","username","intervalMinutes","deleteAfterFetch","labelName","markRead","enabled","lastRunAt","lastStatus","lastError","consecutiveFailures","lastImportedCount","createdAt","mode","quietDays","completedAt","lastOversizeCount"],"type":"object"},"PimAttendee":{"properties":{"cn":{"description":"Attendee display name","type":"string"},"email":{"description":"Attendee email address","type":"string"},"partstat":{"description":"Participation status (NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE)","type":"string"},"role":{"description":"Attendee role (REQ-PARTICIPANT, OPT-PARTICIPANT, CHAIR)","type":"string"},"rsvp":{"description":"True if attendee requested an RSVP reply","type":"boolean"}},"required":["email"],"type":"object"},"PimChangedRef":{"properties":{"etag":{"type":"string"},"href":{"type":"string"},"id":{"type":"string"},"uid":{"type":"string"}},"required":["href","etag","id","uid"],"type":"object"},"PimChanges":{"properties":{"changed":{"items":{"$ref":"#/components/schemas/PimChangedRef"},"type":"array"},"deleted":{"description":"Deleted (or renamed-away) hrefs","items":{"type":"string"},"type":"array"},"syncToken":{"description":"OPAQUE. Anchored at the last change reported when truncated","type":"string"},"truncated":{"description":"More changes remain; re-poll with the returned token (gateway maps to 507)","type":"boolean"}},"required":["syncToken","changed","deleted","truncated"],"type":"object"},"PimCollection":{"properties":{"color":{"description":"Hex color code (e.g. #3b82f6), or null","type":["string","null"]},"components":{"description":"Supported primary components, in VEVENT then VTODO order; null for addressbooks. Legacy mixed calendars may also retain journals or unparsed resources. Narrowing refuses with components_conflict and a count of incompatible live and restorable trashed objects.","items":{"enum":["VEVENT","VTODO"],"type":"string"},"maxItems":2,"minItems":1,"type":["array","null"]},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"description":{"description":"Collection description, or null","type":["string","null"]},"descriptionLang":{"description":"BCP 47 language tag (xml:lang) of the collection description, or null","type":["string","null"]},"displayName":{"description":"Display name of the calendar or addressbook, or null","type":["string","null"]},"id":{"description":"Collection ULID: stable across renames; the JMAP id","type":"string"},"kind":{"description":"Collection type ('calendar' or 'addressbook')","enum":["calendar","addressbook"],"type":"string"},"myPermission":{"description":"What the CALLING identity may do with this collection: 'owner' for its own, otherwise the granted level.","enum":["owner","read","read-write"],"type":"string"},"name":{"description":"URL path segment slug (e.g. 'work-calendar')","type":"string"},"objectCount":{"description":"Total number of events, tasks, or contacts in this collection","format":"int64","type":"integer"},"ownerAddress":{"description":"Primary address of the owning mailbox, or null when it has none","type":["string","null"]},"ownerIdentityId":{"description":"Identity ULID that owns this collection","type":"string"},"role":{"description":"Special role ('default', 'tasks'), or null","type":["string","null"]},"scheduleTransp":{"description":"RFC 6638 §9.1 CALDAV:schedule-calendar-transp — whether this calendar's objects contribute to the owner's free/busy. `transparent` excludes the whole calendar (a birthdays or subscribed-holidays feed); `opaque` is the default the RFC assumes when the property is absent. An addressbook always reports `opaque` and cannot be set otherwise: the property is defined for calendar collections, and the addressbook PATCH body does not carry it","enum":["opaque","transparent"],"type":"string"},"syncToken":{"description":"Opaque sync token for delta synchronization","type":"string"},"taskCounts":{"description":"Members that are tasks, split by the two `progress` buckets. Exact complements; events and contacts are in neither, so the pair need not sum to `objectCount`.","properties":{"active":{"description":"Tasks not completed or cancelled — what `?progress=active` lists","format":"int64","type":"integer"},"closed":{"description":"Tasks completed or cancelled — what `?progress=closed` lists","format":"int64","type":"integer"}},"required":["active","closed"],"type":"object"},"visibility":{"description":"Access visibility scope","enum":["private","shared","public"],"type":"string"}},"required":["id","kind","components","name","displayName","color","description","descriptionLang","visibility","role","scheduleTransp","syncToken","createdAt","objectCount","taskCounts","myPermission","ownerIdentityId","ownerAddress"],"type":"object"},"PimCollectionRestored":{"properties":{"collection":{"$ref":"#/components/schemas/PimCollection"},"objectsRestored":{"description":"Members that came back with it","format":"int64","type":"integer"},"reinvitesDropped":{"description":"Schedulable members past the per-restore bound: restored, but no REQUEST is sent for them","type":"integer"},"reinvitesScheduled":{"description":"Restored meetings offered to the scheduler; those this mailbox does not organize are skipped there, SEQUENCE untouched","type":"integer"}},"required":["collection","objectsRestored","reinvitesScheduled","reinvitesDropped"],"type":"object"},"PimImportItem":{"properties":{"error":{"description":"Error message if import failed","type":"string"},"etag":{"description":"ETag of the imported object","type":"string"},"href":{"description":"Resource path where object landed, or null if failed","type":["string","null"]},"status":{"description":"Import outcome for this object","enum":["created","replaced","failed"],"type":"string"},"uid":{"description":"Imported object UID","type":"string"}},"required":["uid","href","status"],"type":"object"},"PimImportResult":{"properties":{"createdCount":{"description":"Count of newly created objects","type":"integer"},"failedCount":{"description":"Count of items that failed to import","type":"integer"},"items":{"description":"List of import results per item","items":{"$ref":"#/components/schemas/PimImportItem"},"type":"array"},"replacedCount":{"description":"Count of existing objects replaced","type":"integer"},"syncToken":{"description":"Updated collection sync token","type":"string"}},"required":["items","createdCount","replacedCount","failedCount"],"type":"object"},"PimInstance":{"properties":{"component":{"description":"Standalone iCalendar VCALENDAR text for this occurrence","type":"string"},"end":{"description":"Occurrence end timestamp in epoch seconds","format":"int64","type":"integer"},"fbType":{"description":"What this occurrence contributes to a free/busy answer (RFC 4791 §7.10 and the owner's own PARTSTAT), or null for nothing. Present only with fbtype=true","enum":["BUSY","BUSY-TENTATIVE"],"type":["string","null"]},"ownerPartstat":{"description":"The collection owner's own PARTSTAT on this occurrence; present only with fbtype=true, null when they are not an attendee of it","type":["string","null"]},"recurrenceId":{"description":"Specific recurrence-ID timestamp in epoch seconds, or null","format":"int64","type":["integer","null"]},"scheduling":{"description":"Effective occurrence participants, including RANGE overrides; present with expand=true and fields=json. Missing statuses are not inherited from the master","properties":{"attendees":{"items":{"properties":{"email":{"description":"Calendar address with the mailto prefix removed","type":"string"},"name":{"type":"string"},"partstat":{"type":"string"},"scheduleStatus":{"description":"Server-owned SCHEDULE-STATUS on this participant","type":"string"}},"required":["email"],"type":"object"},"type":"array"},"organizer":{"properties":{"email":{"description":"Calendar address with the mailto prefix removed","type":"string"},"name":{"type":"string"},"partstat":{"type":"string"},"scheduleStatus":{"description":"Server-owned SCHEDULE-STATUS on this participant","type":"string"}},"required":["email"],"type":["object","null"]}},"required":["organizer","attendees"],"type":"object"},"start":{"description":"Occurrence start timestamp in epoch seconds","format":"int64","type":"integer"},"status":{"description":"Status for this occurrence","type":["string","null"]},"transp":{"description":"Time transparency for this occurrence","type":["string","null"]}},"required":["start","end","recurrenceId","transp","status"],"type":"object"},"PimInvitationStatus":{"properties":{"amOrganizer":{"description":"True if the current user is the organizer of this event","type":"boolean"},"calendarId":{"description":"ID of the calendar holding this event, or null","type":["string","null"]},"found":{"description":"True if this event is already saved in a calendar","type":"boolean"},"href":{"description":"DAV resource path of the stored event, or null","type":["string","null"]},"myAddress":{"description":"Email address of this mailbox listed as an attendee, or null","type":["string","null"]},"myPartstat":{"description":"Caller's current RSVP participation status (ACCEPTED, DECLINED, TENTATIVE), or null","type":["string","null"]},"organizer":{"description":"Organizer email address, or null","type":["string","null"]}},"required":["found","calendarId","href","myPartstat","myAddress","organizer","amOrganizer"],"type":"object"},"PimObjectJson":{"allOf":[{"$ref":"#/components/schemas/PimObjectMeta"},{"properties":{"content":{"description":"The wire text; present only when data is null","type":"string"},"data":{"additionalProperties":{},"description":"JSCalendar Event or Task (RFC 8984) or JSContact Card (RFC 9553); null when unmapped","type":["object","null"]},"writable":{"description":"False when the object converts TO JSON but cannot be converted back — display-only. The reader is more permissive than the writer (e.g. a VEVENT with no DTSTART reads fine and can never be written), so this says up front that an edit would be refused","type":"boolean"}},"required":["data","writable"],"type":"object"}]},"PimObjectMeta":{"properties":{"attendees":{"description":"List of parsed attendees, or null","items":{"$ref":"#/components/schemas/PimAttendee"},"type":["array","null"]},"component":{"description":"Main component type","enum":["VEVENT","VTODO","VJOURNAL","VCARD"],"type":["string","null"]},"contentType":{"description":"MIME content type (text/calendar or text/vcard)","type":"string"},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"dtend":{"description":"Event end timestamp in epoch seconds, or null","format":"int64","type":["integer","null"]},"dtstart":{"description":"Event start timestamp in epoch seconds, or null","format":"int64","type":["integer","null"]},"etag":{"description":"SHA-256 hash of object body (strong ETag)","type":"string"},"eventStatus":{"description":"Event status (CONFIRMED, TENTATIVE, CANCELLED), or null","type":["string","null"]},"href":{"description":"DAV resource path name (e.g. 'event-123.ics')","type":"string"},"id":{"description":"Object ULID","type":"string"},"organizer":{"description":"Organizer email address, or null","type":["string","null"]},"rrule":{"description":"Recurrence rule (RRULE string), or null","type":["string","null"]},"sequence":{"description":"iCalendar revision sequence number","type":"integer"},"size":{"description":"Object size in bytes","format":"int64","type":"integer"},"transp":{"description":"Time transparency (OPAQUE for busy, TRANSPARENT for free), or null","type":["string","null"]},"uid":{"description":"iCalendar or vCard UID","type":"string"},"updatedAt":{"description":"Last updated timestamp in epoch seconds","format":"int64","type":"integer"},"vcardEmail":{"description":"vCard primary email address, or null","type":["string","null"]},"vcardFn":{"description":"vCard full formatted name (FN), or null","type":["string","null"]},"vcardN":{"description":"vCard structured name (family;given;additional;prefix;suffix), or null","type":["string","null"]}},"required":["id","href","uid","etag","size","contentType","component","dtstart","dtend","rrule","organizer","attendees","sequence","eventStatus","transp","vcardFn","vcardEmail","vcardN","createdAt","updatedAt"],"type":"object"},"PimObjectPage":{"properties":{"nextCursor":{"description":"Present when more objects remain; pass back as ?cursor=","type":"string"},"objects":{"items":{"allOf":[{"$ref":"#/components/schemas/PimObjectMeta"},{"properties":{"content":{"description":"Absent when fields=meta, and under fields=json unless data is null","type":"string"},"data":{"additionalProperties":{},"description":"Present when fields=json","type":["object","null"]},"instances":{"items":{"$ref":"#/components/schemas/PimInstance"},"type":"array"}},"type":"object"}]},"type":"array"},"window":{"description":"The effective range actually answered, echoed on ranged queries","properties":{"clamped":{"description":"True when the asked-for range was narrowed to the cap","type":"boolean"},"end":{"format":"int64","type":"integer"},"start":{"format":"int64","type":"integer"}},"required":["start","end","clamped"],"type":"object"}},"required":["objects"],"type":"object"},"PimObjectRestored":{"properties":{"etag":{"description":"The live row's strong ETag: the stored one, or the re-invite's bumped body","type":"string"},"href":{"description":"DAV resource path name, unchanged","type":"string"},"id":{"description":"Object ULID, unchanged","type":"string"},"reinvited":{"description":"True when this mailbox organizes the event and a fresh REQUEST, SEQUENCE advanced by one, was scheduled to its attendees","type":"boolean"},"syncToken":{"description":"Updated collection sync token","type":"string"},"uid":{"type":"string"}},"required":["id","href","uid","etag","syncToken","reinvited"],"type":"object"},"PimPublicCollection":{"properties":{"category":{"description":"Public category tag, or null","type":["string","null"]},"collectionId":{"description":"Public collection ULID","type":"string"},"components":{"description":"Supported primary components, in VEVENT then VTODO order; null for addressbooks. Legacy mixed calendars may also retain journals or unparsed resources. Narrowing refuses with components_conflict and a count of incompatible live and restorable trashed objects.","items":{"enum":["VEVENT","VTODO"],"type":"string"},"maxItems":2,"minItems":1,"type":["array","null"]},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"description":{"description":"Public description, or null","type":["string","null"]},"displayName":{"description":"Public display name, or null","type":["string","null"]},"id":{"description":"Directory entry id: the handle POST /subscriptions takes","type":"string"},"kind":{"description":"Collection type ('calendar' or 'addressbook')","enum":["calendar","addressbook"],"type":"string"},"ownerIdentityId":{"description":"Identity ULID of the owner","type":"string"}},"required":["id","ownerIdentityId","collectionId","kind","components","displayName","description","category","createdAt"],"type":"object"},"PimPutResult":{"properties":{"created":{"description":"True if a new object was created (false if replaced)","type":"boolean"},"etag":{"description":"Strong ETag SHA-256 hash","type":"string"},"href":{"description":"DAV resource path name","type":"string"},"id":{"description":"Object ULID","type":"string"},"merged":{"description":"True when the difference reported by rewritten is other people's answers: a matching If-Schedule-Tag-Match had the server carry its own ATTENDEE state (PARTSTAT, RSVP, SCHEDULE-STATUS) for every attendee but the owner onto the new body (RFC 6638 §3.2.10.1)","type":"boolean"},"rewritten":{"description":"True when the stored bytes are not the bytes sent, whatever the cause: the VCALENDAR-level METHOD was dropped (RFC 4791 §4.1), SCHEDULE-FORCE-SEND was dropped (RFC 6638 §7.2), or attendee state was merged in (see merged). The etag returned is the stored body's, so re-read before relying on a cached copy — and a DAV gateway must withhold the strong ETag (RFC 4791 §5.3.4)","type":"boolean"},"syncToken":{"description":"Updated collection sync token","type":"string"},"unparsed":{"description":"True if stored object body could not be parsed into structured fields","type":"boolean"}},"required":["id","href","etag","created","syncToken"],"type":"object"},"PimRsvpResult":{"properties":{"calendarId":{"description":"Calendar collection ULID holding the event","type":"string"},"etag":{"description":"Updated ETag of the calendar object","type":"string"},"filed":{"description":"True if the event was newly added to the calendar","type":"boolean"},"href":{"description":"DAV resource path of the event","type":"string"},"myAddress":{"description":"Recipient email address for which this RSVP was recorded","type":"string"},"organizerUpdated":{"description":"True if local organizer event copy was updated directly","type":"boolean"},"partstat":{"description":"Recorded participation status (ACCEPTED, DECLINED, TENTATIVE)","enum":["ACCEPTED","DECLINED","TENTATIVE","NEEDS-ACTION"],"type":"string"},"replySent":{"description":"True if email reply was sent to remote organizer","type":"boolean"},"summary":{"description":"Event title/summary, or null","type":["string","null"]}},"required":["partstat","calendarId","href","myAddress","filed","etag","organizerUpdated","replySent","summary"],"type":"object"},"PimShare":{"properties":{"createdAt":{"format":"int64","type":"integer"},"permission":{"description":"Access permission level","enum":["read","read-write"],"type":"string"},"shareeAddress":{"description":"Primary email address of the sharee, or null for an address-less identity. Present so a sharing UI can name the grantee without a lookup per grant — the mirror of MailShare.granteeAddress","type":["string","null"]},"shareeIdentityId":{"description":"Identity ULID granted access","type":"string"}},"required":["shareeIdentityId","shareeAddress","permission","createdAt"],"type":"object"},"PimSharedWithMe":{"properties":{"collectionId":{"description":"Shared collection ULID","type":"string"},"color":{"description":"Hex color code, or null","type":["string","null"]},"components":{"description":"Supported primary components, in VEVENT then VTODO order; null for addressbooks. Legacy mixed calendars may also retain journals or unparsed resources. Narrowing refuses with components_conflict and a count of incompatible live and restorable trashed objects.","items":{"enum":["VEVENT","VTODO"],"type":"string"},"maxItems":2,"minItems":1,"type":["array","null"]},"createdAt":{"description":"Timestamp when share was created in epoch seconds","format":"int64","type":"integer"},"description":{"description":"Collection description, or null","type":["string","null"]},"descriptionLang":{"description":"BCP 47 language tag (xml:lang) of the collection description, or null","type":["string","null"]},"displayName":{"description":"Display name, or null","type":["string","null"]},"kind":{"description":"Collection type ('calendar' or 'addressbook')","enum":["calendar","addressbook"],"type":"string"},"name":{"description":"URL slug name","type":"string"},"objectCount":{"description":"Total number of events, tasks, or contacts in this collection","format":"int64","type":"integer"},"ownerAddress":{"description":"Primary email address of the owner, or null for an address-less identity. The mirror of SharedMailbox.ownerAddress: a \"shared with me\" list names WHO shared","type":["string","null"]},"ownerIdentityId":{"description":"Identity ULID of the collection owner","type":"string"},"permission":{"description":"Access permission level","enum":["read","read-write"],"type":"string"},"scheduleTransp":{"description":"RFC 6638 §9.1 CALDAV:schedule-calendar-transp, as the OWNER set it — whether this calendar counts toward their free/busy","enum":["opaque","transparent"],"type":"string"},"syncToken":{"description":"Current sync token","type":"string"},"taskCounts":{"description":"Members that are tasks, split by the two `progress` buckets. Exact complements; events and contacts are in neither, so the pair need not sum to `objectCount`.","properties":{"active":{"description":"Tasks not completed or cancelled — what `?progress=active` lists","format":"int64","type":"integer"},"closed":{"description":"Tasks completed or cancelled — what `?progress=closed` lists","format":"int64","type":"integer"}},"required":["active","closed"],"type":"object"}},"required":["ownerIdentityId","ownerAddress","collectionId","permission","kind","components","name","displayName","color","description","descriptionLang","scheduleTransp","syncToken","createdAt","objectCount","taskCounts"],"type":"object"},"PimToken":{"properties":{"accessCount":{"description":"Number of times this feed token has been accessed","format":"int64","type":"integer"},"collectionId":{"description":"Target collection ULID","type":"string"},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"expiresAt":{"description":"Expiration timestamp in epoch seconds, or null for no expiry","format":"int64","type":["integer","null"]},"id":{"description":"Token identifier","type":"string"},"kind":{"description":"Collection type ('calendar' or 'addressbook')","enum":["calendar","addressbook"],"type":"string"},"label":{"description":"User label for this feed token, or null","type":["string","null"]},"lastAccessedAt":{"description":"Timestamp of most recent access in epoch seconds, or null","format":"int64","type":["integer","null"]}},"required":["id","collectionId","kind","label","expiresAt","accessCount","lastAccessedAt","createdAt"],"type":"object"},"PimTokenCreated":{"allOf":[{"$ref":"#/components/schemas/PimToken"},{"properties":{"token":{"description":"Plaintext feed token (returned once only at creation)","type":"string"},"url":{"description":"Public unauthenticated iCalendar feed URL","type":"string"}},"required":["token","url"],"type":"object"}]},"PimTrashPurged":{"properties":{"objectsPurged":{"description":"Trashed objects removed for good","format":"int64","type":"integer"},"purged":{"enum":[true],"type":"boolean"}},"required":["purged","objectsPurged"],"type":"object"},"PimTrashedCollection":{"properties":{"color":{"type":["string","null"]},"components":{"description":"Supported primary components, in VEVENT then VTODO order; null for addressbooks. Legacy mixed calendars may also retain journals or unparsed resources. Narrowing refuses with components_conflict and a count of incompatible live and restorable trashed objects.","items":{"enum":["VEVENT","VTODO"],"type":"string"},"maxItems":2,"minItems":1,"type":["array","null"]},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"description":{"type":["string","null"]},"displayName":{"type":["string","null"]},"expiresAt":{"description":"When the purge duty removes it and its members for good, in epoch seconds","format":"int64","type":"integer"},"id":{"description":"Collection ULID: the same id it had, and will have again","type":"string"},"kind":{"description":"Collection type ('calendar' or 'addressbook')","enum":["calendar","addressbook"],"type":"string"},"name":{"description":"URL slug it had; a restore refuses (409 name_taken) while a live collection holds it","type":"string"},"objectCount":{"description":"Members that went with it, and come back with it","format":"int64","type":"integer"},"role":{"description":"Special role ('tasks'), or null; the default collection cannot be deleted","type":["string","null"]},"trashedAt":{"description":"When it was deleted, in epoch seconds","format":"int64","type":"integer"}},"required":["id","kind","components","name","displayName","color","description","role","createdAt","objectCount","trashedAt","expiresAt"],"type":"object"},"PimTrashedObject":{"allOf":[{"$ref":"#/components/schemas/PimObjectMeta"},{"properties":{"expiresAt":{"description":"When the purge duty removes it for good, in epoch seconds (fourteen days after trashedAt)","format":"int64","type":"integer"},"trashedAt":{"description":"When it was deleted, in epoch seconds","format":"int64","type":"integer"}},"required":["trashedAt","expiresAt"],"type":"object"}]},"PimTrashedObjectPage":{"properties":{"nextCursor":{"description":"Present when more remain; pass back as ?cursor=","type":"string"},"objects":{"description":"Newest deletion first","items":{"$ref":"#/components/schemas/PimTrashedObject"},"type":"array"}},"required":["objects"],"type":"object"},"Prefs":{"properties":{"prefs":{"additionalProperties":{},"description":"User client preferences JSON key-value map. Opaque to the server with one exception: notifyNewClient: false turns off the mail the platform sends when a client reaches the identity from a new location (the identity.client.new event to the tenant's hooks is unaffected)","type":"object"},"version":{"description":"Monotonic version counter for optimistic concurrency control (CAS)","format":"int64","type":"integer"}},"required":["prefs","version"],"type":"object"},"PublicBranding":{"properties":{"brandName":{"description":"Public display name shown on login screens, or null","type":["string","null"]},"logoType":{"description":"Media type of the public logo, or null","type":["string","null"]},"logoUpdatedAt":{"description":"Timestamp when public logo was last updated in epoch seconds","format":"int64","type":["integer","null"]}},"required":["brandName","logoType","logoUpdatedAt"],"type":"object"},"PublicBrandingByHost":{"allOf":[{"$ref":"#/components/schemas/PublicBranding"},{"properties":{"domain":{"description":"Canonical domain name resolved from the hostname","type":"string"}},"required":["domain"],"type":"object"}]},"PushSubscription":{"properties":{"createdAt":{"description":"Creation time in epoch seconds","format":"int64","type":"integer"},"deviceClientId":{"description":"Client-chosen device identifier. Re-registering the same one replaces the previous subscription (and resets verification: new keys mean a new handshake)","type":"string"},"expires":{"description":"Expiry in epoch seconds, capped 30 days out. Extend with PATCH before it lapses; an expired subscription is invisible and the device re-registers","format":"int64","type":"integer"},"id":{"description":"Subscription ULID","type":"string"},"types":{"description":"Type names that wake this device, or null for all types","items":{"type":"string"},"type":["array","null"]},"verified":{"description":"False until the device echoes back the verificationCode delivered by the handshake push. Nothing is ever pushed to an unverified subscription","type":"boolean"}},"required":["id","deviceClientId","verified","expires","types","createdAt"],"type":"object"},"PushSubscriptionPage":{"properties":{"subscriptions":{"description":"Only the subscriptions registered by the CALLING credential","items":{"$ref":"#/components/schemas/PushSubscription"},"type":"array"},"vapidPublicKey":{"description":"The server's VAPID application key (base64url, uncompressed P-256 point). Pass it as applicationServerKey when calling PushManager.subscribe. Null when Web Push is not configured on this deployment, in which case POST refuses with web_push_not_configured","type":["string","null"]}},"required":["vapidPublicKey","subscriptions"],"type":"object"},"PutMailShareBody":{"properties":{"labelScope":{"description":"Restrict the grant to specific FOLDERS, by name. Send `null` to share the whole mailbox — and note that OMITTING the field is a different request from sending null; see below.\n\nA folder-scoped grant may carry up to `lrswit` — everything `read_write` means. Within the granted folders it reads, marks read/unread privately, changes flags, files messages in, and trashes them. Two letters are rejected, naming themselves: `e` (permanently delete trashed messages), because a purge is irreversible and reaches messages filed in folders the holder cannot see; and `k` (create and rename folders), because a folder they created would not be inside their own grant.\n\n**What trashing means on a folder-scoped grant.** It removes the message from the folders they were granted — never from the mailbox. A message filed elsewhere as well stays exactly where you put it and simply leaves their view; a message that was only in their folders goes to Trash, where your normal 14-day undo reaches it. They can never permanently delete anything.\n\n**Filing in.** They must name one of their folders; there is no default (yours is INBOX, which is usually not one of theirs). Your filters do not run on what they file — a rule of yours could otherwise move it somewhere they cannot see, forward it, or send an auto-reply in your name.\n\nThe grant follows the folder if it is RENAMED, and does not follow the name: deleting a folder and creating a new one with the same name does not revive an old grant. The grant follows the folder into DELETION too: deleting a folder removes it from every grant that names it, and a grant left naming no folders is revoked outright — a share dies with its last folder. An empty list is rejected on WRITE — revoke with DELETE instead.\n\n**Omitting the field and sending `null` are different requests.** On a grant that is already folder-scoped, omitting `labelScope` PRESERVES the existing folders and changes only the rights; sending an explicit `null` is what widens the grant to the whole mailbox. Widening is a deliberate act, so it has to be spelled — otherwise any client that does not know about folder scopes (IMAP `SETACL` among them, since the ACL wire format cannot express one) would silently replace a one-folder grant with a whole-store grant, and drop the `lrs` cap along with it.\n\nOn READ an empty list can appear only on the OWNER's listing, and only as residue: it means every folder the grant named has since been deleted and the automatic revocation above could not run. Such a grant is dead — it matches nothing and gives access to nothing — and the owner's listing shows it so you can see it and remove it, while the shared-with-me listing never lists it. It is the one value you cannot send back unchanged: send DELETE, which is what a grant scoped to no folders already means.\n\nA folder-scoped viewer sees only these folders, and only their messages: listings, searches and conversations are all confined to them. Reachable over IMAP, the REST API and JMAP alike.\n\n**Changing a grant signs their clients out of sync.** Sync tokens on a folder-scoped grant are tied to the grant itself, so editing the folders or the rights makes every outstanding token stale exactly once: their clients re-list and carry on. Any live event stream they hold is closed at the same moment, so a narrowed grant takes effect immediately rather than when their connection happens to drop.\n\nAt most 32 folders may be named in one grant.","items":{"type":"string"},"maxItems":32,"type":["array","null"]},"rights":{"description":"What the person you shared with is allowed to do, written as a set of letters in any order (stored and returned in the canonical order below).\n\n| Letter | Allows |\n| --- | --- |\n| `l` | See the mailbox in folder listings |\n| `r` | Read messages |\n| `s` | Change the read/unread mark — each person's own, never shared |\n| `w` | Change other flags, such as flagged or answered |\n| `i` | Put messages in: append, copy in, move in |\n| `k` | Create and rename labels |\n| `t` | Move messages to trash |\n| `e` | Permanently delete trashed messages |\n\nInstead of letters you may send a preset name, which is usually what you want: `read` or `read_only` (= `lrs`), `read_write` (= `lrswit`), or `admin` / `full` (= `lrswikte`, everything a grant can carry). Hyphenated spellings work too (`read-only`, `read-write`).\n\n**Three things no grant ever allows.** It does not allow sending mail as the mailbox owner. It does not allow deleting labels (`x`): that sends every message whose only label it was to the trash, which the owner may do with their own credentials but not hand to a delegate. And it does not allow re-sharing (`a`, RFC 4314's administration right): only the mailbox owner and account administrators can change who has access. Asking for `x` or `a` is refused with the letters named (an invalid_rights error), never quietly dropped.\n\nLetters outside the table (RFC 4314's `p`, and the obsolete `c` and `d`) are rejected and named back to you rather than ignored, so a grant never quietly means less than what you asked for. A repeated letter is rejected for the same reason.","type":"string"}},"required":["rights"],"type":"object"},"QueryMessagesUpdateResult":{"properties":{"archived":{"description":"Messages whose last label this patch removed that fell back to the Archive label instead of being expunged. Unlike `expunged`, this is a SUBSET of `updated`, not an alternative to it: an archived message was still updated, so `examined` equals `updated + unchanged + expunged + failed` and adding `archived` to `updated` double counts. Only present when the patch carried `orphans: \"archive\"`.","type":"integer"},"examined":{"description":"Messages the query selected in this call","type":"integer"},"expunged":{"description":"Messages whose last label this patch removed: moved to the Recently-deleted tier, restorable until purge. Counted here rather than in `updated`.","type":"integer"},"failed":{"description":"Per-message refusals. Not an error: the rest of the call applied.","type":"integer"},"idMax":{"description":"The ULID ceiling this call worked under. Send it back UNCHANGED on a continuation: it is what keeps the selection the one the search showed, and re-resolving it would let mail that arrived since drift into the gesture.","type":"string"},"nextAfter":{"description":"Continuation cursor: call again with `after` set to this, the same `idMax`, the same filter and the same patch. `null` means the selection is drained. There is no `remaining` count — counting what is left of a filter is an aggregate over the whole filtered set on every call. Measure progress against the search's own `total`.","type":["string","null"]},"unchanged":{"description":"Selected messages the patch provably would not have changed, so they were skipped","type":"integer"},"updated":{"description":"Messages the patch changed","type":"integer"}},"required":["idMax","examined","updated","unchanged","expunged","archived","failed","nextAfter"],"type":"object"},"RecipientAccepted":{"properties":{"accepted":{"description":"True if recipient address is accepted for delivery","enum":[true],"type":"boolean"}},"required":["accepted"],"type":"object"},"RecipientDeliveryStatus":{"properties":{"at":{"description":"Epoch seconds at which this recipient reached the status above. Absent while the leg is still queued, in which case the submission's createdAt is its time","format":"int64","type":"integer"},"delivered":{"description":"Raw JMAP RFC 8621 delivered status ('queued', 'yes', 'no', 'unknown')","type":"string"},"displayed":{"description":"Raw JMAP RFC 8621 displayed status ('unknown', 'yes')","type":"string"},"email":{"description":"Recipient email address","type":"string"},"mxHost":{"description":"Hostname of the mail exchanger that answered for this recipient, or the reporting MTA of a bounce that arrived later. Absent for legs that never spoke SMTP","type":"string"},"smtpReply":{"description":"The reply the receiving mail system gave for this recipient, verbatim where it spoke SMTP ('250 2.0.0 Ok: queued as 4bXyz', '550 5.1.1 no such user'), synthesized in the same grammar for a leg that did not (local delivery, a policy refusal here)","type":"string"},"status":{"description":"Delivery status for this recipient","enum":["queued","relayed","delivered","failed"],"type":"string"}},"required":["email","status","delivered"],"type":"object"},"RecoveryAddressDeleted":{"properties":{"deleted":{"description":"True if an address was removed by this call","type":"boolean"}},"required":["deleted"],"type":"object"},"RecoveryAddressPending":{"properties":{"address":{"description":"The pending address, masked","type":"string"},"expiresAt":{"description":"Epoch seconds after which the confirmation code is dead and the address must be set again","format":"int64","type":"integer"},"sameAccount":{"description":"True if this address routes to another mailbox in the SAME account, so a single compromise or a single outage can take both. Allowed, and worth warning about","type":"boolean"},"state":{"description":"Pending is never a reset target","enum":["pending"],"type":"string"}},"required":["address","state","sameAccount","expiresAt"],"type":"object"},"RecoveryAddressVerified":{"properties":{"address":{"description":"The verified address, masked","type":"string"},"state":{"enum":["verified"],"type":"string"},"usableAfter":{"description":"Epoch seconds until which this address may receive notices but not drive a reset; null when it is usable immediately","format":"int64","type":["integer","null"]}},"required":["address","state","usableAfter"],"type":"object"},"RecoveryCodesIssued":{"properties":{"codes":{"description":"The plaintext codes, shown exactly once. Only their SHA-256 hashes are stored","items":{"type":"string"},"type":"array"},"issuedAt":{"description":"Issue timestamp in epoch seconds","format":"int64","type":"integer"}},"required":["codes","issuedAt"],"type":"object"},"RecoveryCompleted":{"properties":{"appPasswordsRevoked":{"description":"Non-expiring app passwords revoked. Zero unless the caller asked for it","type":"integer"},"created":{"description":"True when the mailbox had no password credential and the reset established one","type":"boolean"},"credentialIds":{"description":"Every password credential now carrying the new secret","items":{"type":"string"},"type":"array"},"mailboxId":{"description":"The identity whose password was reset","type":"string"},"recoveryAddressVerified":{"description":"Present on the invitation branch only (§XVII): true when the nominated address was promoted to this mailbox's verified recovery address in the same act. False when the account's policy is admin_only, which means the address was used once as a delivery destination and never stored. That is the one outcome the redeeming user could not otherwise discover, since it turns on a tenant policy they have never heard of","type":"boolean"},"reset":{"description":"The password was set","enum":[true],"type":"boolean"},"sessionsRevoked":{"description":"Expiring credentials revoked by the reset (browser sessions and other dated credentials)","type":"integer"},"usernames":{"description":"Every username those credentials answer to. More than one means two logins now share this password, which the frontend must say out loud","items":{"type":"string"},"type":"array"}},"required":["reset","mailboxId","credentialIds","usernames","sessionsRevoked","appPasswordsRevoked","created"],"type":"object"},"RecoveryInvitationSent":{"properties":{"address":{"description":"The nominated address, masked","type":"string"},"expiresAt":{"description":"Epoch seconds at which the mailed code stops working","format":"int64","type":"integer"},"kind":{"description":"invitation: the mailbox had no password credential, so the mailed code SETS one and verifies the address in the same act. nomination: it already had one, so the mailed code is an ordinary 24h confirmation code that sets nothing and can only be spent from the mailbox's own session","enum":["invitation","nomination"],"type":"string"},"retained":{"description":"True if the address was stored as this mailbox's pending recovery address. False when the account policy is admin_only: the address was used once as a delivery destination and never stored","type":"boolean"}},"required":["kind","address","expiresAt","retained"],"type":"object"},"RecoveryPolicy":{"properties":{"policy":{"description":"self_service: mailbox users may recover their own password. admin_only: existing codes and addresses are kept and refused, and resets come from an admin","enum":["self_service","admin_only"],"type":"string"}},"required":["policy"],"type":"object"},"RecoveryStatus":{"properties":{"address":{"description":"Verified recovery address, masked (j••@ex•••.com), or null if none is verified","type":["string","null"]},"addressPlaintext":{"description":"The unmasked verified address. Present for system principals only","type":["string","null"]},"codesLockedUntil":{"description":"Epoch seconds until code submission is refused after repeated wrong codes, or null","format":"int64","type":["integer","null"]},"codesRemaining":{"description":"Unspent recovery codes. Zero means either none were ever issued or all are spent","type":"integer"},"invitation":{"description":"An outstanding provisioning invitation, or null. This IS the idempotency answer for POST /identities/:id/invitation (§XVII.5): a caller that lost its create response asks whether one is outstanding rather than holding an idempotency key, because an invitation is never re-sent automatically and a repeat is always a deliberate second call. Consumed and expired both read as null","properties":{"createdAt":{"description":"Epoch seconds at which it was sent","format":"int64","type":"integer"},"expiresAt":{"description":"Epoch seconds at which the invitation code stops working","format":"int64","type":"integer"}},"required":["expiresAt","createdAt"],"type":["object","null"]},"pending":{"description":"A typed, unconfirmed address, masked, or null. Reported ALONGSIDE `state` because §II.3 allows both at once (replacing does not disarm: the old address keeps working until the new one confirms), so a settings screen has to be able to show a change in flight without implying the old one has stopped","type":["string","null"]},"policy":{"description":"The account's recovery policy. admin_only keeps existing rows and refuses their use","enum":["self_service","admin_only"],"type":"string"},"state":{"description":"Address state: none, pending (typed, unconfirmed, never a reset target), or verified. `verified` wins when BOTH exist, because that is the address a reset would use","enum":["none","pending","verified"],"type":"string"},"usableAfter":{"description":"Epoch seconds until which a newly verified address may receive notices but not drive a reset (the 72h cooldown); null when nothing is waiting","format":"int64","type":["integer","null"]}},"required":["address","state","pending","usableAfter","codesRemaining","codesLockedUntil","policy","invitation"],"type":"object"},"RenamedResult":{"properties":{"renamed":{"description":"True if the label was successfully renamed","type":"boolean"}},"required":["renamed"],"type":"object"},"ReplyContext":{"properties":{"from":{"description":"Suggested sending address: the one the newest message reached this mailbox at, or was sent from when it is our own. Not re-checked against routing; the reply route uses it only while it still routes to this mailbox","type":["string","null"]},"inReplyTo":{"description":"Message-ID to set as In-Reply-To header","type":["string","null"]},"inboundSourceId":{"description":"Message ULID being replied to (null if newest message is outbound)","type":["string","null"]},"references":{"description":"List of Message-IDs for References header","items":{"type":"string"},"type":"array"},"subject":{"description":"Suggested normalized reply subject line","type":["string","null"]},"to":{"description":"Suggested recipient email address string","type":["string","null"]}},"required":["inReplyTo","references","subject","to","from","inboundSourceId"],"type":"object"},"RequestBreakdownRow":{"properties":{"bytesOut":{"description":"Total response bytes sent for these requests","format":"int64","type":"integer"},"count":{"description":"Total number of API requests matching this breakdown","format":"int64","type":"integer"},"kind":{"description":"Operation kind ('read', 'write', 'exempt')","type":"string"},"principal":{"description":"Authentication principal type ('system', 'account', 'mailbox', 'none')","type":"string"},"resource":{"description":"Resource category ('mail', 'calendar', 'contacts', 'directory', 'account', 'auth', 'other')","type":"string"},"surface":{"description":"API interface surface ('rest', 'jmap', 'dav', 'gateway', 'webmail', 'console', 'mcp')","type":"string"}},"required":["resource","kind","principal","surface","count","bytesOut"],"type":"object"},"RequestsSeriesPoint":{"properties":{"bucket":{"description":"Time bucket start, UTC `YYYY-MM-DD HH:MM:SS`: the same label, width and alignment the traffic aggregate gives the bucket for the same range","type":"string"},"calls":{"description":"Estimated API calls in this bucket: one per HTTP request (refusals, 401s and unmatched paths included) plus one per JMAP method call, successes and failures alike","format":"int64","type":"integer"}},"required":["bucket","calls"],"type":"object"},"Retention":{"properties":{"accountRetentionDays":{"description":"The owning account's default window (null = none)","type":["integer","null"]},"minDays":{"description":"The platform floor (RETENTION_MIN_DAYS): no window may be shorter","type":"integer"},"nextRunAt":{"description":"Epoch seconds at which the oldest live message becomes due under the window in force — the duty's next scheduled wake; null when no window is in force or nothing is live","format":"int64","type":["integer","null"]},"oldestReceivedAt":{"description":"Arrival time (epoch seconds) of the oldest live message, or null on an empty mailbox","format":"int64","type":["integer","null"]},"ownRetentionDays":{"description":"The mailbox's own window (null = none set; the account default applies if any)","type":["integer","null"]},"previews":{"description":"What each previewed window would expunge: the windows named by ?days=, else the window in force (one entry), else empty","items":{"$ref":"#/components/schemas/RetentionPreview"},"type":"array"},"retentionDays":{"description":"The window in force: the mailbox's own, else the account default, else null (off)","type":["integer","null"]},"source":{"description":"Where the window in force came from: the mailbox's own setting, the account default, or none","enum":["own","account","none"],"type":"string"}},"required":["retentionDays","source","ownRetentionDays","accountRetentionDays","minDays","oldestReceivedAt","nextRunAt","previews"],"type":"object"},"RetentionPreview":{"properties":{"bytes":{"description":"Their stored size in bytes (quota keeps counting them until the trash purge)","format":"int64","type":"integer"},"days":{"description":"The window previewed, in days","type":"integer"},"messages":{"description":"Live messages older than the window — what the duty would expunge","format":"int64","type":"integer"}},"required":["days","messages","bytes"],"type":"object"},"RevokedResult":{"properties":{"revoked":{"description":"True if the key or credential was successfully revoked","type":"boolean"}},"required":["revoked"],"type":"object"},"Route":{"properties":{"address":{"description":"Inbound email address (e.g. user@example.com)","type":"string"},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"destinationType":{"description":"Destination type","enum":["mailbox","webhook","remote","group"],"type":"string"},"domain":{"description":"Domain part of the route address","type":"string"},"mailboxId":{"description":"Target mailbox ULID when destinationType='mailbox', otherwise null","type":["string","null"]},"memberCount":{"description":"Count of members in this group route","type":"integer"},"paced":{"description":"True if inbound delivery to this route is rate-paced","type":"boolean"},"personaMailboxId":{"description":"Group routes only: the ULID of the group's PERSONA — the address-less mailbox that keeps the group's archive (a copy of every message the group admits) and holds the credential that may send as the group address. Read it with GET /identities/:id (which reports groupAddress back). Null only while the group's delete is in flight","type":["string","null"]},"posting":{"description":"Group posting policy (open = anyone may post, members = only members may post)","enum":["open","members"],"type":"string"},"remoteAddress":{"description":"Where this address forwards a copy: the destination address when destinationType='remote', otherwise the forward TAP — an address that receives a copy alongside the destination. Null when neither is set","type":["string","null"]},"webhookFormat":{"anyOf":[{"enum":["parsed","reference"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"Payload format for the webhook named by webhookUrl: 'parsed' (the default — decoded bodies and inlined attachments) or 'reference' (headers plus rawUrl, no MIME walk). Null when this address carries no webhook"},"webhookUrl":{"description":"Target webhook URL or tap webhook URL, otherwise null","type":["string","null"]}},"required":["address","domain","destinationType","mailboxId","webhookUrl","webhookFormat","remoteAddress","paced","createdAt"],"type":"object"},"RouteMember":{"properties":{"address":{"description":"Group route address","type":"string"},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"memberAddress":{"description":"Member recipient email address","type":"string"}},"required":["address","memberAddress","createdAt"],"type":"object"},"RouteMemberBatchResult":{"properties":{"addedCount":{"description":"Number of new members added","type":"integer"},"duplicateCount":{"description":"Number of duplicate members skipped","type":"integer"}},"required":["addedCount","duplicateCount"],"type":"object"},"RouteMemberRef":{"properties":{"address":{"description":"Group route address","type":"string"},"memberAddress":{"description":"Member recipient email address","type":"string"}},"required":["address","memberAddress"],"type":"object"},"RuleAction":{"oneOf":[{"additionalProperties":false,"properties":{"keepInInbox":{"default":false,"description":"Also leave the message in the Inbox. A bare `fileinto` CANCELS Sieve's implicit keep, so the default — false — is what every rule written before this field already did: file into the label and nowhere else. True compiles to `fileinto :copy`, which preserves the keep.","type":"boolean"},"label":{"maxLength":255,"minLength":1,"type":"string"},"type":{"enum":["fileInto"],"type":"string"}},"required":["type","label"],"type":"object"},{"additionalProperties":false,"properties":{"flag":{"enum":["seen","answered","flagged"],"type":"string"},"type":{"enum":["addFlag"],"type":"string"}},"required":["type","flag"],"type":"object"},{"additionalProperties":false,"properties":{"keepCopy":{"default":false,"type":"boolean"},"to":{"maxLength":320,"type":"string"},"type":{"enum":["redirect"],"type":"string"}},"required":["type","to"],"type":"object"},{"additionalProperties":false,"properties":{"type":{"enum":["discard"],"type":"string"}},"required":["type"],"type":"object"}]},"RuleCondition":{"oneOf":[{"additionalProperties":false,"properties":{"field":{"enum":["from","to","cc","toOrCc"],"type":"string"},"not":{"default":false,"description":"Invert this condition","type":"boolean"},"op":{"enum":["contains","is","matches","regex","exists"],"type":"string"},"value":{"maxLength":1024,"minLength":0,"type":"string"}},"required":["field","op"],"type":"object"},{"additionalProperties":false,"properties":{"field":{"enum":["subject","listId"],"type":"string"},"not":{"default":false,"description":"Invert this condition","type":"boolean"},"op":{"enum":["contains","is","matches","regex","exists"],"type":"string"},"value":{"maxLength":1024,"minLength":0,"type":"string"}},"required":["field","op"],"type":"object"},{"additionalProperties":false,"properties":{"field":{"enum":["header"],"type":"string"},"header":{"maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9-]+$","type":"string"},"not":{"default":false,"description":"Invert this condition","type":"boolean"},"op":{"enum":["contains","is","matches","regex","exists"],"type":"string"},"value":{"maxLength":1024,"minLength":0,"type":"string"}},"required":["field","header","op"],"type":"object"},{"additionalProperties":false,"properties":{"field":{"enum":["body"],"type":"string"},"not":{"default":false,"description":"Invert this condition","type":"boolean"},"op":{"enum":["contains"],"type":"string"},"value":{"maxLength":1024,"minLength":1,"type":"string"}},"required":["field","op","value"],"type":"object"},{"additionalProperties":false,"properties":{"field":{"enum":["size"],"type":"string"},"not":{"default":false,"description":"Invert this condition","type":"boolean"},"op":{"enum":["over","under"],"type":"string"},"value":{"format":"int64","maximum":2147483647,"minimum":0,"type":"integer"}},"required":["field","op","value"],"type":"object"}]},"RulesDocument":{"additionalProperties":false,"properties":{"rules":{"items":{"$ref":"#/components/schemas/FilterRule"},"maxItems":100,"type":"array"}},"required":["rules"],"type":"object"},"ScheduledLegResult":{"properties":{"address":{"description":"Recipient email address","type":"string"},"deliveryId":{"description":"Delivery attempt identifier","type":"string"},"error":{"description":"Error message if sending failed","type":"string"},"list":{"description":"On an address-list refusal: the sender's list that decided","type":"string"},"pattern":{"description":"On an address-list refusal: the entry that decided (`*@*` for a block-all)","type":"string"},"source":{"description":"On 'recipient_not_permitted' or 'recipient_not_verified': which of the sender's own policies refused it, as on `SendRecipientResult`","enum":["permitted_recipients","address_list","verified_recipients"],"type":"string"},"status":{"description":"Delivery status ('delivered', 'queued', 'failed')","type":"string"}},"required":["address","status","deliveryId"],"type":"object"},"ScheduledSend":{"properties":{"attempts":{"description":"Number of delivery attempts made","type":"integer"},"createdAt":{"description":"Creation timestamp in epoch seconds","format":"int64","type":"integer"},"deferrals":{"description":"Number of deferrals encountered","type":"integer"},"deliveryId":{"description":"Idempotency key for this submission","type":"string"},"error":{"description":"Error reason if sending failed or was canceled, or null","type":["string","null"]},"finishedAt":{"description":"Completion timestamp in epoch seconds, or null if pending","format":"int64","type":["integer","null"]},"messageId":{"description":"Draft message ULID scheduled for sending","type":"string"},"recipients":{"description":"List of target recipient email addresses","items":{"type":"string"},"type":"array"},"releaseAt":{"description":"Actual scheduled release time in epoch seconds","format":"int64","type":"integer"},"result":{"description":"Per-recipient delivery outcomes, or null if pending","items":{"$ref":"#/components/schemas/ScheduledLegResult"},"type":["array","null"]},"scheduleId":{"description":"Scheduled send ULID","type":"string"},"sendAt":{"description":"Requested send time in epoch seconds","format":"int64","type":"integer"},"state":{"description":"Current scheduling status","enum":["pending","releasing","sent","failed","canceled"],"type":"string"},"threadId":{"description":"Associated conversation thread ID, or null","type":["string","null"]}},"required":["scheduleId","deliveryId","messageId","threadId","sendAt","releaseAt","state","recipients","attempts","deferrals","createdAt","finishedAt","result","error"],"type":"object"},"SchedulingInboxPage":{"properties":{"entries":{"description":"Newest first. Refusals are listed too: an arrival that was declined is exactly what somebody asks about when they say they never got the invitation","items":{"properties":{"consumedAt":{"description":"When the client DELETEd the entry, unix seconds; null while pending","format":"int64","type":["integer","null"]},"counterpart":{"description":"The sender's address, lowercased. Empty when unknown","type":"string"},"createdAt":{"description":"When it arrived, unix seconds","format":"int64","type":"integer"},"direction":{"description":"Always inbound on this surface","enum":["inbound"],"type":"string"},"id":{"description":"Row ULID","type":"string"},"method":{"description":"iTIP METHOD: REQUEST, CANCEL or REPLY","type":"string"},"outcome":{"description":"What became of it — `applied`, or the refusal's name","type":["string","null"]},"pending":{"description":"An Inbox MEMBER (RFC 6638 §4): the message is held for the client to GET and has not been consumed. False for a refusal, an oversized message, or an entry already DELETEd","type":"boolean"},"reason":{"description":"Why, where the outcome needs one","type":["string","null"]},"size":{"description":"Bytes of the held message, null when none is held","type":["integer","null"]},"status":{"description":"Unused inbound; the RFC 6638 code is outbound-only","type":["string","null"]},"uid":{"description":"The scheduling object's UID","type":"string"}},"required":["id","uid","direction","method","counterpart","outcome","reason","status","createdAt","pending","size","consumedAt"],"type":"object"},"type":"array"}},"required":["entries"],"type":"object"},"SemanticCoverage":{"properties":{"complete":{"description":"True once every message at or above `since` is embedded (no backfill in flight, nothing owed). False while a backfill or catch-up chain is still running — results are partial meanwhile","type":"boolean"},"since":{"description":"The earliest arrival time (epoch seconds) semantic results can cover — the backfill floor; 0 = the whole store. Mail received before it is lexically searchable only. Lower it with PATCH /identities/:id { semanticFloor }","format":"int64","type":["integer","null"]}},"required":["since","complete"],"type":"object"},"SemanticSearchResult":{"properties":{"coverage":{"$ref":"#/components/schemas/SemanticCoverage"},"fused":{"description":"True when the lexical (BM25) ranking was fused in by reciprocal rank (hybrid): the default, and FORCED whenever a DO-side filter such as `label` is given, because the semantic candidate list is bounded at 100 before that filter and a narrow scope would otherwise starve","type":"boolean"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"},"results":{"items":{"$ref":"#/components/schemas/MessageMeta"},"type":"array"},"scoped":{"description":"Present when a post-filter (`label`) narrowed a candidate list that is bounded at 100 before filtering: the semantic half may have missed matches that rank past 100; the fused lexical half is what keeps the answer honest","enum":["candidate-bounded"],"type":"string"},"snippets":{"description":"Highlighted excerpts (snippet=true)","items":{"$ref":"#/components/schemas/EmailSearchSnippet"},"type":"array"}},"required":["results","coverage","fused"],"type":"object"},"SendAsAddresses":{"properties":{"addresses":{"description":"Primary address first, then the mailbox's other routed addresses on domains that may send, then wildcards; at most 100 addresses. Not exhaustive: an address a narrower catch-all pattern routes here is sendable without being listed","items":{"properties":{"email":{"description":"A lowercased address this mailbox may send as, or `*@domain` where a catch-all lets it send as any address on that domain (RFC 8621 §6's wildcard)","type":"string"},"subaddressing":{"description":"Whether `local+tag@domain` forms of this address are sendable too. Always false on a wildcard, which already covers every local part","type":"boolean"}},"required":["email","subaddressing"],"type":"object"},"type":"array"}},"required":["addresses"],"type":"object"},"SendRecipientResult":{"properties":{"address":{"description":"Recipient email address","type":"string"},"deliveryId":{"description":"Unique delivery attempt ID for this recipient","type":"string"},"error":{"description":"Error reason code if status is failed (e.g. 'over_quota', 'receiving_disabled'). 'sending_paused' and 'sending_disabled' mean a hold on the sender (mailbox, domain or account) landed while the request was running: recipients already handled keep their status and the rest are refused. 'sending_paused' is temporary: retry with the same X-Delivery-Id once the hold lifts. 'sending_disabled' is permanent. 'recipient_not_verified' is permanent for this recipient alone: the account is not yet vetted, so it may send only to its verified recipients (its own domains, and outside addresses whose owners confirmed them), and this one is neither; or the recipient is a hosted address that forwards for an account not yet vetted, to a target that is not one of that account's verified recipients.","type":"string"},"list":{"description":"On an address-list refusal: the sender's list that decided","type":"string"},"pattern":{"description":"On an address-list refusal: the entry that decided (`*@*` for a block-all)","type":"string"},"source":{"description":"On 'recipient_not_permitted': which of the sender's own policies refused it, the identity or credential allowlist, or the sender's outbound address lists. On 'recipient_not_verified': 'verified_recipients', the verified-recipients rule of the sending account, or of the account the recipient forwards for","enum":["permitted_recipients","address_list","verified_recipients"],"type":"string"},"status":{"description":"Outcome status for this recipient","enum":["delivered","queued","filtered","failed"],"type":"string"}},"required":["address","status","deliveryId"],"type":"object"},"SendResult":{"properties":{"deliveryId":{"description":"Master submission delivery ID","type":"string"},"recipients":{"description":"Outcome status per recipient","items":{"$ref":"#/components/schemas/SendRecipientResult"},"type":"array"},"sentCopy":{"description":"Status of saving copy to Sent folder ('saved', 'duplicate', 'over_quota')","enum":["saved","duplicate","over_quota"],"type":"string"},"sentThreadId":{"description":"Conversation thread ID of the saved sent message","type":["string","null"]}},"required":["deliveryId","recipients"],"type":"object"},"SendState":{"properties":{"canSend":{"description":"True if this mailbox may send from its primary address now: the answer `/auth/verify` gives a login typed as that address","type":"boolean"},"sendHold":{"description":"Why canSend is false, present only then, with `/auth/verify`'s values: 'unverified' = the domain's send records were never published (publish DNS), 'receive_only' = the domain is configured to receive here and send through another provider, 'paused' = a reversible hold at some scope (mailbox, account or domain), 'disabled' = a permanent stop, or a mailbox that cannot send at all. Unlike `/send-usage`'s `sendHold`, which is the mailbox's own switch only, this is the fold across every scope. Advisory; the submission gate is the authority. Treat an unrecognized value as permanent","enum":["disabled","paused","unverified","receive_only"],"type":"string"}},"required":["canSend"],"type":"object"},"SendUsage":{"properties":{"burstWindowSeconds":{"description":"Width of one burst bucket in seconds (3600); the burst figures cover two of them","format":"int64","type":"integer"},"messages":{"description":"Number of distinct messages sent in the rolling 24-hour window, plus each accepted list post whose fan-out is still being delivered: the count the daily limit is checked against","format":"int64","type":"integer"},"messagesHour":{"description":"Distinct messages in the BURST window — the current hourly bucket plus the previous one, so a burst stays visible for up to an hour after it ended","format":"int64","type":"integer"},"msgsPerDay":{"description":"Configured daily message limit (null = unlimited or unenforced)","format":"int64","type":["integer","null"]},"msgsPerHour":{"description":"Configured hourly (burst) message limit (null = unlimited or unenforced)","format":"int64","type":["integer","null"]},"rcptsPerDay":{"description":"Configured daily recipient limit (null = unlimited or unenforced)","format":"int64","type":["integer","null"]},"rcptsPerHour":{"description":"Configured hourly (burst) recipient limit (null = unlimited or unenforced)","format":"int64","type":["integer","null"]},"recipients":{"description":"Total recipient count sent to in the rolling 24-hour window, plus the recipients an accepted list post still holds for its fan-out: the count the daily limit is checked against","format":"int64","type":"integer"},"recipientsHour":{"description":"Recipients in the BURST window (current + previous hourly bucket)","format":"int64","type":"integer"},"sendHold":{"anyOf":[{"enum":["disabled","paused"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"The mailbox's own hold: 'disabled' = permanent stop, 'paused' = reversible hold, null = neither"},"windowSeconds":{"description":"Duration of the rate-limit window in seconds (e.g. 86400 for 24h)","format":"int64","type":"integer"}},"required":["messages","recipients","msgsPerDay","rcptsPerDay","messagesHour","recipientsHour","msgsPerHour","rcptsPerHour","sendHold","windowSeconds","burstWindowSeconds"],"type":"object"},"SenderCheck":{"properties":{"allowed":{"enum":[true],"type":"boolean"}},"required":["allowed"],"type":"object"},"SharedMailbox":{"properties":{"createdAt":{"description":"When the grant was first created, in epoch seconds","format":"int64","type":"integer"},"granteeIdentityId":{"description":"ULID of the identity the grant belongs to; always the caller's own identity","type":"string"},"labelScope":{"description":"Restrict the grant to specific FOLDERS, by name. Send `null` to share the whole mailbox — and note that OMITTING the field is a different request from sending null; see below.\n\nA folder-scoped grant may carry up to `lrswit` — everything `read_write` means. Within the granted folders it reads, marks read/unread privately, changes flags, files messages in, and trashes them. Two letters are rejected, naming themselves: `e` (permanently delete trashed messages), because a purge is irreversible and reaches messages filed in folders the holder cannot see; and `k` (create and rename folders), because a folder they created would not be inside their own grant.\n\n**What trashing means on a folder-scoped grant.** It removes the message from the folders they were granted — never from the mailbox. A message filed elsewhere as well stays exactly where you put it and simply leaves their view; a message that was only in their folders goes to Trash, where your normal 14-day undo reaches it. They can never permanently delete anything.\n\n**Filing in.** They must name one of their folders; there is no default (yours is INBOX, which is usually not one of theirs). Your filters do not run on what they file — a rule of yours could otherwise move it somewhere they cannot see, forward it, or send an auto-reply in your name.\n\nThe grant follows the folder if it is RENAMED, and does not follow the name: deleting a folder and creating a new one with the same name does not revive an old grant. The grant follows the folder into DELETION too: deleting a folder removes it from every grant that names it, and a grant left naming no folders is revoked outright — a share dies with its last folder. An empty list is rejected on WRITE — revoke with DELETE instead.\n\n**Omitting the field and sending `null` are different requests.** On a grant that is already folder-scoped, omitting `labelScope` PRESERVES the existing folders and changes only the rights; sending an explicit `null` is what widens the grant to the whole mailbox. Widening is a deliberate act, so it has to be spelled — otherwise any client that does not know about folder scopes (IMAP `SETACL` among them, since the ACL wire format cannot express one) would silently replace a one-folder grant with a whole-store grant, and drop the `lrs` cap along with it.\n\nOn READ an empty list can appear only on the OWNER's listing, and only as residue: it means every folder the grant named has since been deleted and the automatic revocation above could not run. Such a grant is dead — it matches nothing and gives access to nothing — and the owner's listing shows it so you can see it and remove it, while the shared-with-me listing never lists it. It is the one value you cannot send back unchanged: send DELETE, which is what a grant scoped to no folders already means.\n\nA folder-scoped viewer sees only these folders, and only their messages: listings, searches and conversations are all confined to them. Reachable over IMAP, the REST API and JMAP alike.\n\n**Changing a grant signs their clients out of sync.** Sync tokens on a folder-scoped grant are tied to the grant itself, so editing the folders or the rights makes every outstanding token stale exactly once: their clients re-list and carry on. Any live event stream they hold is closed at the same moment, so a narrowed grant takes effect immediately rather than when their connection happens to drop.\n\nAbsent when the request passed `labelScope=false`, when the grant fell past the per-request folder-name render bound, or when the owner's store could not be reached to resolve names. Never an empty list here.","items":{"type":"string"},"type":["array","null"]},"mailboxId":{"description":"ULID of the shared mailbox — the store to address when reading it","type":"string"},"ownerAddress":{"description":"Primary email address of the mailbox owner, or null if the owner has none. Intended as the display name for the shared mailbox; fall back to the ULID when null","type":["string","null"]},"rights":{"description":"What the person you shared with is allowed to do, written as a set of letters in any order (stored and returned in the canonical order below).\n\n| Letter | Allows |\n| --- | --- |\n| `l` | See the mailbox in folder listings |\n| `r` | Read messages |\n| `s` | Change the read/unread mark — each person's own, never shared |\n| `w` | Change other flags, such as flagged or answered |\n| `i` | Put messages in: append, copy in, move in |\n| `k` | Create and rename labels |\n| `t` | Move messages to trash |\n| `e` | Permanently delete trashed messages |\n\nInstead of letters you may send a preset name, which is usually what you want: `read` or `read_only` (= `lrs`), `read_write` (= `lrswit`), or `admin` / `full` (= `lrswikte`, everything a grant can carry). Hyphenated spellings work too (`read-only`, `read-write`).\n\n**Three things no grant ever allows.** It does not allow sending mail as the mailbox owner. It does not allow deleting labels (`x`): that sends every message whose only label it was to the trash, which the owner may do with their own credentials but not hand to a delegate. And it does not allow re-sharing (`a`, RFC 4314's administration right): only the mailbox owner and account administrators can change who has access. Asking for `x` or `a` is refused with the letters named (an invalid_rights error), never quietly dropped.\n\nLetters outside the table (RFC 4314's `p`, and the obsolete `c` and `d`) are rejected and named back to you rather than ignored, so a grant never quietly means less than what you asked for. A repeated letter is rejected for the same reason.","type":"string"}},"required":["mailboxId","granteeIdentityId","ownerAddress","rights","createdAt"],"type":"object"},"SieveActivated":{"properties":{"active":{"description":"True indicating the script is now active","type":"boolean"},"name":{"description":"Name of the activated script","type":"string"}},"required":["name","active"],"type":"object"},"SieveActiveName":{"properties":{"name":{"description":"Name of currently active script, or null if none is active","type":["string","null"]}},"required":["name"],"type":"object"},"SieveCapabilities":{"properties":{"implementation":{"description":"Sieve engine implementation identifier","type":"string"},"maxScriptSize":{"description":"Maximum script size in bytes","format":"int64","type":"integer"},"maxScripts":{"description":"Maximum allowed scripts per mailbox","format":"int64","type":"integer"},"sieve":{"description":"List of supported Sieve capability extensions","items":{"type":"string"},"type":"array"}},"required":["implementation","sieve","maxScripts","maxScriptSize"],"type":"object"},"SieveCheckResult":{"properties":{"col":{"description":"Column number of syntax error","type":"integer"},"line":{"description":"Line number of syntax error","type":"integer"},"message":{"description":"Error message if script compilation failed","type":"string"},"valid":{"description":"True if the Sieve script compiled without syntax errors","type":"boolean"}},"required":["valid"],"type":"object"},"SieveDeactivated":{"properties":{"active":{"description":"False indicating no script is active","type":"boolean"}},"required":["active"],"type":"object"},"SieveDeleted":{"properties":{"deleted":{"description":"True if script was deleted","type":"boolean"},"name":{"description":"Name of the deleted script","type":"string"}},"required":["name","deleted"],"type":"object"},"SievePutResult":{"properties":{"created":{"description":"True if a new script was created (false if replaced)","type":"boolean"},"name":{"description":"Script name","type":"string"},"stored":{"description":"True if script was stored successfully","type":"boolean"}},"required":["name","stored","created"],"type":"object"},"SieveRenamed":{"properties":{"name":{"description":"New script name","type":"string"},"renamed":{"description":"True if script was renamed","type":"boolean"}},"required":["name","renamed"],"type":"object"},"SieveScript":{"properties":{"active":{"description":"True if this script is currently active for filtering","type":"boolean"},"name":{"description":"Script name (e.g. 'myscript')","type":"string"},"updatedAt":{"description":"Timestamp when script was last updated in epoch seconds","format":"int64","type":"integer"}},"required":["name","active","updatedAt"],"type":"object"},"SieveScriptBody":{"properties":{"active":{"description":"True if this script is currently active","type":"boolean"},"name":{"description":"Script name","type":"string"},"script":{"description":"Sieve script source code text","type":"string"},"updatedAt":{"description":"Last updated timestamp in epoch seconds","format":"int64","type":"integer"}},"required":["name","script","active","updatedAt"],"type":"object"},"SimilarMessagesResult":{"properties":{"coverage":{"$ref":"#/components/schemas/SemanticCoverage"},"results":{"description":"Nearest messages by meaning, most similar first; the message itself is excluded","items":{"$ref":"#/components/schemas/MessageMeta"},"type":"array"}},"required":["results","coverage"],"type":"object"},"Suppression":{"properties":{"accountId":{"description":"Sending account whose complaint blocks this recipient; absent for a deployment-global block","type":"string"},"address":{"description":"Normalized (lowercased) recipient email address","type":"string"},"detail":{"description":"Diagnostic error message or feedback detail from the bounce or complaint report","type":["string","null"]},"eventCount":{"description":"Total number of bounce or complaint events recorded for this address","format":"int64","type":"integer"},"firstEventAt":{"description":"Timestamp of first suppression event in epoch seconds","format":"int64","type":"integer"},"lastEventAt":{"description":"Timestamp of most recent suppression event in epoch seconds","format":"int64","type":"integer"},"reason":{"description":"Reason for suppression ('complaint' from FBL report, or 'hard_bounce' from MTA)","enum":["complaint","hard_bounce"],"type":"string"},"sourceDeliveryId":{"description":"Delivery ID that triggered this suppression, or null","type":["string","null"]}},"required":["address","reason","detail","sourceDeliveryId","eventCount","firstEventAt","lastEventAt"],"type":"object"},"SuppressionList":{"properties":{"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"},"suppressions":{"items":{"$ref":"#/components/schemas/Suppression"},"type":"array"}},"required":["suppressions"],"type":"object"},"ThreadListItem":{"properties":{"exemplar":{"allOf":[{"$ref":"#/components/schemas/MessageMeta"},{"description":"The conversation's list-row face: the newest live member THAT MATCHED THIS LISTING'S FILTER, or the newest live member when no filter was given. Matching means the same member that qualified the thread — the `label` and the flag filters together — so ?label=INBOX faces the row with the newest Inbox member and not with your own Sent reply, and ?label=INBOX&notFlags=seen faces it with the unread Inbox message that put the row on screen. This is JMAP's rule for Email/query with collapseThreads. Position is a different question and stays conversation-wide: see lastReceivedAt."}]},"flaggedCount":{"description":"Flagged (starred) live messages in this conversation, over the same population as messageCount. Read this and not exemplar's `flagged` flag to decide whether a row shows a star: a star on any other member is otherwise invisible from the list, and so cannot be cleared from it. To clear them all, PATCH /messages with `threadIds` and `flagsClear: [\"flagged\"]`. Not viewer-relative, unlike unseenCount: only `seen` is a per-viewer overlay.","format":"int64","type":"integer"},"labels":{"description":"Distinct label names across this conversation's live members, ordered by sort_order then name. Excludes the members the row excludes: those in Trash or Junk outside their own views, and those carrying an excludeRoles role. Limited to the viewer's granted labels.","items":{"type":"string"},"type":"array"},"lastReceivedAt":{"description":"When this conversation last had activity, in epoch seconds — the newest live member's arrival, ANYWHERE in the thread, which is also what the listing sorts by. May be newer than exemplar.receivedAt: the position is conversation-wide, the exemplar is folder-relative (see exemplar).","format":"int64","type":"integer"},"messageCount":{"description":"Live messages in this conversation, across every label — not just the one filtered by. Matches what GET /threads/{threadId} returns, so a row's count agrees with the conversation a client then renders.","format":"int64","type":"integer"},"participants":{"description":"Distinct senders in the conversation, oldest first, deduplicated by address — the \"Carol, Alice, Bob\" line a conversation row shows, which the exemplar alone cannot supply. Conversation-wide like messageCount, so an Inbox row for a thread you replied to lists you as well. Bounded and capped at 8 entries: read from the conversation's opener plus its 20 newest live members, so a long thread reports who started it and who is still in it, and elides the middle. Scoped and filtered like the rest of the row (Trash and Junk members hidden outside their own views), so the Trash view of a conversation lists the people in its trashed half.","items":{"$ref":"#/components/schemas/ThreadParticipant"},"type":"array"},"threadId":{"description":"Conversation thread ULID identifier","type":"string"},"unseenCount":{"description":"Unread live messages in this conversation, over the same population as messageCount. Read this and not exemplar's `seen` flag to decide whether a row is unread: the exemplar is one member and may be read while older ones are not.","format":"int64","type":"integer"}},"required":["threadId","messageCount","unseenCount","flaggedCount","lastReceivedAt","exemplar","participants","labels"],"type":"object"},"ThreadParticipant":{"description":"One sender in the conversation; name is null when the From header carried no display name","properties":{"email":{"description":"Email address","type":"string"},"name":{"description":"Display name or personal name, or null","type":["string","null"]}},"required":["name","email"],"type":"object"},"ThreadView":{"properties":{"canonicalThreadId":{"description":"Canonical thread ID if requested ID was merged","type":"string"},"messageCount":{"description":"Total count of messages in this conversation","format":"int64","type":"integer"},"messages":{"description":"List of messages in this thread in chronological order","items":{"$ref":"#/components/schemas/MessageMeta"},"type":"array"},"nextCursor":{"description":"Pagination cursor for next page of messages","type":"string"},"replyContext":{"anyOf":[{"$ref":"#/components/schemas/ReplyContext"},{"type":"null"}],"description":"Pre-computed context for replying to this thread"},"threadId":{"description":"Canonical conversation thread identifier (ULID)","type":"string"}},"required":["threadId","messages","messageCount","replyContext"],"type":"object"},"TrafficEvent":{"properties":{"attempt":{"description":"Delivery retry attempt number, or null","type":["integer","null"]},"blobHash":{"description":"Storage blob SHA-256 hash, or null","type":["string","null"]},"deliveryId":{"description":"Delivery ID identifier, or null","type":["string","null"]},"detail":{"description":"Diagnostic detail or error message, or null","type":["string","null"]},"envelopeFrom":{"description":"SMTP envelope sender address, or null","type":["string","null"]},"envelopeTo":{"description":"SMTP envelope recipient address, or null","type":["string","null"]},"eventTime":{"description":"Event timestamp in epoch seconds","format":"int64","type":"integer"},"mailboxId":{"description":"Associated mailbox ULID, or null","type":["string","null"]},"matchedBy":{"description":"Route ID or rule that handled the message, or null","type":["string","null"]},"messageId":{"description":"Internal message ULID, or null","type":["string","null"]},"messageIdHeader":{"description":"RFC 5322 Message-ID header, or null","type":["string","null"]},"originalAddress":{"description":"Original recipient before alias expansion, or null","type":["string","null"]},"outcome":{"description":"Result outcome ('delivered', 'rejected', 'tempfail', 'bounced')","type":"string"},"response":{"description":"Remote SMTP server response line, or null","type":["string","null"]},"routeKind":{"description":"Route kind ('mailbox', 'forward', 'pipe', 'discard'), or null","type":["string","null"]},"routeTarget":{"description":"Route target destination address or mailbox ID, or null","type":["string","null"]},"size":{"description":"Message size in bytes, or null","format":"int64","type":["integer","null"]},"source":{"description":"Event source component ('inbound', 'outbound', 'relay', 'imap')","type":"string"},"subject":{"description":"Message subject line, or null","type":["string","null"]},"template":{"description":"The prepared email this message was sent from, or null for any other mail. Present on each recipient's admission row and on every relay attempt after it; filter on it with `template`.","properties":{"lang":{"description":"The language the message went out in, or null if the row did not record one","type":["string","null"]},"slug":{"description":"The template's slug within the account","type":"string"}},"required":["slug","lang"],"type":["object","null"]}},"required":["eventTime","source","outcome","detail","deliveryId","envelopeFrom","envelopeTo","originalAddress","matchedBy","routeKind","routeTarget","mailboxId","messageId","messageIdHeader","subject","size","blobHash","attempt","response","template"],"type":"object"},"TrafficRow":{"properties":{"bytes":{"description":"Total message payload size in bytes in this bucket","format":"int64","type":"integer"},"events":{"description":"Total number of events in this bucket","format":"int64","type":"integer"},"outcome":{"description":"Delivery or operation outcome (e.g. 'delivered', 'relayed', 'bounced')","type":"string"},"routeKind":{"description":"Routing match kind ('exact', 'pattern', 'catchall', 'system')","type":"string"}},"required":["outcome","routeKind","events","bytes"],"type":"object"},"TrafficSeriesPoint":{"properties":{"bucket":{"description":"Time bucket start timestamp ISO string","type":"string"},"byOutcome":{"additionalProperties":{"format":"int64","type":"integer"},"description":"Breakdown of event counts keyed by outcome","type":"object"},"bytes":{"description":"Total traffic bytes in this time bucket","format":"int64","type":"integer"},"bytesIn":{"description":"Bytes received in this time bucket, by the rule daily usage counts `inboundBytes` by: each copy that reached a hosted address (stored, or filtered by its rules) and each admission to a webhook or forward route. A subset of `bytes`, sampled like it, and not deduped by delivery as the daily ledger is","format":"int64","type":"integer"},"bytesOut":{"description":"Bytes sent in this time bucket, by the rule daily usage counts `outboundBytes` by: each recipient leg of a send, hosted or external, counted when the send was accepted (on the relay's success, for days before usage counted at acceptance). A forward's bytes are in neither this nor `bytesIn`, so this is not the bytes of `outbound`","format":"int64","type":"integer"},"events":{"description":"Total traffic events in this time bucket","format":"int64","type":"integer"},"forwarded":{"description":"The inbound-driven SUBSET of `outbound` (never a third direction): mail that left because a route was configured rather than because anyone submitted it. Bounded by the per-domain forwarding budget, billed on its own axis (forwardedMessages), and spends no send allowance","format":"int64","type":"integer"},"inbound":{"description":"Messages received in this time bucket, one per copy, by the rule daily usage counts `inboundDeliveries` by: each copy that reached a hosted address (from outside, as a group member, or from a hosted sender), was filtered by its rules, or was admitted to a webhook or forward route. Deferrals, refusals, duplicates, uploads, imports and Sent copies are not counted. Sampled, and not deduped by delivery as the daily ledger is","format":"int64","type":"integer"},"outbound":{"description":"Recipient legs sent in this time bucket, one per recipient, by the rule daily usage counts `outboundRecipients` by (counted when the send was accepted, or on the relay's success for days before usage counted at acceptance), plus each target a forward reached (`forwarded`). Deferrals and retries are not counted again. Sampled, and not deduped by delivery as the daily ledger is","format":"int64","type":"integer"}},"required":["bucket","events","bytes","inbound","outbound","forwarded","bytesIn","bytesOut"],"type":"object"},"UploadResult":{"properties":{"blobId":{"description":"Opaque upload id (u_…); pass it as an attachment's blobId, or to JMAP as a blobId","type":"string"},"expiresAt":{"description":"Epoch seconds after which the upload is treated as gone — reference it before then","format":"int64","type":"integer"},"size":{"description":"Stored byte length","format":"int64","type":"integer"},"type":{"description":"The media type recorded for the blob (echoes the request Content-Type)","type":"string"}},"required":["blobId","size","type","expiresAt"],"type":"object"},"UsageDay":{"properties":{"calendarObjects":{"description":"Total calendar events and tasks stored, or null","format":"int64","type":["integer","null"]},"closedAt":{"description":"Timestamp when the day's metrics were finalized and closed in epoch seconds, or null","format":"int64","type":["integer","null"]},"contactObjects":{"description":"Total address book contacts stored, or null","format":"int64","type":["integer","null"]},"day":{"description":"UTC date string in YYYY-MM-DD format","type":"string"},"estimated":{"description":"True if storage numbers are estimated or carried forward","type":"boolean"},"eventsPushedImap":{"description":"Cumulative live events pushed to IMAP IDLE clients, or null","format":"int64","type":["integer","null"]},"eventsPushedJmap":{"description":"Cumulative live events pushed to JMAP SSE clients, or null","format":"int64","type":["integer","null"]},"eventsPushedWeb":{"description":"Cumulative live events pushed to web clients, or null","format":"int64","type":["integer","null"]},"forwardedMessages":{"description":"Count of auto-forwarded or redirected messages, or null","format":"int64","type":["integer","null"]},"inboundBytes":{"description":"Total size of inbound mail in bytes, or null","format":"int64","type":["integer","null"]},"inboundDeliveries":{"description":"Count of messages delivered into account mailboxes, or null","format":"int64","type":["integer","null"]},"mailBytes":{"description":"Total mail storage in bytes at day close (including trash), or null","format":"int64","type":["integer","null"]},"mailboxes":{"description":"Number of active mailboxes/identities on the account, or null","format":"int64","type":["integer","null"]},"maxDatabaseSize":{"description":"The account's LARGEST single store's metadata database size in bytes that day (MAX across mailboxes, not a sum — the figure that measures distance to the per-store store_metadata_full ceiling), or null when not measured","format":"int64","type":["integer","null"]},"outboundBytes":{"description":"Total size of outbound mail relayed in bytes, or null","format":"int64","type":["integer","null"]},"outboundMessages":{"description":"Count of distinct outbound messages sent, or null","format":"int64","type":["integer","null"]},"outboundRecipients":{"description":"Total outbound recipient deliveries relayed, or null","format":"int64","type":["integer","null"]},"pimBytes":{"description":"Calendar and contacts storage in bytes, or null","format":"int64","type":["integer","null"]},"pimRelayedImap":{"description":"Retired: the mail store no longer relays pim.changed, so this is null for every day filed since. Earlier days keep the cumulative frames it relayed to imap-class sockets","format":"int64","type":["integer","null"]},"pimRelayedJmap":{"description":"Retired: the mail store no longer relays pim.changed, so this is null for every day filed since. Earlier days keep the cumulative frames it relayed to jmap-class sockets","format":"int64","type":["integer","null"]},"pimRelayedWeb":{"description":"Retired: the mail store no longer relays pim.changed, so this is null for every day filed since. Earlier days keep the cumulative frames it relayed to web-class sockets","format":"int64","type":["integer","null"]},"reportedAt":{"description":"Timestamp when usage was reported to billing system in epoch seconds, or null","format":"int64","type":["integer","null"]},"requestBytesOut":{"description":"Total API response bandwidth consumed in bytes, or null","format":"int64","type":["integer","null"]},"requests":{"description":"Total API requests made to this account, or null","format":"int64","type":["integer","null"]},"requestsRolledAt":{"description":"Timestamp when API request metrics were aggregated in epoch seconds, or null","format":"int64","type":["integer","null"]},"rolledAt":{"description":"Timestamp when daily usage was aggregated in epoch seconds, or null","format":"int64","type":["integer","null"]},"socketsAcceptedImap":{"description":"Cumulative websocket/IDLE connections opened by IMAP clients, or null","format":"int64","type":["integer","null"]},"socketsAcceptedJmap":{"description":"Cumulative event connections opened by JMAP clients, or null","format":"int64","type":["integer","null"]},"socketsAcceptedWeb":{"description":"Cumulative websocket connections opened by web clients, or null","format":"int64","type":["integer","null"]},"trashBytes":{"description":"Storage bytes occupied by trash messages, or null","format":"int64","type":["integer","null"]},"webhookDeliveries":{"description":"Count of outgoing webhook notifications, or null","format":"int64","type":["integer","null"]}},"required":["day","mailBytes","trashBytes","pimBytes","mailboxes","calendarObjects","contactObjects","maxDatabaseSize","estimated","inboundDeliveries","inboundBytes","outboundMessages","outboundRecipients","outboundBytes","forwardedMessages","webhookDeliveries","eventsPushedImap","eventsPushedWeb","eventsPushedJmap","socketsAcceptedImap","socketsAcceptedWeb","socketsAcceptedJmap","pimRelayedImap","pimRelayedWeb","pimRelayedJmap","requests","requestBytesOut","rolledAt","requestsRolledAt","closedAt","reportedAt"],"type":"object"},"Vacation":{"properties":{"fromDate":{"description":"Start timestamp in ISO 8601 UTC format (e.g. 2026-08-01T09:00:00Z), or null","type":["string","null"]},"htmlBody":{"description":"HTML auto-reply message content, or null","type":["string","null"]},"isEnabled":{"description":"True if out-of-office auto-reply is enabled","type":"boolean"},"state":{"description":"Opaque state token for conditional updates (ETag / If-Match)","type":"string"},"subject":{"description":"Custom auto-reply subject line, or null for default","type":["string","null"]},"textBody":{"description":"Plain-text auto-reply message content","type":["string","null"]},"toDate":{"description":"End timestamp in ISO 8601 UTC format (e.g. 2026-08-15T18:00:00Z), or null","type":["string","null"]}},"required":["isEnabled","fromDate","toDate","subject","textBody","htmlBody","state"],"type":"object"},"ValidationError":{"example":{"error":"validation_failed","issues":[{"code":"invalid_string","message":"Invalid email address","path":"body.to.0.email"}]},"properties":{"error":{"description":"Always validation_failed for request schema mismatches","enum":["validation_failed"],"type":"string"},"issues":{"description":"List of specific validation issues found in the request","items":{"properties":{"code":{"description":"Validation issue code","type":"string"},"message":{"description":"Human-readable explanation of why validation failed","type":"string"},"path":{"description":"Field or parameter path that failed validation (e.g. body.name)","type":"string"}},"required":["path","code","message"],"type":"object"},"type":"array"}},"required":["error","issues"],"type":"object"},"VanishedResult":{"properties":{"highestModseq":{"description":"Current RFC 7162 HIGHESTMODSEQ of the label","format":"int64","type":"integer"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"},"vanished":{"description":"List of expunged UIDs since the requested modseq","items":{"format":"int64","type":"integer"},"type":"array"}},"required":["highestModseq","vanished"],"type":"object"},"VerifiedRecipient":{"properties":{"address":{"description":"The address, normalized as forwarding destinations are: trimmed, lowercased, its domain in A-label form","type":"string"},"createdAt":{"description":"When the address was added, in epoch seconds","format":"int64","type":"integer"},"id":{"description":"Verified recipient ULID: the handle DELETE takes, so no address is path-encoded","type":"string"},"lastSentAt":{"description":"When a confirmation link was last mailed, in epoch seconds. Each link works for seven days from its own mailing; a pending address whose newest link has expired is dropped at the next add, and posting it again mails a fresh one","format":"int64","type":["integer","null"]},"state":{"description":"Confirmation state; only 'verified' counts as a verified recipient","enum":["pending","verified"],"type":"string"},"verifiedAt":{"description":"When its owner pressed Confirm, in epoch seconds, or null while pending","format":"int64","type":["integer","null"]}},"required":["id","address","state","createdAt","verifiedAt","lastSentAt"],"type":"object"},"VerifiedRecipientAdded":{"properties":{"recipient":{"allOf":[{"$ref":"#/components/schemas/VerifiedRecipient"},{"description":"The address's row as it now stands"}]},"sent":{"description":"True when a confirmation link was mailed by this request; false when the address was already verified and nothing was sent","type":"boolean"}},"required":["recipient","sent"],"type":"object"},"WebauthnCredential":{"properties":{"createdAt":{"description":"Enrollment timestamp in epoch seconds","format":"int64","type":"integer"},"id":{"description":"Unique WebAuthn credential ULID","type":"string"},"lastUsedAt":{"description":"Timestamp when key was last used for authentication, or null","format":"int64","type":["integer","null"]},"name":{"description":"User-assigned name for the security key or passkey","type":["string","null"]},"rpId":{"description":"Relying party ID (hostname) the key is bound to","type":"string"},"transports":{"description":"Supported authenticator transports (usb, nfc, ble, internal)","items":{"type":"string"},"type":["array","null"]}},"required":["id","name","createdAt","lastUsedAt","transports","rpId"],"type":"object"},"WebauthnRegistrationOptions":{"properties":{"attestation":{"description":"Attestation conveyance preference","enum":["none"],"type":"string"},"authenticatorSelection":{"properties":{"residentKey":{"description":"Resident key requirement","type":"string"},"userVerification":{"description":"User verification requirement (preferred, required, discouraged)","type":"string"}},"required":["residentKey","userVerification"],"type":"object"},"challenge":{"description":"Base64url-encoded one-time challenge","type":"string"},"excludeCredentials":{"description":"Credentials to exclude to prevent duplicate enrollment","items":{"properties":{"id":{"description":"Base64url-encoded credential ID","type":"string"},"transports":{"description":"Allowed authenticator transport types","items":{"type":"string"},"type":"array"},"type":{"description":"Credential type","enum":["public-key"],"type":"string"}},"required":["type","id"],"type":"object"},"type":"array"},"pubKeyCredParams":{"description":"Supported cryptographic algorithms","items":{"properties":{"alg":{"type":"integer"},"type":{"enum":["public-key"],"type":"string"}},"required":["type","alg"],"type":"object"},"type":"array"},"rp":{"properties":{"id":{"description":"Relying party ID","type":"string"},"name":{"description":"Relying party display name","type":"string"}},"required":["id","name"],"type":"object"},"timeout":{"description":"Ceremony timeout in milliseconds","type":"integer"},"user":{"properties":{"displayName":{"description":"User display name","type":"string"},"id":{"description":"Base64url-encoded identity ULID","type":"string"},"name":{"description":"User account name","type":"string"}},"required":["id","name","displayName"],"type":"object"}},"required":["challenge","rp","user","pubKeyCredParams","timeout","excludeCredentials","authenticatorSelection","attestation"],"type":"object"},"WebhookDeliveryAttachment":{"properties":{"content":{"description":"Base64 of the decoded bytes, or null (see contentOmitted)","type":["string","null"]},"contentId":{"description":"Content-ID for cid: references, or null","type":["string","null"]},"contentOmitted":{"description":"Why `content` is null: the part is over the per-attachment inline ceiling, or the batch's total inline budget was spent","enum":["too_large","budget_exhausted"],"type":"string"},"contentType":{"type":"string"},"degraded":{"description":"Synthetic child of a degraded multipart parse; bytes are a best effort","enum":[true],"type":"boolean"},"filename":{"type":"string"},"inline":{"description":"True for a Content-Disposition: inline part","type":"boolean"},"section":{"description":"IMAP section number. Fetchable as GET /messages/{id}/parts/{section} when the address also delivers to a mailbox (a webhook TAP); a destination-only webhook has no stored message, so there it is just an identifier","type":"string"},"size":{"description":"EXACT decoded byte length, whether or not `content` was inlined","format":"int64","type":"integer"},"url":{"description":"Signed capability URL for the decoded bytes (GET /deliveries/fetch/{token}), present only when `content` is null and the fetch feature is configured. Needs no credentials; expires","type":"string"}},"required":["section","filename","contentType","size","inline","contentId","content"],"type":"object"},"WebhookDeliveryAuth":{"properties":{"arc":{"description":"ARC verdict, or null","type":["string","null"]},"dkim":{"description":"DKIM verdict, or null","type":["string","null"]},"dmarc":{"description":"DMARC verdict, or null","type":["string","null"]},"junk":{"description":"The inbound spam verdict (X-OpenEmail-Junk), or null when none was stamped","type":["boolean","null"]},"spf":{"description":"SPF verdict (pass/fail/softfail/none/...), or null","type":["string","null"]}},"required":["spf","dkim","dmarc","arc","junk"],"type":["object","null"]},"WebhookDeliveryMessage":{"description":"The parsed message; degraded forms carry bodiesOmitted, never null","properties":{"attachments":{"items":{"$ref":"#/components/schemas/WebhookDeliveryAttachment"},"type":"array"},"attachmentsTruncated":{"description":"The attachment list was cut at the entry ceiling","enum":[true],"type":"boolean"},"auth":{"$ref":"#/components/schemas/WebhookDeliveryAuth"},"bodiesOmitted":{"description":"Present when the bodies are absent, and why. text/html/attachments are then empty as a matter of ignorance, not of fact — except for 'not_requested', which is the webhook asking for the 'reference' format: no MIME walk was performed and the original message is at rawUrl","enum":["too_large","unavailable","parse_failed","not_requested"],"type":"string"},"cc":{"items":{"$ref":"#/components/schemas/ContentAddress"},"type":"array"},"date":{"description":"Date header, epoch seconds (the envelope's receivedAt is separate)","format":"int64","type":["integer","null"]},"from":{"items":{"$ref":"#/components/schemas/ContentAddress"},"type":"array"},"headers":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Every header field, lowercased name mapped to its values in document order. Bounded by the 64 KB head window; a longer header block is reported partially","type":"object"},"html":{"description":"Decoded, charset-transcoded text/html body; null when the message has none","type":["string","null"]},"htmlTruncated":{"description":"The HTML body hit the 1 MiB decoded ceiling","enum":[true],"type":"boolean"},"inReplyTo":{"type":["string","null"]},"messageId":{"description":"Message-ID header value, or null","type":["string","null"]},"references":{"description":"References header Message-IDs","items":{"type":"string"},"type":"array"},"replyTo":{"items":{"$ref":"#/components/schemas/ContentAddress"},"type":"array"},"subject":{"type":["string","null"]},"text":{"description":"Decoded, charset-transcoded text/plain body; null when the message has none","type":["string","null"]},"textTruncated":{"description":"The text body hit the 1 MiB decoded ceiling","enum":[true],"type":"boolean"},"to":{"items":{"$ref":"#/components/schemas/ContentAddress"},"type":"array"}},"required":["subject","date","messageId","inReplyTo","references","from","to","cc","replyTo","text","html","attachments","headers","auth"],"type":"object"},"WebhookDeliveryPayload":{"properties":{"blobHash":{"description":"SHA-256 hash of the raw MIME content","type":"string"},"deliveryId":{"description":"This delivery's id: the receiver's idempotency key across retries","type":"string"},"from":{"description":"SMTP envelope sender address","type":"string"},"message":{"$ref":"#/components/schemas/WebhookDeliveryMessage"},"rawUrl":{"description":"Signed capability URL for the original RFC 5322 bytes (GET /deliveries/fetch/{token}), for DKIM verification, archival, or a parser of your own. Needs no credentials; expires. Absent when the fetch feature is not configured","type":"string"},"receivedAt":{"description":"When the platform accepted the message, epoch seconds","format":"int64","type":"integer"},"size":{"description":"Raw RFC 5322 message size in bytes","format":"int64","type":"integer"},"to":{"description":"SMTP envelope recipient address: the address routed to this webhook","type":"string"}},"required":["deliveryId","from","to","receivedAt","size","blobHash","message"],"type":"object"},"WhoamiResult":{"properties":{"accountId":{"description":"Owning account ID, or null for system keys","type":["string","null"]},"credentialId":{"description":"Credential ULID for mailbox app passwords, or null","type":["string","null"]},"domains":{"description":"An account key's domain scope (migration 0078), sorted — ABSENT for an unscoped key and for every other credential kind. Present, this key reaches only these domains' directory and the mailboxes with an address on them; a call outside that answers 404 (a resource) or 403 account_credentials_required (the account tier, and JMAP).","items":{"type":"string"},"type":"array"},"idleExpiresAt":{"description":"The idle deadline computed from the key's recorded last use (or creation if no use is recorded), in epoch seconds, or null when it never lapses. Usage updates are best-effort and coalesced with a five-minute interval, so successful use may not immediately advance this deadline. This response can precede its own request's renewal.","format":"int64","type":["integer","null"]},"keyId":{"description":"API key ID for system or account bearers, or null for mailbox app passwords","type":["string","null"]},"kind":{"description":"What this key is ('cli' for one the browser login minted), or null — including for every mailbox app password, which has no key row. Display metadata; nothing authorizes on it.","type":["string","null"]},"mailboxId":{"description":"Mailbox ULID for mailbox app passwords, or null","type":["string","null"]},"permittedRecipients":{"description":"A mailbox credential's OWN outbound recipient allowlist (design D50) — exact addresses and `*@domain` wildcards, INTERSECTED with the identity's at every submission site, so this list is a bound and not a promise that everything in it is deliverable. ABSENT when this credential carries no list of its own (the `domains` convention), which is not the same fact as `[]`: an empty array is a credential permitted to send to NOBODY. Here so an agent door learns its correspondents up front instead of discovering them as a per-recipient `recipient_not_permitted`","items":{"type":"string"},"type":"array"},"scope":{"anyOf":[{"enum":["read","write","send","full"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"A mailbox credential's scope — 'read', 'write', 'send' or 'full' — or null for an API key. What this bearer may do of what its mailbox may do; a call outside it answers 403 credential_scope naming the rung it needs"},"type":{"description":"Bearer credential permission scope","enum":["system","account","mailbox"],"type":"string"}},"required":["type","keyId","accountId","mailboxId","credentialId","scope","kind","idleExpiresAt"],"type":"object"}},"securitySchemes":{"bearerAuth":{"description":"Two credential kinds share this scheme; `GET /api/v1/auth/whoami` answers which one you hold and what it reaches.\n\n**`oek_…` API key** (minted by `POST /api/v1/api-keys`; shown once at mint). `role: account` reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. `role: system` additionally reaches the operator surface, which is documented separately.\n\n**`oemp_…` mailbox app password** (minted by `POST /api/v1/identities/{identityId}/credentials`). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with `403 insufficient_scope`.\n\nRefusal vocabulary: a missing, malformed, expired, or revoked credential answers `401 unauthorized` with a `WWW-Authenticate: Bearer` challenge; a VALID credential outside its scope answers `403` (`insufficient_scope` for an app password on a directory route, `system_credentials_required` where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare `security: []`.","scheme":"bearer","type":"http"}}},"info":{"contact":{"name":"open.email","url":"https://open.email"},"description":"Message store + routing core for the open.email platform: mailbox Durable Objects, R2 blobs, D1 directory.\n\n**Pre-release.** Version 0.x: the surface is complete, but names and shapes may still change without a deprecation cycle. Pin the exact contract you built against.\n\n## Authentication\nBearer credentials, two kinds (the `bearerAuth` security scheme carries the full matrix): an `oek_…` account API key reaches the account's directory and every mailbox it owns; an `oemp_…` mailbox app password reaches ONE mailbox and is refused on directory routes with `403 insufficient_scope`. `GET /api/v1/auth/whoami` answers which credential you hold. A missing or invalid credential answers `401 unauthorized` with a `WWW-Authenticate: Bearer` challenge. The only unauthenticated operations are the ones declared `security: []`: `GET /api/v1/health`; the token-in-path capabilities (`/pim/feeds/{token}`, `/deliveries/fetch/{token}`, `/forwarding/disable/{token}`, `/recipients/confirm/{token}`), where the token IS the credential; and the public `/branding/*` reads a login screen needs before anyone signs in (which answer a uniform 404 for an unknown domain and an unbranded one alike).\n\n## Errors\nEvery non-2xx answers `{ \"error\": \"snake_case_code\", … }`; request-schema failures answer `{ \"error\": \"validation_failed\", \"issues\": [...] }`. Key on the CODE, never on the status alone: the per-operation descriptions say which codes are permanent and which must be retried, and Transient failures below names the retryable 503s that operations share. Under the object directory, a write that would change an account's identity counts (an identity or a group's persona created, held, deleted or restored; a push subscription change; a revocation that takes push subscriptions with it) answers `503 temporary_failure` with `Retry-After` while those counts cannot be updated: that write was not made, so retry the same request.\n\n## Transient failures\nAny operation can answer `503 temporary_failure` with a `Retry-After` header (seconds) while the platform's storage briefly cannot answer, whether or not the operation lists other 503s of its own. An operation that reaches a mailbox can likewise answer `503 mailbox_reopening` (its store was found closed while the mailbox exists, and has just been reopened), `503 mailbox_closing` (the mailbox is being deleted) or `503 mailbox_unavailable` (whether the mailbox still exists could not be confirmed just now), each with `Retry-After`. None of these is a verdict on the request:\n- Wait at least `Retry-After`, then back off exponentially with jitter up to a cap, and bound the total time. Many clients retrying at the same instant prolong an incident.\n- A `GET` is always safe to retry.\n- A write that got one of these answers may have been applied before the failure. Retry it with the SAME idempotency key where the operation takes one (`X-Delivery-Id` on the operations that send or store a message; `Idempotency-Key` on an identity created with webhooks and on `PATCH /api/v1/identities/{identityId}`). Otherwise read the state back before retrying, or use the forms that converge: PUT or PATCH to a target value, and DELETE where a later `404` means it was done.\n- `500 internal_error` is a defect, not a retry signal: retry a read after a delay, and report it.\n- Keep the `CF-Ray` response header of any failure: it names the request in the platform's logs.\n\n## Rate limits and retries\nA `429` is always temporary: retry, never surface it as a permanent failure. Where the wait is known it carries a `Retry-After` header (seconds) and `retryAfterSeconds` in the body. Sending endpoints take an `X-Delivery-Id` idempotency key: retry with the SAME id and the platform converges on one send.\n\n## Pagination, ids, timestamps\nListings page with opaque cursors (`nextCursor`, absent on the last page); hold filters and sort constant across a crawl. Ids are ULIDs. Timestamps are epoch SECONDS everywhere, with one deliberate exception: the RFC 8621 search filter's `before`/`after` take UTCDate strings.\n\n## Getting started\n1. Create an API key (from the console, or `POST /api/v1/api-keys` with an existing key), then `GET /api/v1/auth/whoami`.\n2. `GET /api/v1/identities` lists your mailboxes; message routes take the mailbox's ULID.\n3. Read: `GET /mailboxes/{mailboxId}/messages`, then `/messages/{id}/content`.\n4. Send: `POST /mailboxes/{mailboxId}/send`.\n5. Stay current: poll `GET /mailboxes/{mailboxId}/messages/changes`, or subscribe to the WebSocket at `/mailboxes/{mailboxId}/events`.\n\n## Webhooks\nThe HTTP callbacks this platform POSTS OUT (event notifications, message deliveries to webhook addresses) are specified in this document's top-level `webhooks` section, signature scheme included.\n\n## Push\nThree channels wake a client, by where it runs. A foreground client holds the WebSocket (`GET /mailboxes/{mailboxId}/events`). A server subscribes an event webhook (above). A device that must wake while the app is closed registers Web Push (RFC 8030): browsers, PWAs and UnifiedPush Android apps subscribe with the `vapidPublicKey` from `GET /push-subscriptions` as `applicationServerKey`, register the resulting endpoint at `POST /push-subscriptions`, and echo back the verification code the first push delivers. Every push is content-free: a `StateChange` whose per-type state tokens are accepted verbatim as `since` by `GET /mailboxes/{mailboxId}/messages/changes`. A native app with its own backend combines the first two instead: receive event webhooks server-side, wake the app through your own APNs/FCM credentials, then sync via the changes feed. The platform deliberately holds no third-party push credentials, so there is no APNs or FCM bridge to configure here.","title":"openemail-core — public API","version":"0.1.0"},"openapi":"3.1.0","paths":{"/api/v1/accounts/{accountId}":{"get":{"description":"Returns details and status for a specific account.","operationId":"get_AccountGet","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"Account details"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get account details","tags":["Accounts"]},"delete":{"description":"Soft-deletes an account, starting a grace period before final data purge.","operationId":"delete_AccountDelete","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}},{"description":"Set to 'true' to purge immediately bypassing the grace window (system callers only)","in":"query","name":"purge","required":false,"schema":{"description":"Set to 'true' to purge immediately bypassing the grace window (system callers only)","enum":["true","false"],"type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeleteResult"}}},"description":"Account deletion initiated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"system_credentials_required — only a system caller may pass ?purge=true"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"transition_in_progress — retry after the lifecycle transition settles"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_purged — account has already been permanently purged"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"upstream_unavailable — lifecycle transition or purge scheduling unavailable"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete an account","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/recovery-policy":{"put":{"description":"Chooses whether mailbox users in this account may recover their own password (recovery codes, and the recovery address once it ships), or whether resets come from an admin only. admin_only keeps any existing recovery codes and addresses and refuses their use.","operationId":"put_RecoveryPolicySet","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"policy":{"description":"self_service: users may recover their own mailbox. admin_only: recovery rows are kept and refused","enum":["self_service","admin_only"],"type":"string"}},"required":["policy"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryPolicy"}}},"description":"The policy now in force"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_deleted — the account is inside its deletion window or purged; restore it first"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Set the account's mailbox recovery policy","tags":["Accounts"],"x-max-json-body-bytes":1048576}},"/api/v1/accounts/{accountId}/retention":{"put":{"description":"Sets the account DEFAULT retention window in days — the window every mailbox the account owns enforces unless it has one of its own, EXISTING mailboxes included, pushed to each store by a background walk. The owning account key or a system key. Refused below the platform floor. Answers the same view as GET — the default now in force and one page of per-mailbox previews of it — read it. Mail expunged under the window is restorable for 14 days; to recover from a wrong window, clear or raise it FIRST, then restore.","operationId":"put_AccountRetentionPut","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"retentionDays":{"description":"The account DEFAULT window in days, applied to every mailbox the account owns that has no window of its own — EXISTING mailboxes included (it is read at resolution time, not copied at create), so preview it first with GET ?days=. Refused below the platform floor (400 retention_too_short). Pushed to the account's stores by a paged background walk; deliberately outside the plan system, so a plan change never touches it","exclusiveMinimum":0,"maximum":36500,"type":"integer"}},"required":["retentionDays"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountRetention"}}},"description":"The default now in force, with the first page of per-mailbox previews"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or retention_too_short (the window is below the platform floor; the body carries minDays)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_deleted — the account is inside its deletion window or purged; restore it first"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Set account default retention window","tags":["Accounts"],"x-max-json-body-bytes":1048576},"get":{"description":"Pages the account's mailboxes with each one's own window, the window in force after resolution against the account default, and a preview of what a window would expunge — the window named by ?days= (what an account default WOULD do, before setting one), else each mailbox's effective window. One store read per mailbox; a store that could not be read is listed in `unreadable` rather than reported as zero.","operationId":"get_AccountRetentionGet","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}},{"description":"One window in days to preview on every mailbox (e.g. the account default you are about to set)","in":"query","name":"days","required":false,"schema":{"description":"One window in days to preview on every mailbox (e.g. the account default you are about to set)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountRetention"}}},"description":"One page of mailboxes with their retention state and previews"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed ?days= (an integer 1–36500)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Preview retention across an account's mailboxes","tags":["Accounts"]},"delete":{"description":"Clears the account DEFAULT retention window; mailboxes with a window of their own keep it, every other mailbox stops enforcing one on the next walk. Answers the same view as GET. Nothing already in the trash tier is restored by this: restore messages explicitly.","operationId":"delete_AccountRetentionDelete","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountRetention"}}},"description":"The account with no default in force, with the first page of per-mailbox state"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_deleted — the account is inside its deletion window or purged; restore it first"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Clear account default retention window","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/limits":{"get":{"description":"Returns every plan limit of the account with its resolved threshold (the account's own number, or the platform default it follows), enforcement state, stored value, and whether the number is an operator-agreed limit; plus the vetting label and billing tier. `enforcement` is enforced, log_only (shadow mode: measured without refusing), or off (`limit` null). Shadow mode preserves the numeric threshold. This describes configured behavior, not transient ledger health or other refusal checks. The mailbox ceiling and the mailbox, address and domain creation limits bound the account's own key; an operator's system key is not held to them. Current usage is on send-usage, receive-usage and storage-usage.","operationId":"get_AccountLimitsGet","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountLimits"}}},"description":"Every plan limit's resolved threshold and enforcement state"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get an account's limits and enforcement state","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/verified-recipients":{"post":{"description":"Names an outside address and mails it a link to a page whose Confirm button makes it a verified recipient of this account; the link works for seven days, and opening it changes nothing on its own. Posting a pending address again mails a fresh link, at most once a minute. Posting a verified address answers 200 with `sent: false` and mails nothing. A refusal of the mail that concerns the address itself (its server refused it, or it is suppressed) is answered exactly as a sent link is. Reachable by the account's own key or a system key.","operationId":"post_VerifiedRecipientAdd","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"address":{"description":"The outside address to verify","maxLength":320,"minLength":3,"type":"string"}},"required":["address"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifiedRecipientAdded"}}},"description":"The address's row as it now stands, and whether a link was mailed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, when the address is not one; or always_verified, carrying `domain`, when the address is on one of this account's own domains, which are always verified recipients and are never stored"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: the account does not exist or is not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"recipient_limit_reached, carrying `limit`: the account holds 100 addresses, pending and verified together, so remove one first; or pending_limit_reached, carrying `limit`: 10 addresses are awaiting their owners' answer, so wait for one, or remove one. A pending address whose newest link has expired no longer counts"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"resend_cooldown, with Retry-After and `retryAfterSeconds`: a link was mailed to this address less than a minute ago; or confirmation_limit_reached, with Retry-After, `retryAfterSeconds` and `limit`: the account has mailed its 20 confirmation links for this UTC day; or rate_limited, with Retry-After: too many links from this account, or to this address, in the last minute. The last is deliberately one answer for both, since the budget per address is shared across the deployment","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"recipient_verification_unavailable, with Retry-After: domain ownership is being removed and has not settled, so retry; or recipient_mail_unavailable: the link could not be mailed for a reason on the platform's side (the mail binding or the link key is unconfigured, the platform's hourly cap on its own mail is spent, or the sending service refused the message), so nothing is stored and the request may be retried. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Add a verified recipient","tags":["Accounts"],"x-max-json-body-bytes":1048576},"get":{"description":"Every outside address this account has asked to send to, pending or verified, oldest first. Addresses on the account's own domains are always verified recipients and are never listed. Unpaginated: an account holds at most 100. Reachable by the account's own key or a system key.","operationId":"get_VerifiedRecipientList","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"recipients":{"items":{"$ref":"#/components/schemas/VerifiedRecipient"},"type":"array"}},"required":["recipients"],"type":"object"}}},"description":"The list"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: the account does not exist or is not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List an account's verified recipients","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/verified-recipients/{recipientId}":{"delete":{"description":"Removes the address from the account's list, pending or verified; every link mailed for it stops working. Adding it again starts over with a new link. Reachable by the account's own key or a system key.","operationId":"delete_VerifiedRecipientDelete","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}},{"description":"Verified recipient ULID","in":"path","name":"recipientId","required":true,"schema":{"description":"Verified recipient ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Removed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: the account or the recipient does not exist, or is not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove a verified recipient","tags":["Accounts"]}},"/api/v1/recipients/confirm/{token}":{"get":{"description":"Public. Renders the page a verified recipient's confirmation link opens: the address, and a Confirm button whose form POSTs to the same URL. A GET never confirms anything, because link scanners prefetch URLs. No bearer credential: the signed token in the path IS the credential, and its holder is the owner of an outside address.","operationId":"get_RecipientConfirmPage","parameters":[{"description":"Signed confirmation-link token","in":"path","name":"token","required":true,"schema":{"description":"Signed confirmation-link token","maxLength":2048,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"text/html":{"schema":{"type":"string"}}},"description":"The confirmation page, or a page saying the address is already confirmed"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"A page saying the link is not valid, has expired (links work for seven days), or no longer works (its address was removed, or a newer link replaced it)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"security":[],"summary":"Verified recipient confirmation link (the page)","tags":["Accounts"]},"post":{"description":"Public. The confirmation page's Confirm button: makes the address a verified recipient of the account that asked, and retires every link mailed for it. Idempotent: a second POST finds it already confirmed. No bearer credential: the signed token in the path IS the credential.","operationId":"post_RecipientConfirm","parameters":[{"description":"Signed confirmation-link token","in":"path","name":"token","required":true,"schema":{"description":"Signed confirmation-link token","maxLength":2048,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"text/html":{"schema":{"type":"string"}}},"description":"The address is confirmed (or already was)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"A page saying the link is not valid, has expired (links work for seven days), or no longer works (its address was removed, or a newer link replaced it); nothing was changed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"security":[],"summary":"Verified recipient confirmation link (confirm)","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/usage":{"get":{"description":"Returns daily storage, message counts, and API request meter metrics for an account over a UTC date range.","operationId":"get_AccountUsageGet","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}},{"description":"First UTC day in YYYY-MM-DD format (default: 29 days ago)","in":"query","name":"from","required":false,"schema":{"description":"First UTC day in YYYY-MM-DD format (default: 29 days ago)","type":"string"}},{"description":"Last UTC day in YYYY-MM-DD format (default: today)","in":"query","name":"to","required":false,"schema":{"description":"Last UTC day in YYYY-MM-DD format (default: today)","type":"string"}},{"description":"Set to 'true' to include detailed API request count breakdown by resource and principal","in":"query","name":"requests","required":false,"schema":{"description":"Set to 'true' to include detailed API request count breakdown by resource and principal","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUsage"}}},"description":"Daily usage metrics ascending by date"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed (malformed or inverted range, or exceeds 400 days)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get daily account usage metrics","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/storage-usage":{"get":{"description":"Returns total stored bytes summed across all mailboxes in an account against the configured storage quota.","operationId":"get_AccountStorageUsageGet","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountStorageUsage"}}},"description":"Current storage pool usage and limits"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get account storage pool usage","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/send-usage":{"get":{"description":"Returns outbound send rate limit consumption (messages and recipients) and mailbox, address and domain creation churn over the rolling 24-hour window for an account.","operationId":"get_AccountSendUsageGet","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSendUsage"}}},"description":"Current window send limit usage and effective account caps"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get account send rate limit usage","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/receive-usage":{"get":{"description":"Returns the inbound receive allowance's consumption (messages and bytes STORED in the rolling 24-hour window, across every mailbox the account owns), the allowance in force, the per-mailbox fair-share fraction, and the window's heaviest receivers. The allowance is a platform backstop: over it, inbound mail is deferred (429 receiving_rate_limited), never bounced.","operationId":"get_AccountReceiveUsageGet","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountReceiveUsage"}}},"description":"Current window receive usage and the allowance in force"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get account receive allowance usage","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/traffic":{"get":{"description":"Returns total aggregated email volume and bytes across all domains owned by an account. Pass `mailboxId` to narrow the same aggregate to one mailbox — the series a mailbox overview charts. That dimension was added to the analytics write later than the rest, so a mailbox-scoped window covers traffic recorded since; `GET /domains/{domain}/events` (or `/accounts/{accountId}/events`) with the same filter remains the authoritative log.","operationId":"get_AccountTraffic","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}},{"description":"Time window range ('1h', '6h', '24h', '7d', '30d')","in":"query","name":"range","required":false,"schema":{"default":"24h","description":"Time window range ('1h', '6h', '24h', '7d', '30d')","enum":["1h","6h","24h","7d","30d"],"type":"string"}},{"description":"Narrow the aggregate to a single mailbox ULID","in":"query","name":"mailboxId","required":false,"schema":{"description":"Narrow the aggregate to a single mailbox ULID","maxLength":64,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountTraffic"}}},"description":"Counts and bytes summed across all domains owned by this account"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — unknown range value"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"analytics_query_failed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"analytics_unavailable. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get account traffic statistics","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/requests":{"get":{"description":"Returns the API calls attributed to an account per time bucket, successes and failures alike: one per HTTP request plus one per JMAP method call, made with the account's keys or for its mailboxes. Buckets are labelled, sized and aligned exactly as `GET /accounts/{accountId}/traffic`'s for the same range. A sampled estimate; `GET /accounts/{accountId}/usage` carries the exact daily counts.","operationId":"get_AccountRequestsGet","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}},{"description":"Time window ('1h', '6h', '24h', '7d', '30d')","in":"query","name":"range","required":false,"schema":{"default":"24h","description":"Time window ('1h', '6h', '24h', '7d', '30d')","enum":["1h","6h","24h","7d","30d"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountRequests"}}},"description":"The account's API calls per bucket over the window, oldest first, and their total"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — unknown range"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"analytics_query_failed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"analytics_unavailable: no analytics token or account id configured, or this deployment writes no API-call dataset. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get account API call counts","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/events":{"get":{"description":"Returns paginated delivery events and attempt history across every domain owned by an account, with filtering by time range, outcome, source, mailbox, or the prepared email that sent it.","operationId":"get_AccountEvents","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}},{"description":"Time window range ('1h', '6h', '24h', '7d', '30d')","in":"query","name":"range","required":false,"schema":{"default":"24h","description":"Time window range ('1h', '6h', '24h', '7d', '30d')","enum":["1h","6h","24h","7d","30d"],"type":"string"}},{"description":"Filter by delivery outcome ('delivered', 'bounced', 'deferred', 'relayed', 'filtered')","in":"query","name":"outcome","required":false,"schema":{"description":"Filter by delivery outcome ('delivered', 'bounced', 'deferred', 'relayed', 'filtered')","enum":["delivered","duplicate","queued","filtered","rejected","bounced","deferred","relayed","relay_rejected","relay_suppressed","relay_indeterminate","relay_content_lost","webhook_delivered","webhook_route_gone","event_delivered","event_hook_disabled","event_hook_gone","member_skipped","member_failed","fbl_recorded","fbl_content_lost","dmarc_recorded","dmarc_content_lost","dmarc_unreadable","dmarc_unparseable","dmarc_rejected","dead_lettered","internal_error","check_refused","check_accepted","blob_missing","rate_limited","limiter_unavailable","auth_failed","storage_warning","mail_refused","mail_accepted"],"type":"string"}},{"description":"Filter by traffic source ('inbound', 'outbound', 'relay', 'append', 'pickup')","in":"query","name":"source","required":false,"schema":{"description":"Filter by traffic source ('inbound', 'outbound', 'relay', 'append', 'pickup')","enum":["inbound","outbound","sent_copy","append","expansion","relay","webhook","pickup","edge","fbl","dmarc","bounce","events","api","check","read","auth","store","platform_mail"],"type":"string"}},{"description":"'mail' shows only rows where a message moved; 'all' (the default) also includes the rows where the platform describes itself — IMAP uploads, Sent copies, report ingestion, event-webhook batches and the per-RCPT gate. See the per-domain log for the full note.","in":"query","name":"kind","required":false,"schema":{"default":"all","description":"'mail' shows only rows where a message moved; 'all' (the default) also includes the rows where the platform describes itself — IMAP uploads, Sent copies, report ingestion, event-webhook batches and the per-RCPT gate. See the per-domain log for the full note.","enum":["mail","all"],"type":"string"}},{"description":"Filter by exact delivery ID","in":"query","name":"deliveryId","required":false,"schema":{"description":"Filter by exact delivery ID","maxLength":640,"minLength":1,"type":"string"}},{"description":"Filter by mailbox ULID identifier","in":"query","name":"mailboxId","required":false,"schema":{"description":"Filter by mailbox ULID identifier","maxLength":64,"minLength":1,"type":"string"}},{"description":"Filter by envelope sender email address","in":"query","name":"envelopeFrom","required":false,"schema":{"description":"Filter by envelope sender email address","maxLength":320,"minLength":1,"type":"string"}},{"description":"Filter by the row's detail marker — e.g. 'junk' for messages the platform filed into Junk, or a failure reason like 'sender_blocked'.","in":"query","name":"detail","required":false,"schema":{"description":"Filter by the row's detail marker — e.g. 'junk' for messages the platform filed into Junk, or a failure reason like 'sender_blocked'.","maxLength":64,"minLength":1,"type":"string"}},{"description":"Filter to the rows a prepared email (tenant template) wrote, by its slug: the admission of each recipient, every relay attempt after it, and a dead letter if the attempts ran out. Each row names its template and language in `template`.","in":"query","name":"template","required":false,"schema":{"description":"Filter to the rows a prepared email (tenant template) wrote, by its slug: the admission of each recipient, every relay attempt after it, and a dead letter if the attempts ran out. Each row names its template and language in `template`.","maxLength":64,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","type":"string"}},{"description":"Maximum events per page","in":"query","name":"limit","required":false,"schema":{"default":50,"description":"Maximum events per page","maximum":200,"minimum":1,"type":"integer"}},{"description":"Pagination cursor","in":"query","name":"cursor","required":false,"schema":{"description":"Pagination cursor","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountEvents"}}},"description":"Page of traffic delivery events across the account's domains"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed or invalid_cursor"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"analytics_query_failed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"analytics_unavailable. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Query account delivery event log","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/limit-incidents":{"get":{"description":"The account's own limit episodes (enforced refusals only — shadow would-refuses are operator-facing), newest first: which limit fired, at what scope, when, and whether a notice was delivered to the account's notice mailbox.","operationId":"get_AccountLimitIncidentsGet","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}},{"description":"Only episodes that opened at or after this instant (ms since epoch). Default: the last 7 days","in":"query","name":"since","required":false,"schema":{"description":"Only episodes that opened at or after this instant (ms since epoch). Default: the last 7 days","minimum":0,"type":["integer","null"]}},{"description":"Legacy exclusive timestamp bound (ms since epoch). This skips every row tied at that instant; use nextCursor/cursor for lossless paging","in":"query","name":"before","required":false,"schema":{"description":"Legacy exclusive timestamp bound (ms since epoch). This skips every row tied at that instant; use nextCursor/cursor for lossless paging","exclusiveMinimum":0,"type":"integer"}},{"description":"Opaque nextCursor from the previous page. Preserves tied timestamps and the original since bound; repeat the same direction, shadow, account and near filters. Require the unchanged cursor echo in the response: an older Worker ignores this parameter","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque nextCursor from the previous page. Preserves tied timestamps and the original since bound; repeat the same direction, shadow, account and near filters. Require the unchanged cursor echo in the response: an older Worker ignores this parameter","maxLength":1024,"type":"string"}},{"description":"Narrow to one limit family","in":"query","name":"direction","required":false,"schema":{"description":"Narrow to one limit family","enum":["send","recv","forward","storage","mint"],"type":"string"}},{"description":"Page size (default 100, max 500)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100, max 500)","maximum":500,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"cursor":{"description":"Present exactly when the request supplied cursor, echoed unchanged. Require this echo when paging: an older Worker ignores the unknown cursor and could return the newest page again","type":"string"},"incidents":{"items":{"$ref":"#/components/schemas/LimitIncident"},"type":"array"},"nextCursor":{"description":"Opaque position for the next older page; absent when this read found no further row. Use cursor, repeating the same filters","type":"string"}},"required":["incidents"],"type":"object"}}},"description":"Incidents, newest first"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List an account's limit incidents","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/audit":{"get":{"description":"Returns a paginated list of security and directory audit events for an account. Events older than 180 days are excluded. An account keeps at most its newest 1,000,000 events: past that, the oldest are pruned as new ones are written, so a high-churn account's trail can be shorter than 180 days.","operationId":"get_AccountAuditList","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}},{"description":"Exact resource type, e.g. `mailbox`","in":"query","name":"resourceType","required":false,"schema":{"description":"Exact resource type, e.g. `mailbox`","maxLength":64,"type":"string"}},{"description":"Exact resource id — one object's history","in":"query","name":"resourceId","required":false,"schema":{"description":"Exact resource id — one object's history","maxLength":255,"type":"string"}},{"description":"Exact action, e.g. `domain.update`","in":"query","name":"action","required":false,"schema":{"description":"Exact action, e.g. `domain.update`","maxLength":128,"type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"events":{"items":{"$ref":"#/components/schemas/AuditEvent"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["events"],"type":"object"}}},"description":"Page of audit events"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List account audit trail","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/activity":{"get":{"description":"The account's identities ordered by their latest recorded client activity, newest day first, ties by identity id, identities with no recorded activity last; open one identity's clients for the detail (GET /identities/:identityId/clients). Paged by keyset; a live list, so an identity seen between pages can move ahead of the cursor. A domain-scoped key sees the identities its scope reaches, as the mailbox listing does; its pages are bounded in work, so one may hold fewer than limit identities while more follow. The list ends only when nextCursor is absent.","operationId":"get_AccountActivityList","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"identities":{"items":{"$ref":"#/components/schemas/IdentityActivity"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["identities"],"type":"object"}}},"description":"Page of identities, most recently active first"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_cursor for a cursor that is not one this list issued, or one issued for another account or scope"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"insufficient_scope: a mailbox credential, which is not a directory principal"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List an account's identities by recent activity","tags":["Accounts"]}},"/api/v1/accounts/{accountId}/restore":{"post":{"description":"Cancels a pending account deletion during the grace period and restores access.","operationId":"post_AccountRestore","parameters":[{"description":"Account ULID identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"Account restored successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Account not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_deleted, purge_in_progress, or transition_in_progress"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_purged — account has already been permanently purged"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"upstream_unavailable — lifecycle transition unavailable"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Restore deleted account","tags":["Accounts"]}},"/api/v1/auth/whoami":{"get":{"description":"Answers what the presented bearer credential IS and therefore what it reaches; call it first when integrating. Key on `type`: `account` (an `oek_…` API key: the account's directory plus every mailbox it owns), `mailbox` (an `oemp_…` app password: one mailbox, `mailboxId` says which; directory routes answer 403 insufficient_scope), or `system` (an operator key). `scope` and `permittedRecipients` are a mailbox credential's own bound (D50): what it may do, and who it may send to — asked once here rather than learned from a 403 per call. `idleExpiresAt` warns when a key will lapse from disuse, so a client can say 'this key stops working on <date> unless you use it' rather than letting the holder discover it as a 401.","operationId":"get_AuthWhoami","responses":{"200":{"content":{"application/json":{"examples":{"account API key":{"value":{"accountId":"01J9ACCT8B1D4F7H2K00000000","credentialId":null,"idleExpiresAt":1803859200,"keyId":"01J9KEYX5C8E2G5J9M00000000","kind":"cli","mailboxId":null,"scope":null,"type":"account"}},"mailbox app password":{"value":{"accountId":"01J9ACCT8B1D4F7H2K00000000","credentialId":"01J9CRED7D1F4H8K2N00000000","idleExpiresAt":null,"keyId":null,"kind":null,"mailboxId":"01J9MBX7F4Q2K9T3W600000000","scope":"full","type":"mailbox"}}},"schema":{"$ref":"#/components/schemas/WhoamiResult"}}},"description":"Identity and permission scope of the calling token"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get current authenticated identity","tags":["Credentials"]}},"/api/v1/api-keys":{"post":{"description":"Creates an API key and returns the plaintext secret token once.","operationId":"post_ApiKeyCreate","requestBody":{"content":{"application/json":{"schema":{"properties":{"accountId":{"description":"Account ULID to associate key with (required for account role)","type":"string"},"domains":{"description":"Scope this key to these domains (bare lowercase names the owning account holds — an unknown or foreign one answers 400 unknown_domain naming it). A scoped key is an ACCOUNT key wearing a restriction: it reaches the directory of these domains (routes, patterns, DNS, branding, hostnames, webhooks) and the mailboxes with an address on them, and nothing whose subject is the account itself (403 account_credentials_required), nor JMAP. Delegation within one account, not tenancy — every domain still shares the account's caps, storage pool and bill. Omit for full account authority. Refused on system keys (400 system_key_unscopable); fixed for the key's life (revoke and re-mint to change).","items":{"maxLength":253,"minLength":1,"type":"string"},"maxItems":100,"minItems":1,"type":"array"},"idleTtlS":{"description":"Seconds of disuse after which this key stops authenticating, measured from last use (or from creation while it has never been used). Omit for a key that never lapses, which is the default and what every key had before. Refused on system keys.","maximum":31622400,"minimum":86400,"type":"integer"},"kind":{"description":"Display metadata for what this key is ('cli' for one the browser login minted). NEVER an authorization input — the caller sets it, so nothing may branch on it; it exists so a keys list can identify a row without matching on a name the owner can change.","pattern":"^[a-z][a-z0-9_-]{0,31}$","type":"string"},"managed":{"description":"System callers only: an infrastructure-held key, hidden from the owning account","type":"boolean"},"name":{"description":"Human-readable label for this API key","maxLength":128,"minLength":1,"type":"string"},"role":{"description":"Role level ('account' for tenant-scoped, 'system' for cluster-wide admin)","enum":["system","account"],"type":"string"},"surface":{"description":"System callers only: frontend service surface for meter attribution","enum":["rest","jmap","dav","gateway","webmail","console","mcp"],"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}},"description":"API key created successfully (plaintext token returned once)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, account_id_required, unknown_account, system_key_unexpirable, system_key_unscopable, invalid_domain (a `domains` entry is not a bare domain name; `domain` names it), or unknown_domain (a `domains` entry the target account does not hold; `domain` names it — identical for a missing and a foreign domain)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"system_credentials_required or cannot_mint_for_other_account"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create API key","tags":["Credentials"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns a paginated list of API keys without secrets. A key that finished (revoked, or lapsed past its idle window) more than 180 days ago may be omitted: finished keys are retained for the audit trail's 180-day window.","operationId":"get_ApiKeyList","parameters":[{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"apiKeys":{"items":{"$ref":"#/components/schemas/ApiKey"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["apiKeys"],"type":"object"}}},"description":"Page of API keys"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List API keys","tags":["Credentials"]}},"/api/v1/api-keys/{apiKeyId}":{"delete":{"description":"Permanently revokes an API key. Where finished keys are retained for 180 days (see List API keys), an id in the form keys are minted in (26 upper-case Crockford base32 characters) that no principal holds unrevoked, such as a key already revoked or one the retention removed, answers 200 without changing anything; a key another principal still holds, or an id in any other form, answers 404. A system key the deployment's SYSTEM_KEYS secret serves (listed by its id, or by its stored hash under any id) authenticates from the secret, not from its row, so revoking it here is refused (409 system_key_in_secret) until the entry is removed from the secret; while SYSTEM_KEYS is set but does not parse, revoking any system key is refused (409 system_keys_invalid), since fixing the secret could bring a revoked key back.","operationId":"delete_ApiKeyDelete","parameters":[{"description":"API key ULID identifier","in":"path","name":"apiKeyId","required":true,"schema":{"description":"API key ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokedResult"}}},"description":"API key revoked successfully, or no longer held by any principal"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"API key not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"System callers only. system_key_in_secret: the SYSTEM_KEYS secret serves the key and it keeps authenticating from it (`listedAs` names the entry); remove that entry from the secret and deploy, then revoke. system_keys_invalid: SYSTEM_KEYS is set but does not parse, and fixing it could bring a revoked system key back; fix it (or clear it) and deploy, then revoke"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Revoke an API key","tags":["Credentials"]}},"/api/v1/identities/{identityId}/credentials":{"post":{"description":"Creates an IMAP login password or generates a scoped API app password for a mailbox.","operationId":"post_CredentialCreate","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"properties":{"kind":{"enum":["password"],"type":"string"},"name":{"maxLength":128,"type":"string"},"password":{"maxLength":1024,"minLength":8,"type":"string"},"scope":{"description":"A login password is always 'full'; any other value is refused","enum":["full"],"type":"string"},"username":{"maxLength":320,"minLength":3,"type":"string"}},"required":["kind","password"],"type":"object"},{"properties":{"currentPassword":{"description":"Required when the caller is the mailbox's OWN bearer (self-service), ignored for account and system callers: the mailbox's current login password, re-proved because an app password outlives the session that mints it. Refused as password_required (400), invalid_password (403) or no_password_credential (409)","maxLength":1024,"type":"string"},"expiresInSeconds":{"description":"Lifetime in seconds. The credential stops authenticating once it elapses: for a client minting one per browser session, so a closed tab cannot leave a permanently valid key behind. Omit for a credential that never expires (the default, and what a mail client wants)","maximum":31536000,"minimum":60,"type":"integer"},"kind":{"enum":["app_password"],"type":"string"},"name":{"maxLength":128,"type":"string"},"permittedRecipients":{"description":"The credential's OWN outbound recipient allowlist (exact addresses or `*@domain`), INTERSECTED with the identity's: both must permit. Accepted only with scope 'send' (400 permitted_recipients_requires_send otherwise); `[]` means this credential may send to nobody. At most 64 entries of at most 320 characters each (400 validation_failed otherwise). Omit or null for no list of its own","items":{"maxLength":320,"pattern":"^[^\\s@]+@[^\\s@]+$","type":"string"},"maxItems":64,"type":["array","null"]},"scope":{"description":"The credential's SCOPE (design D50), a ladder — 'read': list and read mail, nothing that leaves a trace; 'write': also mark, file, label and trash (everything the store undoes for 14 days); 'send': also submit mail; 'full' (the default): also permanent deletion, every settings route (rules, Sieve, vacation, prefs, forwarding, shares, retention, pickups, webhooks, credentials — reads included), PIM collection lifecycle and sharing. A call outside the scope answers 403 credential_scope naming the rung it needs. The bound for an agent token: mint 'write' for an assistant that reads and files, 'send' with permittedRecipients for one that may write to named people, and never 'full' for a program","enum":["read","write","send","full"],"type":"string"},"surface":{"description":"System callers only, and IGNORED for anyone else: which frontend this session credential belongs to, recorded on every API-request meter row it produces. The webmail BFF declares `webmail` when it mints a per-session password; a customer's own app password carries nothing, which is what keeps the two distinguishable","enum":["rest","jmap","dav","gateway","webmail","console","mcp"],"type":"string"},"username":{"maxLength":320,"minLength":3,"type":"string"}},"required":["kind"],"type":"object"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialCreated"}}},"description":"Created credential (app_password secret is shown only once in this response)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, username_required (the identity has no address for the username to default to, as one created withoutAddress has none: name it), invalid_address (D2: an address username must be an ASCII local part on an A-label domain), invalid_username (D2: a bare username must be printable ASCII with no whitespace), username_not_mailbox_address, username_not_in_scope (a DOMAIN-SCOPED api key may only mint a credential whose username is on one of its domains, migration 0078; `domain` names the refused one), permitted_recipients_requires_send (a recipient list on a credential whose scope is not 'send'), or password_required (the mailbox's own bearer sent no currentPassword)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_password (the mailbox's own bearer proved the wrong password), or account_credentials_required (a mailbox bearer asked for a login password: admin only; or a DOMAIN-SCOPED api key named a mailbox that is also routed on a domain outside its scope — a credential outlives the key that minted it, so minting one needs authority over every domain the mailbox serves)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"no_password_credential — the mailbox has no login password to prove, so it cannot self-serve; username_taken: a username that is not an address, already another identity's (under the objects directory)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited — too many self-service attempts","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the login index could not take the claim, or the identity could not vouch for itself just now; retry after the Retry-After window","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create mailbox credential","tags":["Credentials"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns every credential of a mailbox, revoked and expired ones included (secrets are never returned). Self-service: the mailbox's own bearer may read its own list.","operationId":"get_CredentialList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"credentials":{"items":{"$ref":"#/components/schemas/Credential"},"type":"array"}},"required":["credentials"],"type":"object"}}},"description":"List of credentials"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List mailbox credentials","tags":["Credentials"]}},"/api/v1/identities/{identityId}/credentials/{credentialId}":{"delete":{"description":"Revokes an existing password or app password, closing its active sessions. Self-service: the mailbox's own bearer may revoke its own APP passwords (a login password answers 404 to it, exactly like a missing id).","operationId":"delete_CredentialDelete","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Credential ULID identifier","in":"path","name":"credentialId","required":true,"schema":{"description":"Credential ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokedResult"}}},"description":"Revocation result"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or credential not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window (a revocation that would take push subscriptions with it)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Revoke a mailbox credential","tags":["Credentials"]}},"/api/v1/identities/{identityId}/invitation":{"post":{"description":"Nominates an address as this mailbox's recovery address and mails it one code. If the mailbox has NO password credential the code sets the first password and verifies the address in the same act (7 days); if it already has one, the code is an ordinary 24-hour confirmation code that sets nothing and can only be spent from the mailbox's own session. Never re-sent automatically: calling again replaces the outstanding invitation with a fresh code. Callable with an account key or a system key.","operationId":"post_MailboxInvitationCreate","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"description":"The address to nominate as this mailbox's recovery address, and to mail the code to","maxLength":320,"minLength":3,"type":"string"},"surface":{"description":"The hostname to tell the recipient to sign in at, e.g. webmail.open.email. Printed as a bare hostname and never as a link (§XVII.7): a user being invited has never been here, and a code with no destination is a dead end","maxLength":64,"type":"string"}},"required":["email"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryInvitationSent"}}},"description":"Which message went out, and whether the address was kept"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed; or recovery_address_self, meaning the address reaches the mailbox it would recover, which is a closed loop"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"recovery_disabled: the account's policy is admin_only AND the mailbox already has a password, so there is nothing an invitation could do that the policy permits"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"recovery_address_verified: this mailbox already has a VERIFIED recovery address. Re-pointing one is PUT /recovery, which re-proves the mailbox's password; an invitation may only nominate where there is nothing to displace"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited: too many invitations for this mailbox, or too much mail to that destination","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"recovery_mail_unavailable: the code could not be sent for a reason on the platform's side (the mail binding is unconfigured, the sending service refused the message, or the directory of the mailbox's own account could not answer whether the address routes back to the mailbox), so nothing was stored and the call may be retried. A refusal that concerns the recipient's own address is deliberately indistinguishable from a sent code. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Invite a mailbox user to set their own password","tags":["Credentials"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/password":{"put":{"description":"Updates the login password for a mailbox by verifying the existing password.","operationId":"put_PasswordChange","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"currentPassword":{"maxLength":1024,"minLength":1,"type":"string"},"newPassword":{"maxLength":1024,"minLength":8,"type":"string"}},"required":["currentPassword","newPassword"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordChanged"}}},"description":"Password updated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — new password too short"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_current_password"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"no_password_credential — mailbox has no password credential to change"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited — too many password change attempts","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Change mailbox login password","tags":["Credentials"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/password/reset":{"post":{"description":"Sets a new password on every password credential the mailbox has, creating one if it has none (named after the primary address, or the group address for a group persona), and revokes every expiring credential (browser sessions) so nothing minted before the reset survives it. App passwords are kept unless revokeAppPasswords is set. The mailbox is notified. Callable with an account key or a system key; a mailbox's own bearer uses PUT /password instead, which proves the current password.","operationId":"post_MailboxPasswordReset","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"newPassword":{"description":"The password to set","maxLength":1024,"minLength":8,"type":"string"},"revokeAppPasswords":{"description":"Revoke the mailbox's non-expiring app passwords too. Off by default, on when the reset is a response to a compromise rather than to a forgotten password","type":"boolean"}},"required":["newPassword"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryCompleted"}}},"description":"What the reset changed and what it invalidated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"no_username — the identity has no password credential to rotate and no address (primary or group) to name a new one after; nothing was changed. Create the login with POST /credentials and an explicit username"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Reset a mailbox password as an administrator","tags":["Credentials"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/recovery":{"put":{"description":"Stores an address as PENDING and mails it an 8-character confirmation code, valid for 24 hours. A pending address is never a reset target, and any address already verified keeps working until the new one is confirmed. Requires the current password.","operationId":"put_RecoveryAddressSet","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"address":{"description":"The address to send recovery mail to","maxLength":320,"minLength":3,"type":"string"},"currentPassword":{"description":"The mailbox's current password, re-proved","maxLength":1024,"minLength":1,"type":"string"}},"required":["address","currentPassword"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryAddressPending"}}},"description":"The address is pending confirmation"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed; password_required; or recovery_address_self, meaning the address reaches the mailbox it would recover, which is a closed loop"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_password; or recovery_disabled, meaning the account's policy is admin_only"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"no_password_credential: the mailbox has no password to re-prove"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited: too many address changes, or too much mail to that destination","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"recovery_mail_unavailable: the confirmation code could not be sent for a reason on the platform's side (the mail binding is unconfigured, the sending service refused the message, or the directory of the mailbox's own account could not answer whether the address routes back to the mailbox), so nothing was stored and the call may be retried. Refused rather than stored, because a permanently pending address is worse than no address. A refusal that concerns the recipient's own address is deliberately indistinguishable from a sent code. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Set the mailbox's recovery address","tags":["Credentials"],"x-max-json-body-bytes":1048576},"get":{"description":"Reports whether this mailbox has a verified recovery address and how many recovery codes remain. The address is masked for every principal except system.","operationId":"get_RecoveryStatusRead","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryStatus"}}},"description":"Recovery posture"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Read mailbox recovery posture","tags":["Credentials"]},"delete":{"description":"Removes the verified address and any pending one, and notifies both the mailbox and the address being removed. The mailbox's own bearer must re-prove the current password; an account admin need not, because they cannot know it. Recovery codes are untouched.","operationId":"delete_RecoveryAddressDelete","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"currentPassword":{"description":"The mailbox's current password. Required for the mailbox's own bearer, ignored for an account admin","maxLength":1024,"minLength":1,"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryAddressDeleted"}}},"description":"The address is gone, or there was none"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"password_required, for the mailbox's own bearer"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_password"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"no_password_credential: the mailbox's own bearer has no password to re-prove"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited: too many password re-proofs for this mailbox (every guess spends budget, right or wrong)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove the mailbox's recovery address","tags":["Credentials"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/recovery/confirm":{"post":{"description":"Spends the mailed confirmation code and promotes the pending address to verified. A newly verified address that REPLACES one may receive notices but cannot drive a reset for 72 hours; the first address on a mailbox is usable at once.","operationId":"post_RecoveryAddressConfirm","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"description":"The 8-character code mailed to the pending address","maxLength":64,"minLength":1,"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryAddressVerified"}}},"description":"The address is verified"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed; or no_pending_address, meaning nothing is awaiting confirmation or it expired. One answer for both, so this cannot report whether an address is pending"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_code, with attemptsLeft; or confirmation_cleared, meaning that was the fifth wrong code and the pending address was dropped. Set it again"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Confirm the mailbox's pending recovery address","tags":["Credentials"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/recovery/codes":{"post":{"description":"Issues a fresh set of ten single-use recovery codes and returns the plaintext exactly once, invalidating any previous set. Requires the current password.","operationId":"post_RecoveryCodesCreate","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"currentPassword":{"description":"The mailbox's current password, re-proved","maxLength":1024,"minLength":1,"type":"string"}},"required":["currentPassword"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryCodesIssued"}}},"description":"The codes, shown once"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed or password_required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_password: the current password did not match. Or recovery_disabled: the account's policy is admin_only"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"no_password_credential: the mailbox has no password to re-prove, so it cannot pass the sudo gate"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited: too many password re-proofs for this mailbox (every guess spends budget, right or wrong)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Issue mailbox recovery codes","tags":["Credentials"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/webauthn/registrations":{"post":{"description":"Generates a WebAuthn challenge and registration options to enroll a new hardware security key or passkey for 2-factor authentication. A mailbox bearer or system key acting under its credential must re-prove the current password when an active password credential exists. Account and unacted system administrators, and password-less provisioning, are exempt.","operationId":"post_WebauthnRegisterBegin","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"currentPassword":{"description":"The mailbox's current password. Required for a mailbox session (including a relayed session) when an active password exists; omitted for administrators or password-less provisioning","maxLength":1024,"minLength":1,"type":"string"},"rpId":{"description":"Relying Party ID (domain hostname)","maxLength":253,"minLength":1,"type":"string"}},"required":["rpId"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebauthnRegistrationOptions"}}},"description":"WebAuthn creation options to pass to navigator.credentials.create()"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"password_required: a mailbox session must re-prove its active password"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_password"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"no_password_credential: the password was removed during re-proof; restart registration"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Begin WebAuthn security key registration","tags":["Credentials"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/webauthn/credentials":{"post":{"description":"Verifies the browser WebAuthn attestation response and stores the enrolled security key.","operationId":"post_WebauthnRegisterFinish","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"description":"User-chosen label for the security key (e.g. 'YubiKey 5')","maxLength":128,"type":"string"},"origin":{"description":"Origin URL of the web page where ceremony took place","maxLength":1024,"type":"string"},"response":{"properties":{"attestationObject":{"description":"Base64url-encoded attestationObject","maxLength":65536,"type":"string"},"clientDataJSON":{"description":"Base64url-encoded clientDataJSON","maxLength":65536,"type":"string"},"transports":{"description":"Supported authenticator transports (e.g. ['usb', 'nfc'])","items":{"maxLength":32,"type":"string"},"maxItems":8,"type":"array"}},"required":["clientDataJSON","attestationObject"],"type":"object"},"rpId":{"description":"Relying Party ID (domain hostname)","maxLength":253,"minLength":1,"type":"string"}},"required":["rpId","origin","response"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebauthnCredential"}}},"description":"Enrolled security key details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_origin, challenge_expired, webauthn_failed, or duplicate_credential"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Finish WebAuthn security key registration","tags":["Credentials"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns all enrolled WebAuthn hardware keys and passkeys for a mailbox.","operationId":"get_WebauthnCredentialList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"credentials":{"items":{"$ref":"#/components/schemas/WebauthnCredential"},"type":"array"}},"required":["credentials"],"type":"object"}}},"description":"List of enrolled keys"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List enrolled WebAuthn security keys","tags":["Credentials"]}},"/api/v1/identities/{identityId}/webauthn/credentials/{webauthnId}":{"delete":{"description":"Deletes an enrolled WebAuthn security key from a mailbox. The mailbox's own bearer must re-prove the current password (removing the second factor is how a stolen session would downgrade the account); an account admin need not, because they cannot know it and removing a lost key is their remedy.","operationId":"delete_WebauthnCredentialDelete","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"WebAuthn key ULID identifier","in":"path","name":"webauthnId","required":true,"schema":{"description":"WebAuthn key ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"currentPassword":{"description":"The mailbox's current password. Required for the mailbox's own bearer, ignored for an account admin","maxLength":1024,"minLength":1,"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"description":"Security key removed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"password_required, for the mailbox's own bearer"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_password"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or key not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"no_password_credential: the mailbox's own bearer has no password to re-prove"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited: too many password re-proofs for this mailbox (every guess spends budget, right or wrong)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove an enrolled WebAuthn security key","tags":["Credentials"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/clients":{"get":{"description":"Where this identity has been reached from: one row per (protocol, network, credential), newest first, up to 200 tuples over the last 30 days. Self-service: the identity's own credential may read its own list — under the same `full`-scope rule as the credential list, because the rows name every other credential and the networks it is used from, which a leaked read-scoped token must not learn. A null `country` means nobody looked, not an unknown location; mail-protocol rows carry null until the fleet resolves locations.","operationId":"get_IdentityClientList","parameters":[{"description":"Identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID","type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"clients":{"items":{"$ref":"#/components/schemas/IdentityClient"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["clients"],"type":"object"}}},"description":"Page of clients, newest first"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_cursor for a cursor that is not one this list issued"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"credential_scope: the credential is scoped below `full`"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Identity not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List an identity's clients","tags":["Credentials"]}},"/api/v1/domains":{"post":{"description":"Adds a domain to an account and checks DNS verification records (TXT, MX, SPF, DKIM) to activate sending and receiving.","operationId":"post_DomainCreate","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"accountId":{"description":"Owning account ULID (required for system callers; ignored for account callers)","type":["string","null"]},"aliasOf":{"description":"Primary domain to alias (all mail rewrites to target domain)","minLength":3,"type":"string"},"dav":{"description":"Enable CalDAV/CardDAV autodiscovery DNS checks","type":"boolean"},"dmarc":{"description":"Aggregate DMARC report-ingestion domain (system callers only)","type":"boolean"},"domain":{"description":"Domain name (e.g. 'example.com')","minLength":3,"type":"string"},"enabled":{"description":"Whether the domain is active (default true)","type":"boolean"},"fbl":{"description":"Report-ingestion domain for feedback loops (system callers only)","type":"boolean"},"itip":{"description":"File arriving calendar invitations, cancellations and replies into the recipient's calendar, and let CalDAV clients schedule through the server (default true). False leaves arriving invitations as ordinary mail","type":"boolean"},"jmap":{"description":"Enable JMAP autodiscovery DNS checks","type":"boolean"},"receiveOnly":{"description":"The RECEIVE-ONLY mode (default false), the mirror of `sendOnly`: the domain receives here and its outbound mail goes through somebody else, so `/dns/check` omits the bounce CNAME and both DKIM records — from the checklist AND the verdict — and sending can never be activated. Mutually exclusive with `sendOnly`.","type":"boolean"},"sendOnly":{"description":"The SEND-ONLY mode (default false): the tenant sends as the domain while its inbound MX stays at another provider — every locality decision treats the domain as external (mail from the platform to it relays to its own MX, group members there are remote forwards, `/dns/check` omits the MX record), and mail arriving at our MX for it is refused `receiving_disabled`.","type":"boolean"},"sendVerified":{"description":"Mark the send records as already proven (system callers only — ignored otherwise: sending is EARNED by this call's own DNS check, so an account body asking for it still converges)","type":"boolean"},"srs":{"description":"SRS bounce-return namespace domain — SRS0=/SRS1= local parts relay DSNs back through the forwarding cluster (system callers only)","type":"boolean"},"subaddressing":{"description":"Whether `+` is a tag delimiter on this domain (default true): mail to `alice+anything@` reaches `alice@` and `alice+*@` is a permitted sender family. False makes `+` an ordinary character — no stripping, no tag recorded, no `+*` family advertised. Read from the canonical domain: inert on an alias","type":"boolean"}},"required":["domain"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Domain"},{"properties":{"records":{"items":{"$ref":"#/components/schemas/DnsRecordCheck"},"type":"array"}},"required":["records"],"type":"object"}]}}},"description":"The domain — created, or an existing row the caller owns advanced through a fresh DNS check (a re-POST is the onboarding loop, never a conflict) — plus every DNS record to publish with its live check result. Sending activates automatically once the send records are live"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed - the body is strict, so an UNRECOGNIZED field (a retired spelling such as the pre-0062 `canSend`/`canReceive`) is refused rather than ignored; invalid_domain - the name or aliasOf fails D3 canonicalization (not a convertible, LDH-valid domain; a non-xn label with hyphens at UTS 46 positions 3-4) or D5 (a label whose Unicode form mixes Latin with Cyrillic or Greek); domain_not_verified - the response's `record` field is the exact ownership TXT to publish, so publish it and POST again; account_required or unknown_account (system caller naming the owner); send_receive_exclusive (sendOnly and receiveOnly together describe a domain the platform does nothing for); or an invalid aliasOf: alias_self, unknown_domain, alias_cross_account, alias_chain, alias_fbl_exclusive"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"ingestion_not_writable: fbl, dmarc and srs turn the whole domain into a report-ingestion sink and are operator state; only a system caller may turn one on. Re-sending the value the domain already carries (as well as false, or omitting them) is unaffected; domain_blocked — the domain, or a parent of it, is on the platform blocklist (migration 0070): refused on the create path only and after proof of control, so an already-registered domain keeps advancing and an unproven caller still sees domain_not_verified"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"domain_claimed_elsewhere (the caller proved control, but another account holds the domain — an operator must transfer it), domain_unavailable (identical for every other conflict — no tenant enumeration), account_deleted, alias_conflict, or domain_transition_in_progress (retry after the registration settles)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"upstream_unavailable — domain lifecycle transition unavailable"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"verification_unavailable — DNS could not be queried, so control could not be proven either way. Retryable; nothing was created. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Register or verify a domain","tags":["Domains"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns a paginated list of domains owned by this account with optional mailbox counts and sampled storage metrics. A SYSTEM caller lists every domain on the deployment, and may narrow to one tenant with `accountId`.","operationId":"get_DomainList","parameters":[{"description":"System callers only: list just this account's domains (ignored for account principals, which always see their own)","in":"query","name":"accountId","required":false,"schema":{"description":"System callers only: list just this account's domains (ignored for account principals, which always see their own)","type":"string"}},{"description":"Set to 'true' to include mailbox counts per domain","in":"query","name":"mailboxCounts","required":false,"schema":{"description":"Set to 'true' to include mailbox counts per domain","enum":["true","false"],"type":"string"}},{"description":"Set to 'true' to include sampled storage usage metrics per domain","in":"query","name":"usage","required":false,"schema":{"description":"Set to 'true' to include sampled storage usage metrics per domain","enum":["true","false"],"type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"domains":{"items":{"$ref":"#/components/schemas/Domain"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["domains"],"type":"object"}}},"description":"Page of domains"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List domains","tags":["Domains"]}},"/api/v1/domains/{domain}":{"get":{"description":"Returns configuration, status, and DNS capabilities for a specific domain.","operationId":"get_DomainGet","parameters":[{"description":"Domain name (e.g. 'example.com')","in":"path","name":"domain","required":true,"schema":{"description":"Domain name (e.g. 'example.com')","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}},"description":"Domain details"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get domain details","tags":["Domains"]},"patch":{"description":"Updates domain configuration flags (enabled, sending/receiving, alias targets, autodiscovery protocols).","operationId":"patch_DomainUpdate","parameters":[{"description":"Domain name (e.g. 'example.com')","in":"path","name":"domain","required":true,"schema":{"description":"Domain name (e.g. 'example.com')","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"aliasOf":{"description":"Target domain to alias, or null to remove alias","minLength":3,"type":["string","null"]},"dav":{"description":"Enable CalDAV/CardDAV autodiscovery checks","type":"boolean"},"dmarc":{"description":"Aggregate DMARC report ingestion (enabling is system-only)","type":"boolean"},"dnsStatus":{"description":"Manual DNS status override (system callers only)","properties":{"dav":{"type":"boolean"},"dkim":{"type":"boolean"},"dmarc":{"type":"boolean"},"jmap":{"type":"boolean"},"mx":{"type":"boolean"},"spf":{"type":"boolean"}},"type":["object","null"]},"enabled":{"description":"Whether the domain is active","type":"boolean"},"fbl":{"description":"Feedback loop report ingestion (enabling is system-only)","type":"boolean"},"itip":{"description":"File arriving calendar invitations, cancellations and replies into the recipient's calendar, and let CalDAV clients schedule through the server. False leaves arriving invitations as ordinary mail","type":"boolean"},"jmap":{"description":"Enable JMAP autodiscovery checks","type":"boolean"},"receiveOnly":{"description":"The RECEIVE-ONLY mode — see the create description. `true` drops the send-authentication records from this domain's checklist and verdict; `false` asks for them again. Mutually exclusive with `sendOnly`.","type":"boolean"},"sendHold":{"anyOf":[{"enum":["disabled","paused"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"Operator enforcement (system callers only). 'disabled' STOPS sending: 403 sending_disabled, a permanent 550 at smtp-in, the queued backlog bounced. 'paused' HOLDS it: 429 sending_paused + Retry-After, a 451 the sending MTA queues, the backlog deferred. null lifts either. Egress only: a held domain still receives. Applies to work already accepted as well: a send in progress stops before its remaining recipients, and queued group fan-out, member deliveries, destination webhooks and forwarding legs from this sender's submissions are deferred under 'paused' and dropped under 'disabled'. Already-queued fan-out legs may run for up to 10 seconds after the change. A retry with the same X-Delivery-Id is refused while the hold is set."},"sendOnly":{"description":"The SEND-ONLY mode — see the create description. `true` makes the domain's own MX the authority for its mail everywhere on the platform; `false` receives here again.","type":"boolean"},"sendVerified":{"description":"The send-records verdict (system callers only, in both directions). Owners earn it by publishing DNS and re-POSTing /domains; an operator may assert or revoke it outright","type":"boolean"},"srs":{"description":"SRS bounce-return namespace (enabling is system-only)","type":"boolean"},"subaddressing":{"description":"Whether `+` is a tag delimiter on this domain. Owner-writable in both directions. Read from the canonical domain: inert on an alias","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}},"description":"Updated domain"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed (the body is strict: an unrecognized field is refused, never silently dropped), empty_patch, invalid_domain (an aliasOf that fails D3 canonicalization or D5's mixed-script refusal), send_receive_exclusive (the post-patch state would be both sendOnly and receiveOnly), alias_self, unknown_domain (alias target), alias_cross_account (system caller: the target belongs to a different account than the alias domain), alias_chain, or alias_fbl_exclusive"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"sending_not_writable: `sendVerified` and `sendHold` are operator state — account callers earn sending by publishing DNS and re-POSTing /domains, and a hold its owner could lift is not a hold. Refused for ANY value of either from a non-system caller. ingestion_not_writable: the fbl/dmarc ingestion flags are operator state, so only a system caller may turn one on (an owner may turn them off, and may re-send an unchanged value; a re-send racing an operator's revoke is refused, never re-enabled, and then nothing else in the patch is applied either). dns_status_not_writable, dnsStatus is the platform's resolved verdict, written by POST /domains/:domain/dns/check"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"domain_in_use, domain_is_alias_target, alias_fbl_exclusive, alias_conflict, account_deleted, or domain_transition_in_progress"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"upstream_unavailable — domain lifecycle transition unavailable"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update domain settings","tags":["Domains"],"x-max-json-body-bytes":1048576},"delete":{"description":"Removes a domain from an account after all routes and aliases referencing it have been cleared.","operationId":"delete_DomainDelete","parameters":[{"description":"Domain name (e.g. 'example.com')","in":"path","name":"domain","required":true,"schema":{"description":"Domain name (e.g. 'example.com')","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Domain deleted successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"domain_has_routes, domain_has_patterns, domain_is_alias_target, domain_has_hostnames, account_deleted, or domain_transition_in_progress (retry after the domain's pending change settles)"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"upstream_unavailable: the domain's lifecycle transition is unavailable"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete a domain","tags":["Domains"]}},"/api/v1/domains/{domain}/dns/check":{"post":{"description":"Queries live DNS for required records (MX, SPF, DKIM CNAMEs, DMARC, SRV) and returns validation status and required values.","operationId":"post_DomainDnsCheck","parameters":[{"description":"Domain name (e.g. 'example.com')","in":"path","name":"domain","required":true,"schema":{"description":"Domain name (e.g. 'example.com')","type":"string"}},{"description":"Set to 'true' to bypass the cached verdict and re-query live nameservers. A live check is a dozen DNS questions, so forced checks are rate limited per account; a refused one answers 429. An unforced poll is bounded by the verdict cache instead and is never refused","in":"query","name":"force","required":false,"schema":{"description":"Set to 'true' to bypass the cached verdict and re-query live nameservers. A live check is a dozen DNS questions, so forced checks are rate limited per account; a refused one answers 429. An unforced poll is bounded by the verdict cache instead and is never refused","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDnsCheck"}}},"description":"DNS record verification results and instructions"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited — too many FORCED checks for this account. Only `force=true` is counted; an ordinary client polling through propagation is bounded by the verdict cache and never sees this","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Check domain DNS records","tags":["Domains"]}},"/api/v1/domains/{domain}/branding":{"put":{"description":"Updates or clears the white-label display brand name for a domain.","operationId":"put_DomainBrandingUpdate","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainBrandingPatch"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainBranding"}}},"description":"Updated branding details"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update domain brand name","tags":["Domains"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns white-label branding configuration (brand name and logo metadata) for a domain.","operationId":"get_DomainBrandingGet","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainBranding"}}},"description":"Domain branding details"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get domain branding","tags":["Domains"]}},"/api/v1/domains/{domain}/logo":{"put":{"description":"Uploads a raw image file (PNG, JPEG, WebP, SVG) to set as the white-label logo for a domain.","operationId":"put_DomainLogoUpdate","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}},{"description":"Body size in bytes (required)","in":"header","name":"content-length","required":false,"schema":{"description":"Body size in bytes (required)","type":"string"}},{"description":"Image MIME type (image/png, image/jpeg, image/webp, image/svg+xml)","in":"header","name":"content-type","required":false,"schema":{"description":"Image MIME type (image/png, image/jpeg, image/webp, image/svg+xml)","type":"string"}}],"requestBody":{"content":{"application/octet-stream":{"schema":{"description":"Raw image file bytes","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainBranding"}}},"description":"Logo uploaded successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"empty_body"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Content-Length header required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Image exceeds maximum allowed logo size limit"},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unsupported_media_type"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Upload domain logo","tags":["Domains"]},"delete":{"description":"Deletes the stored white-label logo image for a domain.","operationId":"delete_DomainLogoDelete","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Logo removed successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete domain logo","tags":["Domains"]}},"/api/v1/branding/{domain}":{"get":{"description":"Returns public branding metadata (brand name and logo info) for login page custom styling. No credential: a login screen needs this before anyone signs in. An unknown domain and an unbranded one answer the same 404.","operationId":"get_PublicBrandingGet","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBranding"}}},"description":"Published branding metadata"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No published branding or domain not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"security":[],"summary":"Get public branding for domain","tags":["Domains"]}},"/api/v1/branding/{domain}/logo":{"get":{"description":"Returns raw image bytes for a domain's published white-label logo. No credential: a login screen needs this before anyone signs in.","operationId":"get_PublicBrandingLogoGet","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}},{"description":"Revalidation ETag from previous response","in":"header","name":"if-none-match","required":false,"schema":{"description":"Revalidation ETag from previous response","type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"description":"Raw image bytes","type":"string"}}},"description":"Logo image bytes","headers":{"ETag":{"description":"Content hash for revalidation; send it back as If-None-Match","schema":{"type":"string"}}}},"304":{"description":"Not modified (If-None-Match matched)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No published logo or domain not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"security":[],"summary":"Get public logo image","tags":["Domains"]}},"/api/v1/branding/by-host/{host}":{"get":{"description":"Returns public branding metadata associated with a custom webmail hostname. No credential: a login screen needs this before anyone signs in.","operationId":"get_PublicBrandingByHostGet","parameters":[{"description":"Custom webmail hostname (e.g. mail.example.com)","in":"path","name":"host","required":true,"schema":{"description":"Custom webmail hostname (e.g. mail.example.com)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBrandingByHost"}}},"description":"Published branding and associated domain"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No domain claims this hostname"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"security":[],"summary":"Get public branding by hostname","tags":["Domains"]}},"/api/v1/domains/{domain}/hostnames/{service}":{"put":{"description":"Claims and verifies a custom vanity subdomain for a specific protocol service (mail, smtp, webmail, dav, mx).","operationId":"put_DomainHostnameSet","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}},{"description":"Which client-facing service the hostname fronts","in":"path","name":"service","required":true,"schema":{"description":"Which client-facing service the hostname fronts","enum":["mail","smtp","webmail","dav","mx"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"hostname":{"description":"Subdomain FQDN to claim (e.g. 'mail.example.com')","maxLength":253,"minLength":1,"type":"string"}},"required":["hostname"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainHostnameList"}}},"description":"Hostname claim and verification status"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_hostname, hostname_not_subdomain, hostname_reserved, or hostname_in_foreign_domain"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"vanity_hosts_disabled — not enabled for this account"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"hostname_taken, service_unavailable, or domain_is_alias"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Configure vanity hostname","tags":["Domains"],"x-max-json-body-bytes":1048576},"delete":{"description":"Releases a custom vanity hostname and removes its provisioned SSL certificates.","operationId":"delete_DomainHostnameDelete","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}},{"description":"Which client-facing service the hostname fronts","in":"path","name":"service","required":true,"schema":{"description":"Which client-facing service the hostname fronts","enum":["mail","smtp","webmail","dav","mx"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Hostname released successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found, or no hostname claimed for this service"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"upstream_unavailable — Cloudflare custom hostname could not be removed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete vanity hostname","tags":["Domains"]}},"/api/v1/domains/{domain}/hostnames":{"get":{"description":"Returns custom vanity hostnames (mail, SMTP, webmail, CalDAV, MX) configured for a domain and their verification status.","operationId":"get_DomainHostnamesGet","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainHostnameList"}}},"description":"List of all vanity hostname slots and verification status"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get vanity hostnames for domain","tags":["Domains"]}},"/api/v1/domains/{domain}/hostnames/check":{"post":{"description":"Re-verifies DNS CNAME and SSL certificate status for all vanity hostnames on a domain.","operationId":"post_DomainHostnamesCheck","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}},{"description":"Set to 'true' to bypass cache and re-query live DNS and certificate status","in":"query","name":"force","required":false,"schema":{"description":"Set to 'true' to bypass cache and re-query live DNS and certificate status","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainHostnameList"}}},"description":"Every service slot with the refreshed verification verdict"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Check vanity hostnames status","tags":["Domains"]}},"/api/v1/domains/{domain}/event-webhook":{"put":{"description":"One URL per domain, all events, no filters. Mailboxes on the domain start feeding it within seconds (a background walk arms them) — take a baseline first and treat the first batches as deltas. Any PUT re-enables, and re-runs the arm walk: it is the recovery if a walk ever died mid-domain (visible as a dead_lettered `arm:<domain>` row in the delivery log). What your endpoint receives (payload, `X-OpenEmail-Signature` scheme, retry policy) is specified as `event-batch` in this document's top-level `webhooks` section.","operationId":"put_DomainEventWebhookSet","parameters":[{"description":"Domain name","in":"path","name":"domain","required":true,"schema":{"description":"Domain name","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"secret":"whsec_5e8a1c9f2b7d4e6a8c1f3b5d7e9a2c4f","url":"https://hooks.acme.example/openemail"},"schema":{"properties":{"secret":{"description":"HMAC signing secret — write-only. Omit to keep, string to set, null to clear","maxLength":256,"minLength":1,"type":["string","null"]},"url":{"description":"HTTPS endpoint on a public host","format":"uri","type":"string"}},"required":["url"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventWebhook"}}},"description":"The hook"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — URL refused"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_required: the domain has no owning account, and a hook row must reference one (the legacy directory; once the partitioned directory answers, a platform domain's hook is accepted for the system caller)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create or replace the domain's event webhook","tags":["Domains"],"x-max-json-body-bytes":1048576},"get":{"description":"The domain-scope event webhook: every mailbox whose primary address is on the domain feeds it, plus the domain's directory lifecycle and send outcomes. The signing secret is write-only.","operationId":"get_DomainEventWebhookGet","parameters":[{"description":"Domain name","in":"path","name":"domain","required":true,"schema":{"description":"Domain name","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventWebhook"}}},"description":"The hook"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No hook configured, or domain not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Read the domain's event webhook","tags":["Domains"]},"delete":{"description":"Deletes the hook: event batches for the domain's mailboxes stop and nothing is retained. Mailboxes with their OWN hook keep feeding it (the background walk recomputes each mailbox's arming). Re-creating the hook later starts fresh; re-sync per mailbox rather than expecting a backlog.","operationId":"delete_DomainEventWebhookDelete","parameters":[{"description":"Domain name","in":"path","name":"domain","required":true,"schema":{"description":"Domain name","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Removed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No hook configured, or domain not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove the domain's event webhook","tags":["Domains"]}},"/api/v1/domains/{domain}/event-webhook/test":{"post":{"description":"Queues one `webhook.test` batch through the real delivery path. The outcome shows on the resource and in the traffic log.","operationId":"post_DomainEventWebhookTest","parameters":[{"description":"Domain name","in":"path","name":"domain","required":true,"schema":{"description":"Domain name","type":"string"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventWebhookTestResult"}}},"description":"Test batch queued"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No hook configured, or domain not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Send a test event to the domain's event webhook","tags":["Domains"]}},"/api/v1/domains/{domain}/dmarc":{"get":{"description":"Returns aggregated DMARC statistics, authentication pass/fail totals, top sending sources, and policy enforcement readiness.","operationId":"get_DomainDmarc","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}},{"description":"Reporting window (how far back)","in":"query","name":"range","required":false,"schema":{"default":"30d","description":"Reporting window (how far back)","enum":["7d","30d","90d"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDmarc"}}},"description":"Totals, readiness verdict, and busiest sources over the time window"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — unknown window value"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get DMARC report summary","tags":["Domains"]}},"/api/v1/domains/{domain}/dmarc/reports":{"get":{"description":"Returns a paginated list of ingested XML DMARC aggregate reports from receiving mail providers.","operationId":"get_DomainDmarcReports","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}},{"description":"Maximum reports per page","in":"query","name":"limit","required":false,"schema":{"description":"Maximum reports per page","maximum":200,"minimum":1,"type":"integer"}},{"description":"Pagination cursor","in":"query","name":"cursor","required":false,"schema":{"description":"Pagination cursor","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDmarcReports"}}},"description":"Page of ingested DMARC reports"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List ingested DMARC reports","tags":["Domains"]}},"/api/v1/domains/{domain}/dmarc/sources":{"get":{"description":"Returns sending IP sources and organizations claiming this domain, classified by SPF/DKIM alignment.","operationId":"get_DomainDmarcSources","parameters":[{"description":"Customer domain name (e.g. example.com)","in":"path","name":"domain","required":true,"schema":{"description":"Customer domain name (e.g. example.com)","type":"string"}},{"description":"Reporting window (how far back)","in":"query","name":"range","required":false,"schema":{"default":"30d","description":"Reporting window (how far back)","enum":["7d","30d","90d"],"type":"string"}},{"description":"Maximum sources to return (default 100)","in":"query","name":"limit","required":false,"schema":{"default":100,"description":"Maximum sources to return (default 100)","maximum":500,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDmarcSources"}}},"description":"Aggregated sending sources"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List DMARC sending sources","tags":["Domains"]}},"/api/v1/domains/{domain}/usage":{"get":{"description":"Returns daily storage usage trends for mailboxes associated with a specific domain.","operationId":"get_DomainUsageGet","parameters":[{"description":"Domain name (e.g. 'example.com')","in":"path","name":"domain","required":true,"schema":{"description":"Domain name (e.g. 'example.com')","type":"string"}},{"description":"First UTC day in YYYY-MM-DD format (default: 29 days ago)","in":"query","name":"from","required":false,"schema":{"description":"First UTC day in YYYY-MM-DD format (default: 29 days ago)","type":"string"}},{"description":"Last UTC day in YYYY-MM-DD format (default: today)","in":"query","name":"to","required":false,"schema":{"description":"Last UTC day in YYYY-MM-DD format (default: today)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainUsage"}}},"description":"Daily storage metrics for the domain, ascending by date"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed (malformed or inverted range, or exceeds 400 days)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get daily domain storage metrics","tags":["Domains"]}},"/api/v1/domains/{domain}/traffic":{"get":{"description":"Returns aggregated email volume and bytes by outcome and route kind over a time window for a domain.","operationId":"get_DomainTraffic","parameters":[{"description":"Domain name (e.g. 'example.com')","in":"path","name":"domain","required":true,"schema":{"description":"Domain name (e.g. 'example.com')","type":"string"}},{"description":"Time window range ('1h', '6h', '24h', '7d', '30d')","in":"query","name":"range","required":false,"schema":{"default":"24h","description":"Time window range ('1h', '6h', '24h', '7d', '30d')","enum":["1h","6h","24h","7d","30d"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainTraffic"}}},"description":"Counts and bytes by outcome and route kind over the time window"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — unknown range value"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"analytics_query_failed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"analytics_unavailable. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get domain traffic statistics","tags":["Domains"]}},"/api/v1/domains/{domain}/forward-usage":{"get":{"description":"Returns outbound email forwarding rate limit consumption (for group expansions and redirects) over the rolling 24-hour window for a domain. For an SRS bounce-return domain the isolated bounce-return budget is reported separately as `srsBounce`.","operationId":"get_DomainForwardUsageGet","parameters":[{"description":"Domain name (e.g. 'example.com')","in":"path","name":"domain","required":true,"schema":{"description":"Domain name (e.g. 'example.com')","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SendUsage"},{"properties":{"srsBounce":{"description":"The SRS bounce-return channel's own budget — present only when the domain carries the srs flag. Isolated from the forwarding budget above, because SRS-shaped mail is an unauthenticated trigger and must not be able to spend a tenant channel's allowance.","properties":{"messages":{"description":"Bounce-return relays spent in the rolling 24-hour window","type":"integer"},"msgsPerDay":{"description":"Daily bounce-return limit (null = unenforced)","type":["integer","null"]}},"required":["messages","msgsPerDay"],"type":"object"}},"type":"object"}]}}},"description":"Current forwarding limit usage and effective limits"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get domain forwarding rate limit usage","tags":["Domains"]}},"/api/v1/domains/{domain}/events":{"get":{"description":"Returns paginated detailed delivery events and attempt history for a domain with filtering by time range, outcome, source, mailbox, or the prepared email that sent it.","operationId":"get_DomainEvents","parameters":[{"description":"Domain name (e.g. 'example.com')","in":"path","name":"domain","required":true,"schema":{"description":"Domain name (e.g. 'example.com')","type":"string"}},{"description":"Time window range ('1h', '6h', '24h', '7d', '30d')","in":"query","name":"range","required":false,"schema":{"default":"24h","description":"Time window range ('1h', '6h', '24h', '7d', '30d')","enum":["1h","6h","24h","7d","30d"],"type":"string"}},{"description":"Filter by delivery outcome ('delivered', 'bounced', 'deferred', 'rejected', 'suppressed', 'dropped')","in":"query","name":"outcome","required":false,"schema":{"description":"Filter by delivery outcome ('delivered', 'bounced', 'deferred', 'rejected', 'suppressed', 'dropped')","enum":["delivered","duplicate","queued","filtered","rejected","bounced","deferred","relayed","relay_rejected","relay_suppressed","relay_indeterminate","relay_content_lost","webhook_delivered","webhook_route_gone","event_delivered","event_hook_disabled","event_hook_gone","member_skipped","member_failed","fbl_recorded","fbl_content_lost","dmarc_recorded","dmarc_content_lost","dmarc_unreadable","dmarc_unparseable","dmarc_rejected","dead_lettered","internal_error","check_refused","check_accepted","blob_missing","rate_limited","limiter_unavailable","auth_failed","storage_warning","mail_refused","mail_accepted"],"type":"string"}},{"description":"Filter by traffic source ('smtp_in', 'submission', 'forward', 'webhook', 'scheduled', 'pop3')","in":"query","name":"source","required":false,"schema":{"description":"Filter by traffic source ('smtp_in', 'submission', 'forward', 'webhook', 'scheduled', 'pop3')","enum":["inbound","outbound","sent_copy","append","expansion","relay","webhook","pickup","edge","fbl","dmarc","bounce","events","api","check","read","auth","store","platform_mail"],"type":"string"}},{"description":"'mail' shows only rows where a message moved — arrived, left, reached a member or a webhook route, was collected from another provider, or its sender was told it failed. 'all' (the default, so no client changes behaviour) adds the rows where the platform describes itself: IMAP uploads, Sent copies, report ingestion, event-webhook batches and the per-RCPT gate. A customer-facing delivery log wants 'mail' — one inbound message writes a gate row AND a delivery row, so 'all' counts it twice.","in":"query","name":"kind","required":false,"schema":{"default":"all","description":"'mail' shows only rows where a message moved — arrived, left, reached a member or a webhook route, was collected from another provider, or its sender was told it failed. 'all' (the default, so no client changes behaviour) adds the rows where the platform describes itself: IMAP uploads, Sent copies, report ingestion, event-webhook batches and the per-RCPT gate. A customer-facing delivery log wants 'mail' — one inbound message writes a gate row AND a delivery row, so 'all' counts it twice.","enum":["mail","all"],"type":"string"}},{"description":"Filter by exact delivery ID","in":"query","name":"deliveryId","required":false,"schema":{"description":"Filter by exact delivery ID","maxLength":640,"minLength":1,"type":"string"}},{"description":"Filter by mailbox ULID identifier","in":"query","name":"mailboxId","required":false,"schema":{"description":"Filter by mailbox ULID identifier","maxLength":64,"minLength":1,"type":"string"}},{"description":"Filter by envelope sender email address","in":"query","name":"envelopeFrom","required":false,"schema":{"description":"Filter by envelope sender email address","maxLength":320,"minLength":1,"type":"string"}},{"description":"Filter by the row's detail marker — e.g. 'junk' for messages the platform filed into Junk, or a failure reason like 'sender_blocked'.","in":"query","name":"detail","required":false,"schema":{"description":"Filter by the row's detail marker — e.g. 'junk' for messages the platform filed into Junk, or a failure reason like 'sender_blocked'.","maxLength":64,"minLength":1,"type":"string"}},{"description":"Filter to the rows a prepared email (tenant template) wrote, by its slug: the admission of each recipient, every relay attempt after it, and a dead letter if the attempts ran out. Each row names its template and language in `template`.","in":"query","name":"template","required":false,"schema":{"description":"Filter to the rows a prepared email (tenant template) wrote, by its slug: the admission of each recipient, every relay attempt after it, and a dead letter if the attempts ran out. Each row names its template and language in `template`.","maxLength":64,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","type":"string"}},{"description":"Maximum events per page","in":"query","name":"limit","required":false,"schema":{"default":50,"description":"Maximum events per page","maximum":200,"minimum":1,"type":"integer"}},{"description":"Pagination cursor","in":"query","name":"cursor","required":false,"schema":{"description":"Pagination cursor","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEvents"}}},"description":"Page of traffic delivery events"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed or invalid_cursor"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Domain not found or not accessible to this principal"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"analytics_query_failed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"analytics_unavailable. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Query domain delivery event log","tags":["Domains"]}},"/api/v1/identities":{"post":{"description":"An identity is a principal in an account: it owns stores (a mail store, calendars, contacts), holds credentials, and can be shared with. It takes one of two shapes at creation.\n\n**With primaryAddress** (the common case): the address is claimed and routed to the identity atomically, the mail store is bound, and the initial labels are provisioned. The identity receives mail at once and logs in with the address as its username.\n\n**With withoutAddress: true**: no email address and no mail store, so it receives no mail and every mail route (messages, labels, uploads, search, filters, sharing) answers 404 for it, while the identity routes (credentials, settings, delete and restore) and its calendars and contacts work as for any identity. There is no login until a credential is minted with an explicit username (POST /api/v1/identities/{identityId}/credentials), since there is no address to default to; the username is a bare name without @. Routing an address to it later (POST /api/v1/routes or /api/v1/patterns, destinationType mailbox, or a retarget of either) gives it a mail store in that write, and it then receives mail like any other identity; nothing undoes that, a later route delete included. semantic: true is refused on it (400 no_mail_store), since there is no mail to index. Until then it holds events, tasks and contacts and takes part in sharing, but not in scheduling: iCalendar names participants by mailto: address, so it can neither invite nor be invited.\n\nA create with neither is refused 400 primary_address_required; both together is 400 without_address_has_address.\n\n**receiveHold** creates the mailbox already holding its receiving (paused or disabled), committed with the identity and its address so it applies from the first arrival; the answer carries receiveHold, receiveHoldAt and receiveHoldPending as GET does. On a withoutAddress create the hold is the identity's until an address is routed to it, and the mail store that write gives it holds from its first arrival.\n\n**messageWebhook and eventWebhook** configure, in the same request, the mailbox's message webhook (every message that lands in the mailbox, however it was routed, POSTed beside its normal delivery; managed afterwards at /api/v1/mailboxes/{mailboxId}/message-webhook) and the identity's mailbox-scope event webhook, so the identity never exists without them. Each is optional; with neither the request and answer are exactly as above. Both are an account's: a platform identity takes neither (409 account_required). A create naming either requires an `Idempotency-Key` header (1 to 128 characters), which names one creation: a retry with the same key and body answers the same identity as it now is, never re-applying either webhook over a later change; any other body under the key is refused 409 idempotency_key_reused; and an identity deleted since is never re-created (409 identity_deleted). A completed creation answers its key for 30 days, the retry window. The 200 comes once the identity, its route, each webhook and its mail store's arming are in place. Until then the answer is 503 temporary_failure with Retry-After, mail to the address is refused as temporary (SMTP 451) and the identity's calendar and contact writes too, and the setup completes in the background whether or not the request is retried. Nothing is sent to either URL at creation.","operationId":"post_IdentityCreate","requestBody":{"content":{"application/json":{"example":{"eventWebhook":{"secret":"whsec_events_3f6b8d1a9c4e2f7b","url":"https://hooks.acme.example/events"},"messageWebhook":{"format":"parsed","secret":"whsec_message_7c2e9a4f1b8d3e6a","url":"https://hooks.acme.example/incoming"},"primaryAddress":"agent@acme.example"},"schema":{"properties":{"accountId":{"description":"Owning account (system callers only; account callers always own their mailboxes)","type":"string"},"ephemeral":{"description":"Create the mailbox DISPOSABLE (#483): its DELETE destroys it at once — no undo record, no 7-day window, its object gone, the address free again immediately — the shape for a mailbox per support case, agent session or transaction. Fixed at creation and reported on every read; a PATCH naming it is refused 400 ephemeral_immutable in either direction, so a key cannot make a long-lived mailbox disposable after the fact. Omitted or false creates an ordinary mailbox. Refused 400 ephemeral_requires_account on a platform identity, which has no account home to destroy through","type":"boolean"},"eventWebhook":{"additionalProperties":false,"description":"The identity's mailbox-scope event webhook, as PUT /api/v1/mailboxes/{mailboxId}/event-webhook configures it: one URL, every supported event, batched and signed. Allowed with withoutAddress: true, for calendar and contact notifications. Requires an owning account (409 account_required on a platform identity). Manage it afterwards at /api/v1/mailboxes/{mailboxId}/event-webhook. Omitted or null configures none. Requires an Idempotency-Key","properties":{"secret":{"description":"HMAC signing secret, 1 to 256 characters, write-only. Omitted or null: unsigned","maxLength":256,"minLength":1,"type":["string","null"]},"url":{"description":"HTTPS endpoint on a public host","format":"uri","type":"string"}},"required":["url"],"type":["object","null"]},"messageWebhook":{"additionalProperties":false,"description":"The mailbox's message webhook: every message that lands in the mailbox is POSTed here (the incoming-email payload, its signing and retries) beside its normal delivery, however it got there: its primary address, any address routed to it later, a pattern or catch-all, a group, a forward, a delivery-status or platform notice. Requires a primaryAddress (400 message_webhook_requires_address with withoutAddress: true) and an owning account (409 account_required on a platform identity). Manage it afterwards at /api/v1/mailboxes/{mailboxId}/message-webhook. Omitted or null configures none. Requires an Idempotency-Key","properties":{"format":{"description":"The payload shape: parsed (the default) or reference (headers plus a capability rawUrl; 400 webhook_format_unavailable where the deployment mints none)","enum":["parsed","reference"],"type":["string","null"]},"secret":{"description":"HMAC signing secret, write-only. Omitted or null: the tap is unsigned","type":["string","null"]},"url":{"description":"HTTPS endpoint on a public host","format":"uri","type":"string"}},"required":["url"],"type":["object","null"]},"permittedRecipients":{"description":"System callers only. Outbound recipient allowlist: the ONLY addresses this mailbox may send to. Entries are exact addresses (`jo@acme.dev`) or domain wildcards (`*@acme.dev`). `null` = unrestricted (the default); `[]` = may send to nobody. At most 1,000 entries of at most 320 characters each (400 validation_failed otherwise); a list stored before these limits keeps working. A refused submission answers 403 recipient_not_permitted — permanent, so SMTP submission gets a 550. EGRESS ONLY: a restricted mailbox still receives from anyone","items":{"maxLength":320,"type":"string"},"maxItems":1000,"type":["array","null"]},"primaryAddress":{"description":"On create: CLAIMS the address - the address→mailbox route and the label are created atomically with the mailbox (409 address_taken if already routed); must be an ASCII local part on a non-alias directory domain owned by the mailbox's account (a U-label domain spelling is canonicalized to its stored A-label). On update: selects among the mailbox's already-routed addresses (bind first via POST /routes, which is idempotent); null clears the label","maxLength":320,"type":["string","null"]},"quotaBytes":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":["integer","null"]},"receiveHold":{"anyOf":[{"enum":["paused","disabled"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"Create the mailbox already holding its receiving: 'paused' (senders retry for about four to five days, then their mail bounces and is lost) or 'disabled' (mail to it is rejected at once). The hold commits with the identity and its address, so it applies from the first arrival. Omitted or null creates a receiving mailbox. The account owner's control, like PATCH receiveHold: refused 400 not_holdable on a platform identity, and 403 receive_hold_not_enabled from an account key while this deployment has not enabled it"},"semantic":{"description":"SEMANTIC (meaning-based) search for this mailbox (docs/semantic-search-design.md). true embeds every new message after delivery and, on an existing mailbox, backfills a recent window (the later of 12 months and the 20,000 most recent messages; older mail on request via semanticFloor); false DELETES the mailbox's embeddings. Requires the account's plan gate (403 semantic_not_enabled) and an open shard (503 semantic_capacity). Off by default","type":"boolean"},"semanticFloor":{"description":"'Index older mail': LOWERS the semantic backfill floor to this epoch second (null = the whole store). Never raises it. Requires semantic search to be on (409 semantic_not_enabled); refused on create, where the floor is the creation instant","format":"int64","type":["integer","null"]},"sendHold":{"anyOf":[{"enum":["disabled","paused"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"System callers only. Operator enforcement over this mailbox's outbound mail. 'disabled' STOPS it: every submission is refused 403 sending_disabled, queued relay jobs are dropped at the relay, and vacation auto-replies stop — permanent by contract, so SMTP submission gets a 550 and the mail bounces. 'paused' HOLDS it, the reversible form for a suspension you intend to lift (non-payment, an investigation): submissions answer 429 sending_paused with Retry-After, so SMTP submission gets a 451 and the sender's MTA queues the mail; queued relay jobs are DEFERRED rather than bounced. null lifts either. Does not affect receiving or reading. Applies to work already accepted as well: a send in progress stops before its remaining recipients, and queued group fan-out, member deliveries, destination webhooks and forwarding legs from this sender's submissions are deferred under 'paused' and dropped under 'disabled'. Already-queued fan-out legs may run for up to 10 seconds after the change. A retry with the same X-Delivery-Id is refused while the hold is set."},"sendMsgsPerDay":{"description":"System callers only. Distinct messages this mailbox may send per rolling 24h. null = the platform default; 0 = unlimited","maximum":9007199254740991,"minimum":0,"type":["integer","null"]},"sendMsgsPerHour":{"description":"System callers only. The BURST window: distinct messages this mailbox may send per hour (measured over the current and previous hourly bucket, so a refusal can hold for up to ~2h after a burst). null = the platform default; 0 = unlimited","maximum":9007199254740991,"minimum":0,"type":["integer","null"]},"sendRcptsPerDay":{"description":"System callers only. Envelope recipients this mailbox may send to per rolling 24h. null = the platform default; 0 = unlimited","maximum":9007199254740991,"minimum":0,"type":["integer","null"]},"sendRcptsPerHour":{"description":"System callers only. The BURST window: envelope recipients this mailbox may send to per hour. null = the platform default; 0 = unlimited","maximum":9007199254740991,"minimum":0,"type":["integer","null"]},"withoutAddress":{"default":false,"description":"Create the identity with no email address and no mail store: it receives no mail, and every mail route answers 404 for it; its calendars and contacts work as for any identity. An identity is created WITH a primaryAddress unless this is true: a create with neither is refused 400 primary_address_required, and true with a primaryAddress is refused 400 without_address_has_address, both before anything is written. Omitted or null is false. A domain-scoped api key never creates one: without an address it is refused 400 primary_address_required, withoutAddress or not. There is no login until a credential is minted with an explicit username, and routing an address to it later makes it receive mail like any other identity","type":["boolean","null"]}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"accountId":"01J9ACCT8B1D4F7H2K00000000","createdAt":1788264000,"ephemeral":false,"eventWebhook":{"consecutiveFailures":0,"createdAt":1788264000,"disabledReason":null,"enabled":true,"failingSince":null,"hasSecret":true,"lastDeliveredAt":null,"lastFailure":null,"lastFailureAt":null,"mailboxId":"01J9MBX7F4Q2K9T3W600000000","scope":"mailbox","updatedAt":1788264000,"url":"https://hooks.acme.example/events"},"groupAddress":null,"hasMailStore":true,"id":"01J9MBX7F4Q2K9T3W600000000","messageWebhook":{"createdAt":1788264000,"format":"parsed","hasSecret":true,"updatedAt":1788264000,"url":"https://hooks.acme.example/incoming"},"permittedRecipients":null,"primaryAddress":"agent@acme.example","quotaBytes":null,"receiveHold":null,"receiveHoldAt":null,"receiveHoldPending":false,"retentionDays":null,"semantic":false,"sendHold":null,"sendMsgsPerDay":null,"sendMsgsPerHour":null,"sendRcptsPerDay":null,"sendRcptsPerHour":null,"suspendedAt":null,"suspensionPending":false},"schema":{"$ref":"#/components/schemas/CreatedIdentity"}}},"description":"Created identity. With messageWebhook or eventWebhook it carries each, redacted, and answers only once the identity, its route and every requested webhook are configured and its mail store armed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, ephemeral_requires_account (ephemeral: true on a platform identity), unknown_account, invalid_address, unknown_domain, domain_is_alias, primary_address_required (no primaryAddress and withoutAddress not true; and a DOMAIN-SCOPED api key must create WITH an address on one of its domains, withoutAddress or not: a bare identity would be one it could never reach again, migration 0078), without_address_has_address (withoutAddress: true with a primaryAddress), no_mail_store (semantic: true with withoutAddress: true: no mail to index), not_holdable (receiveHold on a platform identity, which belongs to no account), message_webhook_requires_address (messageWebhook with withoutAddress: true), webhook_format_unavailable (messageWebhook.format reference on a deployment that mints no capability URLs), idempotency_key_required (messageWebhook or eventWebhook without an Idempotency-Key) or idempotency_key_invalid (empty or over 128 characters)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_limit_reached — the account's maximum mailbox limit has been reached; address_blocked — the primary address, its tag-stripped form, or its domain is on the platform blocklist (migration 0070); semantic_not_enabled — semantic: true was asked for without the account's plan gate; or receive_hold_not_enabled (receiveHold from an account key while this deployment has not enabled the owner's receive hold)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"address_taken — the primary email address is already routed to another mailbox — or account_deleted (the owning account is soft-deleted; restore it first), account_required (messageWebhook or eventWebhook on a platform identity: webhooks at creation are an account's), idempotency_key_reused (this Idempotency-Key belongs to a create with another request body; nothing changed), or identity_deleted (the identity this Idempotency-Key created was deleted since; a retry never re-creates it, use a fresh key)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited — account daily mailbox creation limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"semantic_capacity, when semantic: true was asked for but every vector shard is closed to new assignment: nothing was created, retry without the flag or once a shard is open. Or temporary_failure: under the object directory, semantic: true was asked for while the fleet's shard counts could not be read consistently (a bucket move, or semantic facts still backfilling); nothing was created; retry after the Retry-After window. Or temporary_failure on a create with messageWebhook or eventWebhook whose setup has not finished (its initialization, the event webhook or the mail store's arming): the identity is reserved and its setup is completed in the background; mail to its address is refused as temporary and its calendar and contact writes too until it is; retry with the same Idempotency-Key and body, which never creates a second identity. Or temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create an identity","tags":["Mailboxes"],"x-max-json-body-bytes":1048576},"get":{"description":"Lists mailboxes for the authenticated account. Set state=deleted to list restorable tombstones (deleted mailboxes still within the undo window). A SYSTEM caller lists every mailbox on the deployment, and may narrow to one tenant with `accountId`. Under the partitioned directory a system caller's deployment-wide listing walks the accounts in turn: its rows come account by account, its pages are bounded in work, so one may hold fewer than limit rows while more follow, and the list ends only when nextCursor is absent.","operationId":"get_IdentityList","parameters":[{"description":"System callers only: list just this account's mailboxes (ignored for account principals, which always see their own)","in":"query","name":"accountId","required":false,"schema":{"description":"System callers only: list just this account's mailboxes (ignored for account principals, which always see their own)","type":"string"}},{"description":"deleted: list restorable tombstones instead of live mailboxes. suspended: only live mailboxes the account owner has suspended, pending ones included (one account's listing: an account key, or a system key with accountId)","in":"query","name":"state","required":false,"schema":{"description":"deleted: list restorable tombstones instead of live mailboxes. suspended: only live mailboxes the account owner has suspended, pending ones included (one account's listing: an account key, or a system key with accountId)","enum":["deleted","suspended"],"type":"string"}},{"description":"Only live mailboxes whose receiveHold is this value (none selects the receiving ones), pending ones included; combines with state=suspended. One account's listing: an account key, or a system key with accountId (400 account_required otherwise). With state=deleted it is refused (400 validation_failed) rather than ignored","in":"query","name":"receiveHold","required":false,"schema":{"description":"Only live mailboxes whose receiveHold is this value (none selects the receiving ones), pending ones included; combines with state=suspended. One account's listing: an account key, or a system key with accountId (400 account_required otherwise). With state=deleted it is refused (400 validation_failed) rather than ignored","enum":["none","paused","disabled"],"type":"string"}},{"description":"Exact primary-address match (normalized) — the point lookup that saves a client walking the whole account to resolve one address. Live listing only","in":"query","name":"address","required":false,"schema":{"description":"Exact primary-address match (normalized) — the point lookup that saves a client walking the whole account to resolve one address. Live listing only","type":"string"}},{"description":"Only mailboxes whose primary address is on this domain. Live listing only","in":"query","name":"domain","required":false,"schema":{"description":"Only mailboxes whose primary address is on this domain. Live listing only","type":"string"}},{"description":"Case-insensitive substring over the primary address. Live listing only","in":"query","name":"q","required":false,"schema":{"description":"Case-insensitive substring over the primary address. Live listing only","type":"string"}},{"description":"Also return `total`: the full COUNT over the same filters, so 'N mailboxes on this domain' is one call instead of a walk. Opt-in because the default keyset page deliberately carries no totals","in":"query","name":"count","required":false,"schema":{"description":"Also return `total`: the full COUNT over the same filters, so 'N mailboxes on this domain' is one call instead of a walk. Opt-in because the default keyset page deliberately carries no totals","enum":["true","false"],"type":"string"}},{"description":"Also return each row's SAMPLED storage (`usedBytes`, `trashBytes`, `pimBytes`, `messageCount`, `databaseSize`, `usageAt`, `usageStale`) from the daily usage ledger — ONE call for the whole page, never a per-row stat read. These are as of `usageAt`, not live: a mailbox the sweep has not reached yet omits them entirely, and a client must render that as blank rather than as zero. Live figures are GET /mailboxes/:id. Live listing only","in":"query","name":"usage","required":false,"schema":{"description":"Also return each row's SAMPLED storage (`usedBytes`, `trashBytes`, `pimBytes`, `messageCount`, `databaseSize`, `usageAt`, `usageStale`) from the daily usage ledger — ONE call for the whole page, never a per-row stat read. These are as of `usageAt`, not live: a mailbox the sweep has not reached yet omits them entirely, and a client must render that as blank rather than as zero. Live figures are GET /mailboxes/:id. Live listing only","enum":["true","false"],"type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"properties":{"identities":{"items":{"$ref":"#/components/schemas/MailboxWithUsage"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"},"total":{"description":"Full filtered COUNT — present only when count=true was requested","format":"int64","type":"integer"}},"required":["identities"],"type":"object"},{"properties":{"identities":{"items":{"$ref":"#/components/schemas/DeletedMailbox"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["identities"],"type":"object"}]}}},"description":"Mailboxes page (live rows, or restorable tombstones when state=deleted); nextCursor present when a further page exists"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed (also receiveHold with state=deleted); or account_required (state=suspended or receiveHold from a system key without accountId)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Identity inventory temporarily unavailable; retry the same cursor. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List mailboxes","tags":["Mailboxes"]}},"/api/v1/identities/{identityId}":{"get":{"description":"Returns an identity with its bound stores (mail, calendars, contacts) and usage metrics. A bound store that cannot report its usage within a few seconds is still listed, marked `unavailable: true` with no counts; the rest of the identity is returned as usual.","operationId":"get_IdentityGet","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Identity"}}},"description":"Identity and bound store details"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Identity not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the identity's own holder could not answer its bound stores or its activity just now (under the object directory); retry after the Retry-After window","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get identity and bound store usage","tags":["Mailboxes"]},"patch":{"description":"Updates mailbox storage quota, primary address label, and outbound sending limits; or, alone in its request, suspends or resumes the mailbox (`suspended`), or pauses, stops or restores its receiving (`receiveHold`). A control answers 200 once enforced everywhere core must enforce it, or 202 (with Retry-After) while that is still being applied: poll GET until suspensionPending, or receiveHoldPending, is false.","operationId":"patch_IdentityUpdate","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"A control PATCH's (suspended, receiveHold) idempotency key, 1 to 128 characters, unique per gesture. A retry with the same key is recognised and never written again: it answers the state as it stands (200, 202, or 409 suspension_changed / receive_hold_changed if a newer different change won), so a lost answer or a 503 can be retried without reasserting this change over someone else's. The same key asking for another value is 409 idempotency_key_reused. On a settings PATCH it is 400 idempotency_key_unsupported","in":"header","name":"idempotency-key","required":false,"schema":{"description":"A control PATCH's (suspended, receiveHold) idempotency key, 1 to 128 characters, unique per gesture. A retry with the same key is recognised and never written again: it answers the state as it stands (200, 202, or 409 suspension_changed / receive_hold_changed if a newer different change won), so a lost answer or a 503 can be retried without reasserting this change over someone else's. The same key asking for another value is 409 idempotency_key_reused. On a settings PATCH it is 400 idempotency_key_unsupported","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ephemeral":{"description":"Create the mailbox DISPOSABLE (#483): its DELETE destroys it at once — no undo record, no 7-day window, its object gone, the address free again immediately — the shape for a mailbox per support case, agent session or transaction. Fixed at creation and reported on every read; a PATCH naming it is refused 400 ephemeral_immutable in either direction, so a key cannot make a long-lived mailbox disposable after the fact. Omitted or false creates an ordinary mailbox. Refused 400 ephemeral_requires_account on a platform identity, which has no account home to destroy through","type":"boolean"},"permittedRecipients":{"description":"System callers only. Outbound recipient allowlist: the ONLY addresses this mailbox may send to. Entries are exact addresses (`jo@acme.dev`) or domain wildcards (`*@acme.dev`). `null` = unrestricted (the default); `[]` = may send to nobody. At most 1,000 entries of at most 320 characters each (400 validation_failed otherwise); a list stored before these limits keeps working. A refused submission answers 403 recipient_not_permitted — permanent, so SMTP submission gets a 550. EGRESS ONLY: a restricted mailbox still receives from anyone","items":{"maxLength":320,"type":"string"},"maxItems":1000,"type":["array","null"]},"primaryAddress":{"description":"On create: CLAIMS the address - the address→mailbox route and the label are created atomically with the mailbox (409 address_taken if already routed); must be an ASCII local part on a non-alias directory domain owned by the mailbox's account (a U-label domain spelling is canonicalized to its stored A-label). On update: selects among the mailbox's already-routed addresses (bind first via POST /routes, which is idempotent); null clears the label","maxLength":320,"type":["string","null"]},"quotaBytes":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":["integer","null"]},"receiveHold":{"anyOf":[{"enum":["paused","disabled"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"Hold the mailbox's RECEIVING, the account owner's control, independent of suspension: 'paused' tells every sender to retry later (429 receiving_paused, SMTP 451; senders give up after about four to five days, after which their mail bounces and is lost, so a pause is for interruptions measured in days), 'disabled' rejects mail to it at once (403 receiving_disabled, SMTP 550; a rejection already issued cannot be undone), null receives normally again. Existing mail, settings and logins are untouched. Must be the ONLY field of its request (400 control_exclusive otherwise). A change of mode restamps receiveHoldAt; re-sending the current value keeps it and completes any propagation still pending"},"semantic":{"description":"SEMANTIC (meaning-based) search for this mailbox (docs/semantic-search-design.md). true embeds every new message after delivery and, on an existing mailbox, backfills a recent window (the later of 12 months and the 20,000 most recent messages; older mail on request via semanticFloor); false DELETES the mailbox's embeddings. Requires the account's plan gate (403 semantic_not_enabled) and an open shard (503 semantic_capacity). Off by default","type":"boolean"},"semanticFloor":{"description":"'Index older mail': LOWERS the semantic backfill floor to this epoch second (null = the whole store). Never raises it. Requires semantic search to be on (409 semantic_not_enabled); refused on create, where the floor is the creation instant","format":"int64","type":["integer","null"]},"sendHold":{"anyOf":[{"enum":["disabled","paused"],"type":"string"},{"enum":[null],"type":["object","null"]},{"type":"null"}],"description":"System callers only. Operator enforcement over this mailbox's outbound mail. 'disabled' STOPS it: every submission is refused 403 sending_disabled, queued relay jobs are dropped at the relay, and vacation auto-replies stop — permanent by contract, so SMTP submission gets a 550 and the mail bounces. 'paused' HOLDS it, the reversible form for a suspension you intend to lift (non-payment, an investigation): submissions answer 429 sending_paused with Retry-After, so SMTP submission gets a 451 and the sender's MTA queues the mail; queued relay jobs are DEFERRED rather than bounced. null lifts either. Does not affect receiving or reading. Applies to work already accepted as well: a send in progress stops before its remaining recipients, and queued group fan-out, member deliveries, destination webhooks and forwarding legs from this sender's submissions are deferred under 'paused' and dropped under 'disabled'. Already-queued fan-out legs may run for up to 10 seconds after the change. A retry with the same X-Delivery-Id is refused while the hold is set."},"sendMsgsPerDay":{"description":"System callers only. Distinct messages this mailbox may send per rolling 24h. null = the platform default; 0 = unlimited","maximum":9007199254740991,"minimum":0,"type":["integer","null"]},"sendMsgsPerHour":{"description":"System callers only. The BURST window: distinct messages this mailbox may send per hour (measured over the current and previous hourly bucket, so a refusal can hold for up to ~2h after a burst). null = the platform default; 0 = unlimited","maximum":9007199254740991,"minimum":0,"type":["integer","null"]},"sendRcptsPerDay":{"description":"System callers only. Envelope recipients this mailbox may send to per rolling 24h. null = the platform default; 0 = unlimited","maximum":9007199254740991,"minimum":0,"type":["integer","null"]},"sendRcptsPerHour":{"description":"System callers only. The BURST window: envelope recipients this mailbox may send to per hour. null = the platform default; 0 = unlimited","maximum":9007199254740991,"minimum":0,"type":["integer","null"]},"suspended":{"description":"Suspend (true) or resume (false) the mailbox: the account owner's control over a person's mailbox. A suspended mailbox's logins are refused as a wrong password is, its sending is held and its open sessions end; it keeps receiving mail, its credentials and settings are kept, and its owner keys still read and administer it. Must be the ONLY field of its request (400 control_exclusive otherwise). Re-sending the current value keeps suspendedAt and completes any enforcement still pending","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mailbox"}}},"description":"Updated mailbox details"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mailbox"}}},"description":"The control (suspended, receiveHold) was written and committed, and its enforcement is still being applied (suspensionPending, or receiveHoldPending, true): accepted work, not a failure. Retry-After says when to poll GET; repeating the same PATCH is safe and completes the outstanding work. Also the answer when the commit is confirmed but its current state could not be read back: the body then carries this write's own values, and GET is the authority"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, ephemeral_immutable (ephemeral named in a PATCH: it is fixed at creation), invalid_address, unknown_domain, domain_is_alias, address_not_routed, or semantic_floor_with_opt_out (semantic: false and semanticFloor in one request); control_exclusive (suspended or receiveHold alongside any other field, or both together); not_suspendable (suspended on a platform identity, which belongs to no account); not_holdable (receiveHold on one); idempotency_key_invalid (empty or over 128 characters); idempotency_key_unsupported (an Idempotency-Key on a settings PATCH)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"system_credentials_required (a send-policy field from a non-system caller); or semantic_not_enabled — semantic: true, or semanticFloor, without the account's plan gate. Every semantic refusal is decided BEFORE any other field is written; or suspension_not_enabled (suspended from an account key while this deployment has not enabled owner suspension); or receive_hold_not_enabled (receiveHold from an account key while this deployment has not enabled the owner's receive hold)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"semantic_not_enabled — semanticFloor given while semantic search is off; or no_mail_store: semantic: true or semanticFloor on an identity without a mail store, which has no mail to index (semantic: false is what it already is, and is accepted); or suspension_changed: a newer opposite suspend or resume superseded this one before it completed: the body's `mailbox` carries the current fields; or receive_hold_changed: a newer different receiveHold superseded this one before it completed, the body's `mailbox` carrying the current fields; or idempotency_key_reused: this Idempotency-Key was already used asking for another value, nothing changed, use a fresh key for a new gesture"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"semantic_capacity, when every vector shard is closed to new assignment: nothing changed; Retry-After carries an hour. Or temporary_failure: under the object directory, semantic: true was asked for while the fleet's shard counts could not be read consistently (a bucket move, or semantic facts still backfilling); nothing changed; retry after the Retry-After window. Or temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window (a send hold or its release; fields applied before it stand, and the retry converges). Or temporary_failure for a control (suspended, receiveHold) when the authority refused the write before committing it: nothing changed; retry, with the same Idempotency-Key","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update mailbox settings","tags":["Mailboxes"],"x-max-json-body-bytes":1048576},"delete":{"description":"Soft-deletes a mailbox with a 7-day retention window for recovery. Pass purge=true to immediately queue the mailbox for permanent deletion.","operationId":"delete_IdentityDelete","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Set to 'true' to permanently purge the mailbox immediately without a 7-day retention window. A system key's, or redundant on a mailbox created ephemeral (#483); from an account key on any other mailbox it is refused 403 system_credentials_required — the window is the undo a leaked key must not be able to waive","in":"query","name":"purge","required":false,"schema":{"description":"Set to 'true' to permanently purge the mailbox immediately without a 7-day retention window. A system key's, or redundant on a mailbox created ephemeral (#483); from an account key on any other mailbox it is refused 403 system_credentials_required — the window is the undo a leaked key must not be able to waive","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxDeleteResult"}}},"description":"Deletion outcome and undo window timestamps"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"system_credentials_required (purge=true from an account key on a mailbox not created ephemeral, #483) | account_credentials_required — a DOMAIN-SCOPED api key named a mailbox that is also routed on a domain outside its scope. Restore rebinds the mailbox's primary address, so deleting one primaried elsewhere could not be undone without writing a route on a domain this key does not hold; the account's own key may delete it"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_is_group_persona — this identity is a group's persona (its archive and sending identity); delete the group route instead, which tears the persona down with it"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete a mailbox","tags":["Mailboxes"]}},"/api/v1/identities/{identityId}/addresses":{"get":{"description":"Returns every address routed to this identity — what it may be addressed AT, for matching an iCalendar ATTENDEE or ORGANIZER line. Distinct from /auth/verify's permittedFrom, which is the sendability contract and carries tag patterns.","operationId":"get_IdentityAddressList","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentityAddresses"}}},"description":"The identity's addresses"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Identity not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the identity's account could not answer its addresses just now (under the object directory); retry after the Retry-After window","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List an identity's addresses","tags":["Mailboxes"]}},"/api/v1/mailboxes/{mailboxId}":{"get":{"description":"Returns mailbox metadata, current storage usage, message counts, trash metrics, database size, and realtime socket connection stats.","operationId":"get_MailboxGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxWithStats"}}},"description":"Mailbox details and live usage stats"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mail store could not report its usage just now (a storage fault, or no answer within a few seconds); retry after the Retry-After window","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get mailbox details and usage statistics","tags":["Mailboxes"]}},"/api/v1/identities/{identityId}/prefs":{"get":{"description":"Returns client preferences (theme, language, signature, etc.) stored as a JSON object, along with the current version number for optimistic locking.","operationId":"get_PrefsGet","parameters":[{"description":"Identity or mailbox identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity or mailbox identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prefs"}}},"description":"Stored preferences and version number"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Identity not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get identity preferences","tags":["Mailboxes"]},"put":{"description":"Updates or replaces the client preferences JSON object. Supports optimistic locking via the If-Match header.","operationId":"put_PrefsPut","parameters":[{"description":"Identity or mailbox identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity or mailbox identifier","type":"string"}},{"description":"Expected current version number for optimistic locking (omit for unconditional update)","in":"header","name":"if-match","required":false,"schema":{"description":"Expected current version number for optimistic locking (omit for unconditional update)","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"prefs":{"additionalProperties":{},"type":"object"}},"required":["prefs"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prefs"}}},"description":"Updated preferences and new version number"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — invalid request body"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Identity not found or not accessible to this principal"},"412":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"version_conflict — the preferences were updated by another client"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large — preferences payload exceeds size limit (64 KiB)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Save identity preferences","tags":["Mailboxes"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/retention":{"get":{"description":"Returns the time-based retention window in force for this mailbox (its own, else the account default, else none), where it came from, the platform floor, when the next message becomes due, and a PREVIEW of what a window would expunge — count and bytes of live messages older than it. Pass ?days= to preview windows that are not enabled. Retention expunges into the trash tier (restorable for 14 days), aged by the stored arrival time, never by the Date header.","operationId":"get_RetentionGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Comma-separated windows in days to preview (at most 8), e.g. `30,90,365`. Omitted: the window in force is previewed, if any","in":"query","name":"days","required":false,"schema":{"description":"Comma-separated windows in days to preview (at most 8), e.g. `30,90,365`. Omitted: the window in force is previewed, if any","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Retention"}}},"description":"The policy in force and the requested previews"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed ?days= (integers 1–36500, at most 8)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get retention policy and preview","tags":["Mailboxes"]},"put":{"description":"Sets this mailbox's OWN retention window in days — the owning account key or a system key; an app password may read the policy but not set it. Live messages older than it are expunged into the trash tier on the mailbox's next wake (restorable for 14 days; the trash purge frees storage after that), aged by the stored arrival time. Refused below the platform floor. Answers the same view as GET, including the preview of what the window will expunge — read it. To recover from a wrong window: clear or raise it FIRST, then restore; a message restored under the same window is due again at once.","operationId":"put_RetentionPut","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"retentionDays":{"description":"The mailbox's own window in days. Refused below the platform floor (400 retention_too_short). Live messages older than it are expunged into the trash tier on the mailbox's next wake, restorable for 14 days","exclusiveMinimum":0,"maximum":36500,"type":"integer"}},"required":["retentionDays"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Retention"}}},"description":"The policy now in force and its preview"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or retention_too_short (the window is below the platform floor; the body carries minDays)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"insufficient_scope (an app password may read this policy but not set it)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Set retention window","tags":["Mailboxes"],"x-max-json-body-bytes":1048576},"delete":{"description":"Clears this mailbox's OWN retention window. The account default, if any, then applies — the response says which window is now in force, which is why this answers the GET view rather than a bare deleted flag. Nothing already in the trash tier is restored by this: restore messages explicitly.","operationId":"delete_RetentionDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Retention"}}},"description":"The policy now in force (the account default, or none)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"insufficient_scope (an app password may read this policy but not clear it)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Clear retention window","tags":["Mailboxes"]}},"/api/v1/mailboxes/{mailboxId}/event-webhook":{"put":{"description":"One URL per mailbox, all events, no filters. Any PUT re-enables a hook the 24h auto-disable turned off. Omit `secret` to keep the stored one, pass a string to rotate, null to clear. What your endpoint receives (payload, `X-OpenEmail-Signature` scheme, retry policy) is specified as `event-batch` in this document's top-level `webhooks` section.","operationId":"put_MailboxEventWebhookSet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"secret":"whsec_5e8a1c9f2b7d4e6a8c1f3b5d7e9a2c4f","url":"https://hooks.acme.example/openemail"},"schema":{"properties":{"secret":{"description":"HMAC signing secret — write-only. Omit to keep, string to set, null to clear","maxLength":256,"minLength":1,"type":["string","null"]},"url":{"description":"HTTPS endpoint on a public host","format":"uri","type":"string"}},"required":["url"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"consecutiveFailures":0,"createdAt":1785542400,"disabledReason":null,"enabled":true,"failingSince":null,"hasSecret":true,"lastDeliveredAt":1788264000,"lastFailure":null,"lastFailureAt":null,"mailboxId":"01J9MBX7F4Q2K9T3W600000000","scope":"mailbox","updatedAt":1788264000,"url":"https://hooks.acme.example/openemail"},"schema":{"$ref":"#/components/schemas/EventWebhook"}}},"description":"The hook"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — URL refused"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_required — the mailbox has no owning account, and a hook row must reference one"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure — the mailbox's creation (POST /identities with eventWebhook) is still installing its hook; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create or replace the mailbox's event webhook","tags":["Mailboxes"],"x-max-json-body-bytes":1048576},"get":{"description":"The mailbox-scope event webhook: endpoint URL and delivery status. The signing secret is write-only and never returned.","operationId":"get_MailboxEventWebhookGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventWebhook"}}},"description":"The hook"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No hook configured, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Read the mailbox's event webhook","tags":["Mailboxes"]},"delete":{"description":"Deletes the hook: event batches stop immediately and nothing is retained. Any batch already in flight completes its retry ladder against nothing and is dropped; re-creating the hook later starts fresh (re-sync via GET /mailboxes/{mailboxId}/messages/changes rather than expecting a backlog).","operationId":"delete_MailboxEventWebhookDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Removed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No hook configured, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure — the mailbox’s creation is still installing its hook; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove the mailbox's event webhook","tags":["Mailboxes"]}},"/api/v1/mailboxes/{mailboxId}/event-webhook/test":{"post":{"description":"Queues one `webhook.test` batch through the real delivery path. The outcome shows on the resource (lastDeliveredAt / lastFailureAt) and in the traffic log — deliberately not a synchronous probe.","operationId":"post_MailboxEventWebhookTest","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventWebhookTestResult"}}},"description":"Test batch queued"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No hook configured, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Send a test event to the mailbox's event webhook","tags":["Mailboxes"]}},"/api/v1/mailboxes/{mailboxId}/message-webhook":{"put":{"description":"Every message that lands in this mailbox is POSTed here (the incoming-email payload, its signing and retries), however it got there: any of its addresses, a pattern or catch-all route, a group, a forward or redirect into it, a delivery-status notice or a platform notice; and whether the mailbox then keeps it, files it, or discards it (a Sieve discard, or discardIncoming on GET/PUT /mailboxes/{mailboxId}/filtering). Not the mailbox's own writes (its Sent copies, drafts, APPEND and imports, POP3 pickups), and not mail the mailbox refused (a blocked sender, a receive hold). A webhook tap on one of its addresses (PUT /routes/{address}) is separate: with both, each POSTs. Deleting the mailbox stops the POSTs, including ones already queued, and restoring it brings it back without its webhook. Omit `secret` to keep the stored one, pass a string to rotate it, null to clear it; omit `format` to keep it. Only an account key or system key may set it.","operationId":"put_MailboxMessageWebhookSet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageWebhookBody"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageWebhook"}}},"description":"The webhook"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed (the URL refused), or webhook_format_unavailable (format reference on a deployment that mints no capability URLs)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_required: the mailbox has no owning account"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mailbox's creation (POST /identities with messageWebhook) is still installing its webhook; retry after Retry-After. temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create or replace the mailbox's message webhook","tags":["Mailboxes"],"x-max-json-body-bytes":1048576},"get":{"description":"Where each message that lands in this mailbox is POSTed, however it arrived. The signing secret is write-only and never returned. A mailbox's own app password may read it.","operationId":"get_MailboxMessageWebhookGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageWebhook"}}},"description":"The webhook"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No webhook configured, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Read the mailbox's message webhook","tags":["Mailboxes"]},"delete":{"description":"Stops the POSTs: mail that lands from now on reaches the mailbox alone. A POST already queued completes against nothing and is dropped. Only an account key or system key may remove it.","operationId":"delete_MailboxMessageWebhookDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Removed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No webhook configured, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mailbox's creation is still installing its webhook; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove the mailbox's message webhook","tags":["Mailboxes"]}},"/api/v1/mailboxes/{mailboxId}/shares/{granteeIdentityId}":{"put":{"description":"Lets another identity in the same account open this mailbox — the shared team inbox and delegated-assistant case. The `rights` value decides what they may do with it.\n\nSending one grant replaces any previous grant for that identity, so this is how you widen or narrow access as well as how you create it. Both parties must belong to the same account, and a mailbox cannot be shared with itself.\n\nAccess takes effect immediately: rights are re-read on every request, so there is no cache to wait out — and revoking is equally immediate.\n\nA grant covers reading and organising mail only. It never allows sending as the mailbox owner, and it never allows the recipient to re-share the mailbox or change grants.","operationId":"put_MailSharePut","parameters":[{"description":"ULID of the mailbox whose access is being managed","in":"path","name":"mailboxId","required":true,"schema":{"description":"ULID of the mailbox whose access is being managed","type":"string"}},{"description":"ULID of the identity being given (or losing) access","in":"path","name":"granteeIdentityId","required":true,"schema":{"description":"ULID of the identity being given (or losing) access","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutMailShareBody"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailShare"}}},"description":"The grant, as stored. `rights` comes back in canonical letters even if you sent a preset name, so you can display exactly what was granted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"`validation_failed` — malformed body. `invalid_rights` — the rights value is not a known preset and not a valid letter set; the response carries an `invalidLetters` array naming the offending letters. `self_share_prohibited` — a mailbox cannot be shared with itself. `rights_not_allowed_on_folder_share` — a folder-scoped grant may only carry `lrswit` (read, private read/unread marks, write flags/keywords within the scope, file into a named in-scope folder, and trash out of the folder — never expunge or folder administration); the response names the offending letters and the allowed set. `empty_label_scope` — `labelScope` was an empty list, which would be a grant that can see nothing; use DELETE to revoke instead. `unknown_label` — one or more named folders do not exist in this mailbox; the response names them. `label_scope_too_large` — more folders were named than one grant may carry; the response carries the `max`. `invalid_label_scope` — a scope entry was not a folder identifier. `grantee_has_no_mail_store` — the grantee is an identity of this account without a mail store, which has no mail session to read a share in. `cross_account_share_refused` — the grantee belongs to a different account (system principals only; tenants receive 404 instead, so the API cannot be used to discover identities in other accounts)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"`not_found` — the mailbox does not exist or is not yours to manage, or the grantee identity does not exist or belongs to another account"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"`mail_share_grantee_limit` or `mail_share_readable_store_limit`: a new grant would exceed the share fan-out cap; the response carries `max`. Existing grants remain editable."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Give another user access to this mailbox","tags":["Mailboxes"],"x-max-json-body-bytes":1048576},"delete":{"description":"Takes away an identity's access to this mailbox. Access stops immediately — rights are re-read on every request, so a session that is already open loses the mailbox on its next operation rather than at some later expiry.\n\nThe read/unread marks that identity had made in this mailbox are their own, and are discarded with the grant. Nothing belonging to the mailbox owner is deleted.","operationId":"delete_MailShareDelete","parameters":[{"description":"ULID of the mailbox whose access is being managed","in":"path","name":"mailboxId","required":true,"schema":{"description":"ULID of the mailbox whose access is being managed","type":"string"}},{"description":"ULID of the identity being given (or losing) access","in":"path","name":"granteeIdentityId","required":true,"schema":{"description":"ULID of the identity being given (or losing) access","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"The grant was removed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"`not_found` — the mailbox does not exist or is not yours to manage, or that identity had no grant on it"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove another user's access to this mailbox","tags":["Mailboxes"]}},"/api/v1/mailboxes/{mailboxId}/shares":{"get":{"description":"Returns everyone this mailbox has been shared with, oldest grant first, each with the rights they hold. This is the owner's side of sharing; to list mailboxes shared WITH you, use `GET /shared-mailboxes` instead.\n\nThe full list is always returned — grants are bounded by the account's own membership, so there is no paging.","operationId":"get_MailShareList","parameters":[{"description":"ULID of the mailbox whose access is being managed","in":"path","name":"mailboxId","required":true,"schema":{"description":"ULID of the mailbox whose access is being managed","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"shares":{"items":{"$ref":"#/components/schemas/MailShare"},"type":"array"}},"required":["shares"],"type":"object"}}},"description":"Everyone with access to this mailbox, oldest grant first"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"`not_found` — the mailbox does not exist or is not yours to manage"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List who has access to this mailbox","tags":["Mailboxes"]}},"/api/v1/shared-mailboxes":{"get":{"description":"Returns every mailbox belonging to someone else that you have been given access to, oldest grant first, each with the rights you hold on it. Use the returned `mailboxId` to read that mailbox through the ordinary mailbox endpoints.\n\nThere is no mailbox in the path: the answer is scoped to whoever is authenticated. A mailbox credential lists its own grants. An account credential is not an identity and receives an empty list — to see one member's shared mailboxes, ask with that member's credential. A system credential must name the identity it is acting for in the `X-Acting-Identity` header, and without it receives an empty list rather than every grant on the deployment.\n\nAn empty list is the normal answer for someone nothing has been shared with; it is never an error. The full list is always returned — there is no paging.","operationId":"get_SharedMailboxList","parameters":[{"description":"Set `false` to skip resolving each folder-scoped grant's folder NAMES, omitting `labelScope` from every row. Rendering costs one read of the owner's folder list per distinct owner who granted you folder-scoped access, so a client that does not display folder names — notably one calling this per IMAP LIST — should turn it off. The field is OMITTED rather than emptied: `null` already means whole mailbox, so absent is the only honest way to say 'not computed'. Note that skipping the render also skips the dead-grant filter: a grant whose folders were all deleted (normally revoked by the folder delete itself, and hidden here if that cleanup could not run) is only detectable BY rendering, so with `labelScope=false` such residue is listed like any other grant. Defaults to rendering","in":"query","name":"labelScope","required":false,"schema":{"description":"Set `false` to skip resolving each folder-scoped grant's folder NAMES, omitting `labelScope` from every row. Rendering costs one read of the owner's folder list per distinct owner who granted you folder-scoped access, so a client that does not display folder names — notably one calling this per IMAP LIST — should turn it off. The field is OMITTED rather than emptied: `null` already means whole mailbox, so absent is the only honest way to say 'not computed'. Note that skipping the render also skips the dead-grant filter: a grant whose folders were all deleted (normally revoked by the folder delete itself, and hidden here if that cleanup could not run) is only detectable BY rendering, so with `labelScope=false` such residue is listed like any other grant. Defaults to rendering","enum":["true","false"],"type":"string"}},{"description":"System credentials only: the ULID of the identity to answer for. Ignored for mailbox and account credentials, which already identify the caller. Omitting it on a system credential returns an empty list","in":"header","name":"x-acting-identity","required":false,"schema":{"description":"System credentials only: the ULID of the identity to answer for. Ignored for mailbox and account credentials, which already identify the caller. Omitting it on a system credential returns an empty list","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"sharedMailboxes":{"items":{"$ref":"#/components/schemas/SharedMailbox"},"type":"array"}},"required":["sharedMailboxes"],"type":"object"}}},"description":"Mailboxes shared with you, oldest grant first. Empty when nothing is shared with you, or when the caller is not an identity (see above)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List mailboxes shared with you","tags":["Mailboxes"]}},"/api/v1/mailboxes/{mailboxId}/routing":{"get":{"description":"Returns the addresses that deliver mail to this mailbox, and whether it may send as each: its primary address, its other routes and their alias-domain spellings, the wildcard patterns aimed at it (`catch_all` for a bare `*`), and the groups it is a member of or the persona of. `receives` includes a group's persona archive as well as its members; `canSend` requires the domain to permit sending and, for a group, this mailbox to be its persona. An alias spelling receives only when both its alias and canonical domains receive, and its subaddressing follows the canonical domain. Unlike send-as, this keeps addresses that cannot send and patterns a From picker cannot offer. At most 200 eligible, distinct entries; `truncated` says when there were more. A domain-scoped key sees only its own domains.","operationId":"get_MailboxRoutingGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxRouting"}}},"description":"The entries, primary first"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List what delivers to a mailbox","tags":["Mailboxes"]}},"/api/v1/mailboxes/{mailboxId}/send-as":{"get":{"description":"Returns the addresses this mailbox may use as From, primary first: its routed addresses on domains that may send, then `*@domain` wherever a catch-all on a sending domain lands in it (RFC 8621 §6's wildcard, any address on that domain). The same list JMAP Identity/get reports. `subaddressing` says whether an address's `+tag` forms are sendable too. A domain-scoped key sees only its own domains. Suggestions for a From picker, not an authorization list: an address a narrower catch-all pattern routes here is sendable without being listed, and the list stops at 100 addresses, so submission decides.","operationId":"get_MailboxSendAsList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAsAddresses"}}},"description":"The addresses, primary first"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List the addresses a mailbox may send as","tags":["Mailboxes"]}},"/api/v1/mailboxes/{mailboxId}/send-as/check":{"post":{"description":"Checks one From address through the same routing, ownership, credential scope and sending-state authorization as submission, including aliases, subaddresses and catch-all patterns. Requires submission access to the named mailbox; folder grants do not confer sending rights. For non-system callers, unknown or foreign addresses return 403 sender_not_owned without revealing their owner. Does not create mail, reserve quota or send anything. A successful check is advisory: submission always checks again. Responses are not cacheable.","operationId":"post_MailboxSenderCheck","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"address":{"description":"One bare From address, without a display name","type":"string"}},"required":["address"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SenderCheck"}}},"description":"This caller may currently send from this address through this mailbox"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"Malformed address (invalid_address) or request body"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Address not owned by this mailbox (sender_not_owned), no local sender for a system caller (sender_not_local), sending disabled (sending_disabled), or insufficient credential scope (credential_scope)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Sending paused (sending_paused); Retry-After and retryAfterSeconds indicate when to retry","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Check whether a mailbox may send from an address","tags":["Mailboxes"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/send-usage":{"get":{"description":"Returns outbound email quota usage and current rate limits for the mailbox over the rolling 24-hour window.","operationId":"get_SendUsageGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendUsage"}}},"description":"Current send quota usage and limits"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get outbound send rate limit usage","tags":["Mailboxes"]}},"/api/v1/mailboxes/{mailboxId}/send-state":{"get":{"description":"Returns `canSend` and, when it is false, `sendHold`: the answer `/auth/verify` gives a login typed as the mailbox's primary address, from the same function, for a mailbox credential and without the password. `sendHold` is the fold across the mailbox, its account and its domain ('unverified' = publish DNS, 'receive_only' = the domain sends through another provider, 'paused' = a reversible hold, 'disabled' = a stop), unlike `/send-usage`'s `sendHold`, which is the mailbox's own switch. Advisory; the submission gate is the authority.","operationId":"get_MailboxSendState","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendState"}}},"description":"Whether the mailbox may send, and why not"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get whether a mailbox may send","tags":["Mailboxes"]}},"/api/v1/identities/{identityId}/restore":{"post":{"description":"Restores a soft-deleted mailbox from trash within its 7-day retention window. Re-binds the primary address if still available.","operationId":"post_IdentityRestore","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxRestoreResult"}}},"description":"Restore result and restored mailbox details"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No restorable mailbox found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_deleted — mailbox is active or already restored"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"gone — retention window elapsed or mailbox was permanently purged"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Restore a deleted mailbox","tags":["Mailboxes"]}},"/api/v1/routes":{"post":{"description":"Creates an email routing rule mapping an address to a mailbox, webhook, remote forwarder, or group. For non-webhook destinations an optional webhookUrl attaches a tap that receives a copy of incoming messages; for non-remote destinations an optional remoteAddress attaches a forward tap that relays a copy to another address alongside the delivery. Idempotent: re-creating an identical rule returns 200 with the existing route.","operationId":"post_RouteCreate","requestBody":{"content":{"application/json":{"schema":{"properties":{"address":{"type":"string"},"destinationType":{"enum":["mailbox","webhook","remote","group"],"type":"string"},"mailboxId":{"type":"string"},"paced":{"default":false,"description":"Pace inbound deliveries to this route's mailbox through the paced queue (funnel/shared-inbox protection). Mailbox routes only; ignored at delivery time for other destination types.","type":"boolean"},"posting":{"enum":["open","members"],"type":"string"},"remoteAddress":{"type":"string"},"webhookFormat":{"enum":["parsed","reference"],"type":"string"},"webhookSecret":{"type":"string"},"webhookUrl":{"format":"uri","type":"string"}},"required":["address","destinationType"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Route"}}},"description":"Created route — or, when the binding is identical, the EXISTING route unchanged (idempotent create: the replay's paced/webhookSecret/webhookFormat are not applied — PATCH is the verb that edits an existing route)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_address (malformed remoteAddress, or D2: the route's own address must be an ASCII local part on an A-label domain), unknown_domain, domain_is_alias, unknown_mailbox (missing, inaccessible, or outside the route domain's account, including platform domains), webhook_format_unavailable (reference format asked for on a deployment that mints no capability URLs), or destination_is_self / destination_loops / destination_chain_too_long when the forward target routes back to this address"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"address_blocked — the address, its tag-stripped form, or its domain is on the platform blocklist (migration 0070)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"route_exists — the address is bound to a DIFFERENT destination; mailbox_is_group_persona — the mailbox target is a group's persona, which nothing may route to; group_delete_in_flight — this group's delete is still running (retry the DELETE, then re-create); inbound_edge_cap — the destination cannot accept another incoming edge; route_changed — a concurrent edit replaced the publication"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited — the account's daily address or mailbox creation limit (a group also mints its persona)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window (a group, whose persona the census counts)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create a routing rule","tags":["Routing"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns email routing rules. Filter with type=group for group listings (includes posting and member counts), type=webhook for destination webhooks and webhook taps, or type=remote for destination forwards and forward taps.","operationId":"get_RouteList","parameters":[{"description":"Only routes on this domain","in":"query","name":"domain","required":false,"schema":{"description":"Only routes on this domain","type":"string"}},{"description":"Only routes delivering to this mailbox","in":"query","name":"mailboxId","required":false,"schema":{"description":"Only routes delivering to this mailbox","type":"string"}},{"description":"Only routes with this destination type","in":"query","name":"type","required":false,"schema":{"description":"Only routes with this destination type","enum":["mailbox","webhook","remote","group"],"type":"string"}},{"description":"Only the GROUPS this address is a member of: every group whose member list holds the address, or a +tag form of it where its domain splits tags (subaddressing), and whose membership is in effect. A system key sees every account's groups and the platform's; an account key its own account's (a domain-scoped key, those on its domains). Each row is the group as type=group presents it, in address order. Matched as written: an alias-domain spelling is its own address. Not combinable with domain, mailboxId or type, and an address is required (400 validation_failed either way). The answer echoes the normalized address as memberOf; a core that predates this filter ignores it and answers the unfiltered listing without the echo","in":"query","name":"memberOf","required":false,"schema":{"description":"Only the GROUPS this address is a member of: every group whose member list holds the address, or a +tag form of it where its domain splits tags (subaddressing), and whose membership is in effect. A system key sees every account's groups and the platform's; an account key its own account's (a domain-scoped key, those on its domains). Each row is the group as type=group presents it, in address order. Matched as written: an alias-domain spelling is its own address. Not combinable with domain, mailboxId or type, and an address is required (400 validation_failed either way). The answer echoes the normalized address as memberOf; a core that predates this filter ignores it and answers the unfiltered listing without the echo","type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"memberOf":{"description":"With memberOf: the address as core normalized it. A client checks it, since a core without the filter ignores the parameter","type":"string"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"},"routes":{"items":{"$ref":"#/components/schemas/Route"},"type":"array"},"truncated":{"description":"With memberOf: true when a matching-candidate read exhausted its 1,000-row bound. Missing groups can fall anywhere in address order; paging alone does not prove completeness. For account keys this describes only their own in-scope active memberships","type":"boolean"}},"required":["routes"],"type":"object"}}},"description":"Routes page; nextCursor present when a further page exists"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List routing rules","tags":["Routing"]}},"/api/v1/routes/{address}":{"get":{"description":"Returns routing configuration, destination, and webhook tap settings for a specific email address.","operationId":"get_RouteGet","parameters":[{"description":"Full email address (e.g. 'info@example.com')","in":"path","name":"address","required":true,"schema":{"description":"Full email address (e.g. 'info@example.com')","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Route"}}},"description":"Route details"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Route not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get email route details","tags":["Routing"]},"patch":{"description":"Updates the destination, delivery pacing, group posting policy, webhook tap, or forward tap for an email address.","operationId":"patch_RouteUpdate","parameters":[{"description":"Full email address (e.g. 'info@example.com')","in":"path","name":"address","required":true,"schema":{"description":"Full email address (e.g. 'info@example.com')","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"destinationType":{"description":"New destination type","enum":["mailbox","webhook","remote","group"],"type":"string"},"mailboxId":{"description":"Destination mailbox ID (when destinationType is 'mailbox')","type":"string"},"paced":{"description":"Pace inbound deliveries to this route's mailbox through the paced queue (funnel/shared-inbox protection). Mailbox routes only; ignored at delivery time for other destination types.","type":"boolean"},"posting":{"description":"Group posting policy ('open' or 'members')","enum":["open","members"],"type":"string"},"remoteAddress":{"description":"Destination forwarding address or forward tap address (null to remove tap). An external target may carry a UTF-8 local part (D6); the domain half is canonicalized (D3)","type":["string","null"]},"webhookFormat":{"description":"Webhook payload format: 'parsed' (default) or 'reference'","enum":["parsed","reference"],"type":"string"},"webhookSecret":{"description":"HMAC signing secret for webhooks (null to clear)","type":["string","null"]},"webhookUrl":{"description":"Destination webhook URL or tap webhook URL (null to remove tap)","format":"uri","type":["string","null"]}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Route"}}},"description":"Updated route details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_address (malformed remoteAddress), empty_patch, destination_requires_type, posting_requires_group, no_webhook, webhook_format_unavailable, unknown_mailbox (missing, inaccessible, or outside the route domain's account, including platform domains), or destination_is_self / destination_loops / destination_chain_too_long"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Route not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"group_has_persona — a group never changes shape in place (DELETE the route instead: its persona's archive and credential would otherwise be orphaned); mailbox_is_group_persona — the mailbox target is a group's persona; inbound_edge_cap — the destination cannot accept another incoming edge; route_changed — a concurrent edit replaced the publication; primary_address_route (with address and mailboxId): the address is that mailbox's primary address, so it may not be retargeted away from it (a restate onto the same mailbox is fine). Promote another address with PATCH /identities/:id {primaryAddress}, clear it with primaryAddress: null, or delete the mailbox"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited — converting into a group mints its persona and spends a mailbox-create slot","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window (converting into a group, whose persona the census counts)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update email route","tags":["Routing"],"x-max-json-body-bytes":1048576},"delete":{"description":"Removes an email address routing rule. Deleting a GROUP also soft-deletes its persona mailbox (the archive and sending identity) — restorable by its ULID for the usual window through POST /identities/:id/restore; re-creating the address mints a fresh persona.","operationId":"delete_RouteDelete","parameters":[{"description":"Full email address (e.g. 'info@example.com')","in":"path","name":"address","required":true,"schema":{"description":"Full email address (e.g. 'info@example.com')","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Route deleted successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Route not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"primary_address_route (with address and mailboxId): the address is that mailbox's primary address, and deleting it would leave the mailbox unable to receive mail or log in under it. Promote another address with PATCH /identities/:id {primaryAddress}, clear it with primaryAddress: null, or delete the mailbox"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete email route","tags":["Routing"]}},"/api/v1/routes/{address}/members":{"post":{"description":"Adds a single recipient email address to a group route.","operationId":"post_MemberAdd","parameters":[{"description":"Group route email address (e.g. 'team@example.com')","in":"path","name":"address","required":true,"schema":{"description":"Group route email address (e.g. 'team@example.com')","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"memberAddress":{"description":"Email address to add to group","type":"string"}},"required":["memberAddress"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteMemberRef"}}},"description":"Member added successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, member_limit, invalid_member_address, self_membership — the group itself, by any spelling (a plus-tag or an alias-domain form both resolve back to it); destination_loops / destination_chain_too_long — the member's own delivery chain (a forward, a tap, a nested list) leads back into this group"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Group route not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"member_exists; inbound_edge_cap: the member cannot accept another incoming delivery edge; route_changed: a concurrent edit replaced the membership while it was published (either names memberAddress)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Add group member","tags":["Routing"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns a paginated list of recipient member email addresses belonging to a group route.","operationId":"get_MemberList","parameters":[{"description":"Group route email address (e.g. 'team@example.com')","in":"path","name":"address","required":true,"schema":{"description":"Group route email address (e.g. 'team@example.com')","type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"members":{"items":{"$ref":"#/components/schemas/RouteMember"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["members"],"type":"object"}}},"description":"Page of group members"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Group route not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List group members","tags":["Routing"]},"put":{"description":"Overwrites the entire recipient list of a group route in a single call.","operationId":"put_MemberReplace","parameters":[{"description":"Group route email address (e.g. 'team@example.com')","in":"path","name":"address","required":true,"schema":{"description":"Group route email address (e.g. 'team@example.com')","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"members":{"description":"Full list of replacement member addresses","items":{"description":"Recipient member email address","type":"string"},"type":"array"}},"required":["members"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"members":{"items":{"$ref":"#/components/schemas/RouteMember"},"type":"array"}},"required":["members"],"type":"object"}}},"description":"Full replaced member list"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, member_limit, invalid_member_address, self_membership — the group itself, by any spelling (a plus-tag or an alias-domain form both resolve back to it); destination_loops / destination_chain_too_long — the member's own delivery chain (a forward, a tap, a nested list) leads back into this group"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Group route not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"inbound_edge_cap: the member cannot accept another incoming delivery edge; route_changed: a concurrent edit replaced the membership while it was published (either names memberAddress; the rest of the write stands)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Replace all group members","tags":["Routing"],"x-max-json-body-bytes":1048576}},"/api/v1/routes/{address}/members/batch":{"post":{"description":"Adds multiple recipient email addresses to a group route in a single request.","operationId":"post_MemberBatchAdd","parameters":[{"description":"Group route email address (e.g. 'team@example.com')","in":"path","name":"address","required":true,"schema":{"description":"Group route email address (e.g. 'team@example.com')","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"members":{"description":"List of member email addresses to add","items":{"description":"Email address to add","type":"string"},"maxItems":1000,"minItems":1,"type":"array"}},"required":["members"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteMemberBatchResult"}}},"description":"Batch addition counts"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, member_limit, invalid_member_address, self_membership — the group itself, by any spelling (a plus-tag or an alias-domain form both resolve back to it); destination_loops / destination_chain_too_long — the member's own delivery chain (a forward, a tap, a nested list) leads back into this group"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Group route not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"inbound_edge_cap: the member cannot accept another incoming delivery edge; route_changed: a concurrent edit replaced the membership while it was published (either names memberAddress; the rest of the write stands)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Batch add group members","tags":["Routing"],"x-max-json-body-bytes":1048576}},"/api/v1/routes/{address}/members/{memberAddress}":{"delete":{"description":"Removes a recipient email address from a group route.","operationId":"delete_MemberRemove","parameters":[{"description":"Group route email address (e.g. 'team@example.com')","in":"path","name":"address","required":true,"schema":{"description":"Group route email address (e.g. 'team@example.com')","type":"string"}},{"description":"Recipient member email address to remove","in":"path","name":"memberAddress","required":true,"schema":{"description":"Recipient member email address to remove","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Member removed successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Group route or member not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove group member","tags":["Routing"]}},"/api/v1/patterns":{"post":{"description":"Creates a wildcard email pattern route (e.g. 'support-*' or '*') directed to a mailbox, webhook, remote forward, or alias.","operationId":"post_PatternCreate","requestBody":{"content":{"application/json":{"schema":{"properties":{"aliasAddress":{"type":"string"},"destinationType":{"enum":["mailbox","webhook","remote","alias"],"type":"string"},"domain":{"minLength":3,"type":"string"},"mailboxId":{"type":"string"},"paced":{"default":false,"description":"Pace inbound deliveries to this pattern's mailbox through the paced queue (funnel protection). Mailbox patterns only; ignored at delivery time for other destination types.","type":"boolean"},"pattern":{"minLength":1,"type":"string"},"priority":{"type":"integer"},"remoteAddress":{"type":"string"},"webhookFormat":{"enum":["parsed","reference"],"type":"string"},"webhookSecret":{"type":["string","null"]},"webhookUrl":{"format":"uri","type":"string"}},"required":["destinationType","domain","pattern"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pattern"}}},"description":"Pattern route created successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_address (malformed remoteAddress), unknown_domain, domain_is_alias, invalid_pattern, pattern_limit, unknown_mailbox (missing, inaccessible, or outside the pattern domain's account, including platform domains), webhook_format_unavailable (reference format asked for on a deployment that mints no capability URLs), invalid_alias_address, alias_target_unresolvable, destination_is_self, destination_loops, or destination_chain_too_long"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"pattern_exists"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create pattern route","tags":["Routing"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns a paginated list of wildcard address pattern routes for an account or domain.","operationId":"get_PatternList","parameters":[{"description":"Filter by domain name","in":"query","name":"domain","required":false,"schema":{"description":"Filter by domain name","type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"},"patterns":{"items":{"$ref":"#/components/schemas/Pattern"},"type":"array"}},"required":["patterns"],"type":"object"}}},"description":"Page of pattern routes"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed or invalid_cursor"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List pattern routes","tags":["Routing"]}},"/api/v1/patterns/{patternId}":{"patch":{"description":"Updates the priority, delivery pacing, or destination configuration for a pattern route.","operationId":"patch_PatternUpdate","parameters":[{"description":"Pattern route numeric ID","in":"path","name":"patternId","required":true,"schema":{"description":"Pattern route numeric ID","minimum":1,"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"aliasAddress":{"type":"string"},"destinationType":{"enum":["mailbox","webhook","remote","alias"],"type":"string"},"mailboxId":{"type":"string"},"paced":{"description":"Pace inbound deliveries to this pattern's mailbox through the paced queue (funnel protection). Mailbox patterns only; ignored at delivery time for other destination types.","type":"boolean"},"priority":{"description":"Routing priority order (higher priority matches first)","type":"integer"},"remoteAddress":{"type":"string"},"webhookFormat":{"enum":["parsed","reference"],"type":"string"},"webhookSecret":{"type":["string","null"]},"webhookUrl":{"format":"uri","type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pattern"}}},"description":"Updated pattern details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_address (malformed remoteAddress), empty_patch, destination_requires_type, unknown_mailbox (missing, inaccessible, or outside the pattern domain's account, including platform domains), webhook_format_unavailable, invalid_alias_address, alias_target_unresolvable, destination_is_self, destination_loops, or destination_chain_too_long"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Pattern not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update pattern route","tags":["Routing"],"x-max-json-body-bytes":1048576},"delete":{"description":"Removes a pattern routing rule.","operationId":"delete_PatternDelete","parameters":[{"description":"Pattern route numeric ID","in":"path","name":"patternId","required":true,"schema":{"description":"Pattern route numeric ID","minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Pattern route deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — patternId must be an integer"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Pattern not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete pattern route","tags":["Routing"]}},"/api/v1/deliveries/fetch/{token}":{"get":{"description":"Redeems a signed webhook token URL to download a large attachment or original raw MIME message. No bearer credential: the token in the path IS the credential (a signed, expiring capability minted into webhook payloads as `url` / `rawUrl`).","operationId":"get_DeliveryFetch","parameters":[{"description":"Signed capability token from webhook payload","in":"path","name":"token","required":true,"schema":{"description":"Signed capability token from webhook payload","type":"string"}},{"description":"Revalidation ETag from a previous response; on match the answer is 304","in":"header","name":"if-none-match","required":false,"schema":{"description":"Revalidation ETag from a previous response; on match the answer is 304","type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"description":"Binary content stream","type":"string"}}},"description":"Decoded attachment bytes or raw RFC 5322 message stream","headers":{"ETag":{"description":"Content hash for revalidation; send it back as If-None-Match","schema":{"type":"string"}}}},"304":{"description":"Not modified (ETag match)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_token — token is expired, invalid, or forged"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — staged message expired or part section not found"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"message_too_large: the staged message is over the part-walk ceiling, so a section cannot be extracted (the raw-message form of the token still works)"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unparseable_message — message structure cannot be parsed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"part_walk_busy: too many large messages are being read on this server at once; retry after Retry-After. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"security":[],"summary":"Fetch webhook attachment or raw message","tags":["Routing"]}},"/api/v1/accounts/{accountId}/lists":{"post":{"description":"Creates an allow or block list at the account, domain, or mailbox scope. Scope, direction, and verdict are immutable once created.","operationId":"post_AccountAddressListCreate","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"contactsExempt":{"description":"Inbound block lists only (else 400): when this list's catch-all decides, let a vouched sender from the receiving mailbox's own address book through. Groups, webhooks and remote routes still need a named allow.","type":"boolean"},"direction":{"description":"Traffic direction ('inbound' or 'outbound')","enum":["inbound","outbound"],"type":"string"},"name":{"description":"Descriptive name for the list","maxLength":120,"minLength":1,"type":"string"},"scopeId":{"description":"Identifier of the domain, mailbox, or account","type":"string"},"scopeKind":{"description":"Required on account routes ('account', 'domain', 'mailbox'); omitted on mailbox routes","enum":["account","domain","mailbox"],"type":"string"},"verdict":{"description":"Policy outcome ('allow' or 'block')","enum":["allow","block"],"type":"string"}},"required":["name","direction","verdict"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressList"}}},"description":"Created address list"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"list_name_taken (name already exists in this scope) or list_limit_reached (maximum lists for this scope reached)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create an address list","tags":["Routing"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns allow and block address lists for this account or mailbox, optionally filtered by scope, direction (inbound/outbound), or verdict (allow/block).","operationId":"get_AccountAddressListIndex","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}},{"description":"Filter by scope kind ('account', 'domain', 'mailbox')","in":"query","name":"scopeKind","required":false,"schema":{"description":"Filter by scope kind ('account', 'domain', 'mailbox')","enum":["account","domain","mailbox"],"type":"string"}},{"description":"Filter by scope identifier","in":"query","name":"scopeId","required":false,"schema":{"description":"Filter by scope identifier","type":"string"}},{"description":"Filter by direction ('inbound', 'outbound')","in":"query","name":"direction","required":false,"schema":{"description":"Filter by direction ('inbound', 'outbound')","enum":["inbound","outbound"],"type":"string"}},{"description":"Filter by policy action ('allow', 'block')","in":"query","name":"verdict","required":false,"schema":{"description":"Filter by policy action ('allow', 'block')","enum":["allow","block"],"type":"string"}},{"description":"`true`: only the lists holding a live catch-all (`*@*`), the \"block all\" lists","in":"query","name":"catchAll","required":false,"schema":{"description":"`true`: only the lists holding a live catch-all (`*@*`), the \"block all\" lists","enum":["true","false"],"type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListPage"}}},"description":"List of address lists"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List address lists","tags":["Routing"]}},"/api/v1/accounts/{accountId}/lists/{listId}":{"get":{"description":"Returns details of an address list along with its current pattern entry count.","operationId":"get_AccountAddressListGet","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressList"}}},"description":"Address list details and entry count"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get an address list","tags":["Routing"]},"patch":{"description":"Renames an address list and/or sets `contactsExempt` (inbound block lists only). Scope, direction and verdict are immutable.","operationId":"patch_AccountAddressListPatch","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"contactsExempt":{"description":"Inbound block lists only: let the receiving mailbox's contacts through this list's catch-all","type":"boolean"},"name":{"description":"New list name","maxLength":120,"minLength":1,"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressList"}}},"description":"Renamed address list"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"list_name_taken"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): the directory version does not yet support this write; retry","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update an address list","tags":["Routing"],"x-max-json-body-bytes":1048576},"delete":{"description":"Deletes an address list and removes all of its associated address and domain patterns.","operationId":"delete_AccountAddressListDelete","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Address list deleted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete an address list","tags":["Routing"]}},"/api/v1/accounts/{accountId}/lists/{listId}/entries":{"post":{"description":"Adds an email address, domain, or wildcard pattern to an address list. Idempotent.","operationId":"post_AccountAddressListEntryCreate","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"expiresAt":{"description":"Epoch seconds after which the entry stops applying (must be in the future); omit or null for never. A repeat add replaces the previous expiry.","exclusiveMinimum":0,"type":["integer","null"]},"note":{"description":"Optional descriptive note for this pattern entry","maxLength":500,"type":"string"},"pattern":{"description":"Email address or domain pattern to match (e.g. user@example.com or @domain.com)","maxLength":320,"minLength":1,"type":"string"}},"required":["pattern"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListEntry"}}},"description":"Created or updated entry"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"list_full — maximum allowed pattern entries reached"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Add a pattern to an address list","tags":["Routing"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns all address, domain, and wildcard patterns contained in an address list with pagination.","operationId":"get_AccountAddressListEntryIndex","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListEntryPage"}}},"description":"List of address list pattern entries"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List patterns in an address list","tags":["Routing"]}},"/api/v1/accounts/{accountId}/lists/{listId}/entries/batch":{"post":{"description":"Imports a batch of address and domain patterns into an address list. Invalid patterns are skipped and reported in the response.","operationId":"post_AccountAddressListEntryBatch","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"entries":{"description":"Array of pattern entries to add","items":{"properties":{"expiresAt":{"description":"Epoch seconds after which the entry stops applying (must be in the future); omit or null for never. A repeat add replaces the previous expiry.","exclusiveMinimum":0,"type":["integer","null"]},"note":{"description":"Display-only note","maxLength":500,"type":"string"},"pattern":{"description":"Address pattern: `jo@acme.example`, `@acme.example` (stored `*@acme.example`), `sales-*@acme.example`, or `@.acme.example` for a domain and its subdomains","maxLength":320,"minLength":1,"type":"string"}},"required":["pattern"],"type":"object"},"maxItems":500,"minItems":1,"type":"array"}},"required":["entries"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListBatchResult"}}},"description":"Batch import summary with count of added patterns and array of invalid patterns"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"list_full"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 2 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Add multiple patterns to an address list","tags":["Routing"],"x-max-json-body-bytes":2097152}},"/api/v1/accounts/{accountId}/lists/{listId}/entries/import":{"post":{"description":"Adds every row of a CSV document to the list. Columns are `pattern,note,expires_at`, named by an optional header row or taken by position; `expires_at` is epoch seconds or an ISO 8601 date-time, empty for never. Lines starting with `#` and blank lines are ignored, so a plain one-address-per-line file imports too. Invalid rows (bad pattern, past or unparseable expiry) are skipped and reported; the whole import is refused with 409 `list_full` when the new rows would exceed the list's cap. Idempotent: re-importing an export writes nothing new.","operationId":"post_AccountAddressListEntryImport","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"requestBody":{"content":{"text/csv":{"schema":{"description":"CSV document, at most 1 MiB","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListBatchResult"}}},"description":"Import summary"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"list_full"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"payload_too_large — the document exceeds 1 MiB"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Import patterns into an address list from CSV","tags":["Routing"]}},"/api/v1/accounts/{accountId}/lists/{listId}/entries/export":{"get":{"description":"Returns every live pattern of the list as CSV with the columns `pattern,note,expires_at` (expires_at in epoch seconds, empty for never). The file round-trips through the import endpoint unchanged.","operationId":"get_AccountAddressListEntryExport","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"description":"CSV: pattern,note,expires_at","type":"string"}}},"description":"CSV document"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Export an address list as CSV","tags":["Routing"]}},"/api/v1/accounts/{accountId}/lists/{listId}/entries/{pattern}":{"delete":{"description":"Removes a specific email address or domain pattern from an address list.","operationId":"delete_AccountAddressListEntryDelete","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}},{"description":"Pattern to remove","in":"path","name":"pattern","required":true,"schema":{"description":"Pattern to remove","maxLength":320,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Pattern removed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove a pattern from an address list","tags":["Routing"]}},"/api/v1/accounts/{accountId}/lists/evaluate":{"post":{"description":"Evaluates inbound or outbound address list policies for a specific address to test whether it would be allowed, blocked, or bypassed.","operationId":"post_AccountAddressListEvaluate","parameters":[{"description":"Account identifier","in":"path","name":"accountId","required":true,"schema":{"description":"Account identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"address":{"description":"Target email address to evaluate, taken as vouched. Required unless `envelopeFrom` simulates a message.","maxLength":320,"minLength":3,"type":"string"},"direction":{"description":"Traffic direction ('inbound' or 'outbound')","enum":["inbound","outbound"],"type":"string"},"dmarc":{"description":"Message simulation: the DMARC verdict for the From (`pass` vouches for a single-domain From)","maxLength":64,"type":"string"},"domain":{"description":"Narrow the chain with a domain scope you own. With a mailbox and no domain, the mailbox's own domain, as every delivery door judges it.","type":"string"},"envelopeFrom":{"description":"Message simulation: the envelope sender (empty for a null sender, which skips the catch-all floor as delivery does). Judged with `from`, `spf`, `dmarc` and `submitted` the way an arriving message would be.","maxLength":320,"type":"string"},"from":{"description":"Message simulation: the RFC 5322 From addresses (judged up to the evaluator's own candidate bound, as delivery is)","items":{"maxLength":320,"minLength":3,"type":"string"},"maxItems":100,"type":"array"},"mailboxId":{"description":"…and/or a mailbox scope you own","type":"string"},"spf":{"description":"Message simulation: the SPF verdict for the envelope sender (`pass` vouches for it)","maxLength":64,"type":"string"},"submitted":{"description":"Message simulation: an authenticated local submission, which vouches for the envelope and the From","type":"boolean"}},"required":["direction"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListVerdict"}}},"description":"The verdict, with what decided it"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure — a contact lookup a flagged catch-all required could not answer; retry","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Test address list policy against an address","tags":["Routing"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/lists":{"post":{"description":"Creates an allow or block list at the account, domain, or mailbox scope. Scope, direction, and verdict are immutable once created.","operationId":"post_MailboxAddressListCreate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"contactsExempt":{"description":"Inbound block lists only (else 400): when this list's catch-all decides, let a vouched sender from the receiving mailbox's own address book through. Groups, webhooks and remote routes still need a named allow.","type":"boolean"},"direction":{"description":"Traffic direction ('inbound' or 'outbound')","enum":["inbound","outbound"],"type":"string"},"name":{"description":"Descriptive name for the list","maxLength":120,"minLength":1,"type":"string"},"scopeId":{"description":"Identifier of the domain, mailbox, or account","type":"string"},"scopeKind":{"description":"Required on account routes ('account', 'domain', 'mailbox'); omitted on mailbox routes","enum":["account","domain","mailbox"],"type":"string"},"verdict":{"description":"Policy outcome ('allow' or 'block')","enum":["allow","block"],"type":"string"}},"required":["name","direction","verdict"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressList"}}},"description":"Created address list"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"list_name_taken (name already exists in this scope) or list_limit_reached (maximum lists for this scope reached)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create an address list","tags":["Routing"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns allow and block address lists for this account or mailbox, optionally filtered by scope, direction (inbound/outbound), or verdict (allow/block).","operationId":"get_MailboxAddressListIndex","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Filter by scope kind ('account', 'domain', 'mailbox')","in":"query","name":"scopeKind","required":false,"schema":{"description":"Filter by scope kind ('account', 'domain', 'mailbox')","enum":["account","domain","mailbox"],"type":"string"}},{"description":"Filter by scope identifier","in":"query","name":"scopeId","required":false,"schema":{"description":"Filter by scope identifier","type":"string"}},{"description":"Filter by direction ('inbound', 'outbound')","in":"query","name":"direction","required":false,"schema":{"description":"Filter by direction ('inbound', 'outbound')","enum":["inbound","outbound"],"type":"string"}},{"description":"Filter by policy action ('allow', 'block')","in":"query","name":"verdict","required":false,"schema":{"description":"Filter by policy action ('allow', 'block')","enum":["allow","block"],"type":"string"}},{"description":"`true`: only the lists holding a live catch-all (`*@*`), the \"block all\" lists","in":"query","name":"catchAll","required":false,"schema":{"description":"`true`: only the lists holding a live catch-all (`*@*`), the \"block all\" lists","enum":["true","false"],"type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListPage"}}},"description":"List of address lists"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List address lists","tags":["Routing"]}},"/api/v1/mailboxes/{mailboxId}/lists/{listId}":{"get":{"description":"Returns details of an address list along with its current pattern entry count.","operationId":"get_MailboxAddressListGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressList"}}},"description":"Address list details and entry count"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get an address list","tags":["Routing"]},"patch":{"description":"Renames an address list and/or sets `contactsExempt` (inbound block lists only). Scope, direction and verdict are immutable.","operationId":"patch_MailboxAddressListPatch","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"contactsExempt":{"description":"Inbound block lists only: let the receiving mailbox's contacts through this list's catch-all","type":"boolean"},"name":{"description":"New list name","maxLength":120,"minLength":1,"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressList"}}},"description":"Renamed address list"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"list_name_taken"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): the directory version does not yet support this write; retry","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update an address list","tags":["Routing"],"x-max-json-body-bytes":1048576},"delete":{"description":"Deletes an address list and removes all of its associated address and domain patterns.","operationId":"delete_MailboxAddressListDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Address list deleted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete an address list","tags":["Routing"]}},"/api/v1/mailboxes/{mailboxId}/lists/{listId}/entries":{"post":{"description":"Adds an email address, domain, or wildcard pattern to an address list. Idempotent.","operationId":"post_MailboxAddressListEntryCreate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"expiresAt":{"description":"Epoch seconds after which the entry stops applying (must be in the future); omit or null for never. A repeat add replaces the previous expiry.","exclusiveMinimum":0,"type":["integer","null"]},"note":{"description":"Optional descriptive note for this pattern entry","maxLength":500,"type":"string"},"pattern":{"description":"Email address or domain pattern to match (e.g. user@example.com or @domain.com)","maxLength":320,"minLength":1,"type":"string"}},"required":["pattern"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListEntry"}}},"description":"Created or updated entry"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"list_full — maximum allowed pattern entries reached"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Add a pattern to an address list","tags":["Routing"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns all address, domain, and wildcard patterns contained in an address list with pagination.","operationId":"get_MailboxAddressListEntryIndex","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListEntryPage"}}},"description":"List of address list pattern entries"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List patterns in an address list","tags":["Routing"]}},"/api/v1/mailboxes/{mailboxId}/lists/{listId}/entries/batch":{"post":{"description":"Imports a batch of address and domain patterns into an address list. Invalid patterns are skipped and reported in the response.","operationId":"post_MailboxAddressListEntryBatch","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"entries":{"description":"Array of pattern entries to add","items":{"properties":{"expiresAt":{"description":"Epoch seconds after which the entry stops applying (must be in the future); omit or null for never. A repeat add replaces the previous expiry.","exclusiveMinimum":0,"type":["integer","null"]},"note":{"description":"Display-only note","maxLength":500,"type":"string"},"pattern":{"description":"Address pattern: `jo@acme.example`, `@acme.example` (stored `*@acme.example`), `sales-*@acme.example`, or `@.acme.example` for a domain and its subdomains","maxLength":320,"minLength":1,"type":"string"}},"required":["pattern"],"type":"object"},"maxItems":500,"minItems":1,"type":"array"}},"required":["entries"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListBatchResult"}}},"description":"Batch import summary with count of added patterns and array of invalid patterns"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"list_full"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 2 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Add multiple patterns to an address list","tags":["Routing"],"x-max-json-body-bytes":2097152}},"/api/v1/mailboxes/{mailboxId}/lists/{listId}/entries/import":{"post":{"description":"Adds every row of a CSV document to the list. Columns are `pattern,note,expires_at`, named by an optional header row or taken by position; `expires_at` is epoch seconds or an ISO 8601 date-time, empty for never. Lines starting with `#` and blank lines are ignored, so a plain one-address-per-line file imports too. Invalid rows (bad pattern, past or unparseable expiry) are skipped and reported; the whole import is refused with 409 `list_full` when the new rows would exceed the list's cap. Idempotent: re-importing an export writes nothing new.","operationId":"post_MailboxAddressListEntryImport","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"requestBody":{"content":{"text/csv":{"schema":{"description":"CSV document, at most 1 MiB","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListBatchResult"}}},"description":"Import summary"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"list_full"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"payload_too_large — the document exceeds 1 MiB"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Import patterns into an address list from CSV","tags":["Routing"]}},"/api/v1/mailboxes/{mailboxId}/lists/{listId}/entries/export":{"get":{"description":"Returns every live pattern of the list as CSV with the columns `pattern,note,expires_at` (expires_at in epoch seconds, empty for never). The file round-trips through the import endpoint unchanged.","operationId":"get_MailboxAddressListEntryExport","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"description":"CSV: pattern,note,expires_at","type":"string"}}},"description":"CSV document"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Export an address list as CSV","tags":["Routing"]}},"/api/v1/mailboxes/{mailboxId}/lists/{listId}/entries/{pattern}":{"delete":{"description":"Removes a specific email address or domain pattern from an address list.","operationId":"delete_MailboxAddressListEntryDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"List id","in":"path","name":"listId","required":true,"schema":{"description":"List id","type":"string"}},{"description":"Pattern to remove","in":"path","name":"pattern","required":true,"schema":{"description":"Pattern to remove","maxLength":320,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Pattern removed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"account_credentials_required — a mailbox credential may mutate inbound lists only; outbound lists are administrator-managed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove a pattern from an address list","tags":["Routing"]}},"/api/v1/mailboxes/{mailboxId}/lists/evaluate":{"post":{"description":"Evaluates inbound or outbound address list policies for a specific address to test whether it would be allowed, blocked, or bypassed.","operationId":"post_MailboxAddressListEvaluate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"address":{"description":"Target email address to evaluate, taken as vouched. Required unless `envelopeFrom` simulates a message.","maxLength":320,"minLength":3,"type":"string"},"direction":{"description":"Traffic direction ('inbound' or 'outbound')","enum":["inbound","outbound"],"type":"string"},"dmarc":{"description":"Message simulation: the DMARC verdict for the From (`pass` vouches for a single-domain From)","maxLength":64,"type":"string"},"domain":{"description":"Narrow the chain with a domain scope you own. With a mailbox and no domain, the mailbox's own domain, as every delivery door judges it.","type":"string"},"envelopeFrom":{"description":"Message simulation: the envelope sender (empty for a null sender, which skips the catch-all floor as delivery does). Judged with `from`, `spf`, `dmarc` and `submitted` the way an arriving message would be.","maxLength":320,"type":"string"},"from":{"description":"Message simulation: the RFC 5322 From addresses (judged up to the evaluator's own candidate bound, as delivery is)","items":{"maxLength":320,"minLength":3,"type":"string"},"maxItems":100,"type":"array"},"mailboxId":{"description":"…and/or a mailbox scope you own","type":"string"},"spf":{"description":"Message simulation: the SPF verdict for the envelope sender (`pass` vouches for it)","maxLength":64,"type":"string"},"submitted":{"description":"Message simulation: an authenticated local submission, which vouches for the envelope and the From","type":"boolean"}},"required":["direction"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressListVerdict"}}},"description":"The verdict, with what decided it"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_pattern"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the account, mailbox, scope or list is not accessible"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure — a contact lookup a flagged catch-all required could not answer; retry","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Test address list policy against an address","tags":["Routing"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/filtering":{"get":{"description":"Returns the mailbox's filtering switches: `trustContacts`, whether the mailbox's own address book acts as an implicit allow list against the spam verdict, and `discardIncoming`, whether the mailbox stores nothing it receives.","operationId":"get_FilteringGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilteringSettings"}}},"description":"Filtering settings"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get mailbox filtering settings","tags":["Filtering"]},"put":{"description":"Sets the mailbox's filtering switches; a field the body leaves out keeps its value, and a body naming neither is refused. Turning `trustContacts` off makes address-book membership irrelevant to delivery; explicit allow and block lists are unaffected either way. Turning `discardIncoming` on makes the mailbox keep nothing it receives from then on (mail it already holds stays): each arrival is still accepted, passed to the mailbox's message webhook (however it was routed, catch-all included) and counted as a receive, and the mailbox can still send. It is for a mailbox kept for its sending identity whose mail its message webhook consumes; without one, a discard keeps no copy anywhere. Only an account key or system key may set it.","operationId":"put_FilteringPut","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilteringBody"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilteringSettings"}}},"description":"Updated filtering settings"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed: an invalid request body, or one naming neither switch"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"insufficient_scope (an app password naming discardIncoming: it may read that switch but not change it)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update mailbox filtering settings","tags":["Filtering"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/rules":{"get":{"description":"Returns the structured JSON filter rules for this mailbox, their active status, and the compiled Sieve script source.","operationId":"get_RulesGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterRulesState"}}},"description":"Filter rules document and compiled Sieve script"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No rules for this mailbox, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get mailbox filter rules","tags":["Filtering"]},"put":{"description":"Replaces the JSON filter rules for this mailbox, compiles them into a Sieve script, and activates them for incoming mail delivery.","operationId":"put_RulesPut","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RulesDocument"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterRulesPutResult"}}},"description":"Saved and compiled filter rules"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed rules document; or destination_is_self / destination_loops / destination_chain_too_long when a redirect target routes back to this mailbox; or destination_unverified when a redirect target this save introduces has not been confirmed as a forwarding destination"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_many_scripts; or mailbox_is_group_persona — a group persona's archive runs no rules"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large — rules document exceeds size limit (48 KiB)"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_script — rules compile to an oversized or invalid Sieve script"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Save and activate filter rules","tags":["Filtering"],"x-max-json-body-bytes":786432},"delete":{"description":"Removes all JSON filter rules and deactivates the rules script from incoming delivery.","operationId":"delete_RulesDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterRulesDeleted"}}},"description":"Filter rules deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No rules for this mailbox, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete mailbox filter rules","tags":["Filtering"]}},"/api/v1/mailboxes/{mailboxId}/sieve/capabilities":{"get":{"description":"Returns supported Sieve extensions, maximum allowed scripts per mailbox, and maximum script size in bytes.","operationId":"get_SieveCapabilities","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SieveCapabilities"}}},"description":"Sieve capabilities and engine limits"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get Sieve engine capabilities and limits","tags":["Filtering"]}},"/api/v1/mailboxes/{mailboxId}/sieve/check":{"post":{"description":"Dry-run validates Sieve script syntax and returns line and column numbers on error.","operationId":"post_SieveCheck","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"script":{"description":"Sieve script source code","maxLength":65536,"type":"string"}},"required":["script"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SieveCheckResult"}}},"description":"Validation outcome"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed body"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Validate a Sieve filter script without saving","tags":["Filtering"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/sieve/scripts/{scriptName}":{"put":{"description":"Uploads or updates a Sieve script. The script is validated for syntax before saving. Returns error 422 if compilation fails.","operationId":"put_SievePut","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Sieve script name","in":"path","name":"scriptName","required":true,"schema":{"description":"Sieve script name","maxLength":128,"minLength":1,"pattern":"^(?!\\.{1,2}$)[^/\\\\]+$","type":"string"}},{"description":"Set to \"*\" for create-only: prevents overwriting an existing script of the same name","in":"header","name":"if-none-match","required":false,"schema":{"description":"Set to \"*\" for create-only: prevents overwriting an existing script of the same name","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"script":{"description":"Sieve script source code","maxLength":65536,"type":"string"}},"required":["script"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SievePutResult"}}},"description":"Script saved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed name or body; or destination_is_self / destination_loops / destination_chain_too_long when a redirect target routes back to this mailbox; or destination_unverified when a redirect target this write introduces has not been confirmed as a forwarding destination"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"reserved — this script name is reserved for JSON rules"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_many_scripts, name_exists, or mailbox_is_group_persona (a group persona's archive runs no script)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_script — Sieve syntax error with line and column"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Upload or replace a Sieve filter script","tags":["Filtering"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns the raw Sieve source code and active status for a specific script.","operationId":"get_SieveGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Sieve script name","in":"path","name":"scriptName","required":true,"schema":{"description":"Sieve script name","maxLength":128,"minLength":1,"pattern":"^(?!\\.{1,2}$)[^/\\\\]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SieveScriptBody"}}},"description":"Sieve script source code and metadata"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed script name"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such script, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get Sieve filter script source","tags":["Filtering"]},"delete":{"description":"Deletes a stored Sieve script from this mailbox.","operationId":"delete_SieveDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Sieve script name","in":"path","name":"scriptName","required":true,"schema":{"description":"Sieve script name","maxLength":128,"minLength":1,"pattern":"^(?!\\.{1,2}$)[^/\\\\]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SieveDeleted"}}},"description":"Script deleted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed script name"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"reserved — this script is managed by the JSON rules endpoint"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such script, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"script_active — this is the active script (RFC 5804 §2.10); deactivate it (DELETE …/sieve/active) or activate another first"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete a Sieve filter script","tags":["Filtering"]}},"/api/v1/mailboxes/{mailboxId}/sieve/scripts":{"get":{"description":"Returns all Sieve filtering scripts stored in this mailbox along with their active status and update timestamps.","operationId":"get_SieveList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"scripts":{"items":{"$ref":"#/components/schemas/SieveScript"},"type":"array"}},"required":["scripts"],"type":"object"}}},"description":"List of Sieve scripts"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List Sieve filter scripts","tags":["Filtering"]}},"/api/v1/mailboxes/{mailboxId}/sieve/scripts/{scriptName}/rename":{"post":{"description":"Renames an existing Sieve script while preserving its active status.","operationId":"post_SieveRename","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Sieve script name","in":"path","name":"scriptName","required":true,"schema":{"description":"Sieve script name","maxLength":128,"minLength":1,"pattern":"^(?!\\.{1,2}$)[^/\\\\]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"newName":{"description":"New name for the script","maxLength":128,"minLength":1,"pattern":"^(?!\\.{1,2}$)[^/\\\\]+$","type":"string"}},"required":["newName"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SieveRenamed"}}},"description":"Script renamed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed name"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"reserved — the new name is reserved for JSON rules"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such script, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"name_exists — a script with the new name already exists; or mailbox_is_group_persona (a group persona's archive runs no script)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Rename a Sieve filter script","tags":["Filtering"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/sieve/active":{"put":{"description":"Designates a specific script as the active filter for incoming mail delivery in this mailbox.","operationId":"put_SieveActivate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"description":"Name of the script to activate","maxLength":128,"minLength":1,"pattern":"^(?!\\.{1,2}$)[^/\\\\]+$","type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SieveActivated"}}},"description":"Script activated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed script name"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such script, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_is_group_persona — a group persona's archive runs no script"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Activate a Sieve filter script","tags":["Filtering"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns the name of the currently active Sieve script, or null if no filter script is active.","operationId":"get_SieveActiveGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SieveActiveName"}}},"description":"Active script name"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get active Sieve filter script name","tags":["Filtering"]},"delete":{"description":"Disables filtering on incoming mail delivery so all incoming mail delivers directly without rules.","operationId":"delete_SieveDeactivate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SieveDeactivated"}}},"description":"Deactivation confirmed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Deactivate the active Sieve filter script","tags":["Filtering"]}},"/api/v1/mailboxes/{mailboxId}/vacation":{"get":{"description":"Returns the mailbox's out-of-office vacation auto-responder configuration and state token for optimistic locking.","operationId":"get_VacationGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vacation"}}},"description":"Vacation auto-responder settings and state token"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get out-of-office auto-reply settings","tags":["Filtering"]},"put":{"description":"Configures or replaces the out-of-office auto-responder settings. Supports optimistic locking via the If-Match header with the state token.","operationId":"put_VacationPut","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Expected state token for optimistic locking (omit for unconditional update)","in":"header","name":"if-match","required":false,"schema":{"description":"Expected state token for optimistic locking (omit for unconditional update)","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"fromDate":{"default":null,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","type":["string","null"]},"htmlBody":{"default":null,"maxLength":32768,"type":["string","null"]},"isEnabled":{"type":"boolean"},"subject":{"default":null,"maxLength":512,"type":["string","null"]},"textBody":{"default":null,"maxLength":32768,"type":["string","null"]},"toDate":{"default":null,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","type":["string","null"]}},"required":["isEnabled"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vacation"}}},"description":"Updated vacation configuration and new state token"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — invalid request body"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"412":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"state_conflict — state token does not match current version"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_window (fromDate must be before toDate) or empty_body"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update out-of-office auto-reply settings","tags":["Filtering"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/forwarding":{"get":{"description":"Returns every address this mailbox has named for forwarding, with its verification state, plus the forward-everything setting. Never returns a confirmation code.","operationId":"get_ForwardingGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forwarding"}}},"description":"Destinations and the forward-everything setting"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get forwarding destinations and settings","tags":["Filtering"]}},"/api/v1/mailboxes/{mailboxId}/forwarding/all":{"put":{"description":"Points forward-everything at a verified destination, and resumes it if it was paused. Junk, bounce and daemon mail are never forwarded.","operationId":"put_ForwardingAllSet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"destinationId":{"description":"A verified destination to receive a copy of all mail","maxLength":64,"minLength":1,"type":"string"}},"required":["destinationId"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forwarding"}}},"description":"Forwarding is on"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed; or destination_is_self / destination_loops / destination_chain_too_long when the destination now routes back to this mailbox; or destination_not_permitted when the account's allowlist no longer permits it; or destination_fans_out when its address now resolves to something we host that reaches more than one party. All five are re-checked here because this is the write that arms the forward, and a route proved as a single mailbox may have been retargeted to a group since; or destination_unverified (carrying the address as `target`) when the destination has not proved a code, or its proof was revoked. A destination_loops found only while the forward is published (a loop closed after the check above) also carries `forwardAll`, the setting as it now stands: the refused write cleared the forward it replaced, so it reads off"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or destination not found, or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"inbound_edge_cap — the destination already receives the most forwards an address may. Carries `forwardAll`, the setting as it now stands: the refused write cleared the forward it replaced, so it reads off"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Forward all mail to a destination","tags":["Filtering"],"x-max-json-body-bytes":1048576},"patch":{"description":"Pauses or resumes forward-everything without touching the destination: a paused forward keeps its proof, so resuming never re-verifies.","operationId":"patch_ForwardingAllPause","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"paused":{"description":"True to pause forwarding, false to resume. Never re-verifies the destination","type":"boolean"}},"required":["paused"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forwarding"}}},"description":"The new state"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found, or forwarding is not set"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Pause or resume forwarding","tags":["Filtering"],"x-max-json-body-bytes":1048576},"delete":{"description":"Switches forward-everything off. Destinations survive — they are proven, and re-proving them to resume would be punitive.","operationId":"delete_ForwardingAllClear","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forwarding"}}},"description":"Forwarding is off"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Stop forwarding all mail","tags":["Filtering"]}},"/api/v1/mailboxes/{mailboxId}/forwarding/destinations":{"post":{"description":"Names an address and mails it an eight-character confirmation code, valid for 24 hours. The destination forwards nothing until the code is confirmed. Re-posting an address that already exists re-mails a fresh code rather than refusing, which is also how a destination the recipient revoked is re-proved.","operationId":"post_ForwardingDestinationAdd","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"address":{"description":"The address to forward to","maxLength":320,"minLength":3,"type":"string"}},"required":["address"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForwardingDestinationPending"}}},"description":"The destination is pending and a code has been mailed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed; or destination_is_self / destination_loops / destination_chain_too_long when the address routes back to this mailbox; or destination_not_permitted when the account's allowlist refuses it; or destination_fans_out when the address is one we host that reaches more than one party (a group, alias, webhook or onward-forwarding route), which cannot consent to the confirmation code or hold the disable link"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_many_destinations — the per-mailbox cap is reached; remove one first"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"resend_cooldown — a code was mailed to this address recently; or rate_limited, with Retry-After, when this mailbox's confirmation-mail budget is spent. The two are deliberately not distinguishable further: the budget is partly shared per destination address across the deployment","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"forwarding_mail_unavailable — the confirmation could not be sent for a reason on the platform's side (the mail binding is unconfigured, or the sending service refused the message), so no pending row is stored and the request may be retried. A refusal that concerns the destination address itself is deliberately indistinguishable from a sent code. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Add a forwarding destination","tags":["Filtering"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/forwarding/destinations/{destId}/verify":{"post":{"description":"Spends the code mailed to the destination. Five wrong codes end the ceremony. Confirming invalidates every disable link previously mailed for it.","operationId":"post_ForwardingDestinationVerify","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Forwarding destination ULID","in":"path","name":"destId","required":true,"schema":{"description":"Forwarding destination ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"description":"The eight-character code mailed to the destination","maxLength":64,"minLength":1,"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForwardingDestinationVerified"}}},"description":"The destination is verified"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed; or no_pending_code, meaning nothing is awaiting confirmation or the code expired"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_code, with attemptsLeft; or confirmation_cleared, meaning that was the fifth wrong code. Add the address again for a fresh one"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or destination not found, or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Confirm a forwarding destination","tags":["Filtering"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/forwarding/destinations/{destId}":{"delete":{"description":"Removes the destination and clears the forward-everything setting if it pointed there. Filter rules redirecting to the address stop forwarding at the next delivery.","operationId":"delete_ForwardingDestinationDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Forwarding destination ULID","in":"path","name":"destId","required":true,"schema":{"description":"Forwarding destination ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Removed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or destination not found, or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove a forwarding destination","tags":["Filtering"]}},"/api/v1/forwarding/disable/{token}":{"get":{"description":"Public. Renders a confirmation page for the recipient of forwarded mail; the page's form (and RFC 8058 one-click) POSTs to the same URL. A GET never revokes anything — link scanners prefetch URLs. No bearer credential: the signed token in the path IS the credential, and its holder is a stranger receiving forwarded mail.","operationId":"get_ForwardingDisablePage","parameters":[{"description":"Signed disable-link token","in":"path","name":"token","required":true,"schema":{"description":"Signed disable-link token","maxLength":2048,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"text/html":{"schema":{"type":"string"}}},"description":"Confirmation page"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Invalid, superseded, or unknown link (indistinguishable)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"security":[],"summary":"Forwarding disable link (confirmation page)","tags":["Filtering"]},"post":{"description":"Public. Revokes the destination: forward-everything and every filter rule redirecting to this address stop at the next delivery. Idempotent — a second POST finds it already revoked. Serves both the confirmation page's form and RFC 8058 one-click POSTs. No bearer credential: the signed token in the path IS the credential.","operationId":"post_ForwardingDisableRevoke","parameters":[{"description":"Signed disable-link token","in":"path","name":"token","required":true,"schema":{"description":"Signed disable-link token","maxLength":2048,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"text/html":{"schema":{"type":"string"}}},"description":"Forwarding stopped (or already stopped)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Invalid, superseded, or unknown link (indistinguishable)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"security":[],"summary":"Forwarding disable link (revoke)","tags":["Filtering"]}},"/api/v1/mailboxes/{mailboxId}/labels":{"post":{"description":"Creates a new user folder or label with a fresh UID validity epoch.","operationId":"post_LabelCreate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"color":{"description":"Hex color code for the label badge/chip, or null","pattern":"^#[0-9a-f]{6}$","type":["string","null"]},"name":{"description":"Name for the new label. May not start with `*`, which clients reserve for their own views","maxLength":255,"minLength":1,"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedLabel"}}},"description":"Created label details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed name or color"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"label_exists — a label with this name already exists; or too_many_labels — the mailbox is at its ceiling of 500 labels (system labels are not counted), and a retry under another name cannot help. Delete one first"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create a new custom label","tags":["Labels"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns all system and custom labels with message counts, unread counts, UID validity, and next UID sequence numbers. Listing requires the lookup (`l`) right. With `name`, returns only that exact label's statistics and requires read (`r`) instead, so a reader can check a known folder without enumerating the mailbox. An unknown or out-of-scope name returns an empty labels array; wildcard characters are literal. For the owner identity, an unfiltered listing also reports how many sends are scheduled and not yet released, so a client can decide whether to offer a Scheduled view without a second request.","operationId":"get_LabelList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Exact label name for a read-authorized statistics query; no wildcard expansion","in":"query","name":"name","required":false,"schema":{"description":"Exact label name for a read-authorized statistics query; no wildcard expansion","maxLength":255,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"labels":[{"bytes":52428800,"color":null,"deletedCount":0,"highestModseq":91842,"id":1,"isSubscribed":true,"messageCount":128,"name":"INBOX","role":"inbox","sortOrder":0,"uidNext":4214,"uidValidity":1722470400,"unseenCount":3},{"bytes":18874368,"color":null,"deletedCount":0,"highestModseq":91842,"id":2,"isSubscribed":true,"messageCount":431,"name":"Sent","role":"sent","sortOrder":1,"uidNext":887,"uidValidity":1722470400,"unseenCount":0},{"bytes":2097152,"color":"#4a90e2","deletedCount":0,"highestModseq":91710,"id":7,"isSubscribed":true,"messageCount":41,"name":"Receipts","role":null,"sortOrder":6,"uidNext":42,"uidValidity":1722470400,"unseenCount":0}],"scheduledPending":1},"schema":{"$ref":"#/components/schemas/LabelListPage"}}},"description":"List of labels"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed name"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List mailbox labels and folder statistics","tags":["Labels"]}},"/api/v1/mailboxes/{mailboxId}/labels/{label}":{"patch":{"description":"Renames a custom label and/or updates its display sort order, subscription state, and color. System labels cannot be renamed, but their sortOrder, isSubscribed, and color settings can still be updated.\n\n`withChildren: true` carries every `Old/…` sub-label with the rename, in one commit that is validated whole before it writes — so the tree cannot be left half-renamed. Filter rules naming any moved label follow it, and so do pickup sources that deliver into one. Raw user Sieve scripts are NOT rewritten.","operationId":"patch_LabelRename","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Label or folder name (e.g. INBOX, Archive, custom)","in":"path","name":"label","required":true,"schema":{"description":"Label or folder name (e.g. INBOX, Archive, custom)","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"color":{"description":"Hex color code for the label badge/chip, or null to clear","pattern":"^#[0-9a-f]{6}$","type":["string","null"]},"isSubscribed":{"description":"Whether folder is subscribed for client sync","type":"boolean"},"name":{"description":"New label name (custom labels only). May not start with `*`","maxLength":255,"minLength":1,"type":"string"},"sortOrder":{"description":"Presentation display sort order index","maximum":2147483647,"minimum":0,"type":"integer"},"withChildren":{"description":"With `name`, carry every `Old/…` sub-label along in the same commit. The whole move is validated before any of it is written, so it cannot half-apply. Default false, which leaves sub-labels under their old prefix.","type":"boolean"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenamedResult"}}},"description":"Update successful"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed name/sortOrder or empty patch"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"System labels cannot be renamed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or label not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Target label name already exists"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Rename a label or update folder settings","tags":["Labels"],"x-max-json-body-bytes":1048576},"delete":{"description":"Deletes a custom label. Messages carrying this label will retain any other labels they have. Messages with no other labels are expunged (moved to Recently deleted) by default, or moved to Archive when `?orphans=archive` is passed.\n\nFolder-scoped shares follow the folder into deletion: the folder is removed from every grant that names it, and a grant left naming no folders is revoked outright — the person it was shared with stops seeing the mailbox at once, exactly as if the grant had been DELETEd. Whole-mailbox grants are unaffected.","operationId":"delete_LabelDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Label or folder name (e.g. INBOX, Archive, custom)","in":"path","name":"label","required":true,"schema":{"description":"Label or folder name (e.g. INBOX, Archive, custom)","type":"string"}},{"description":"What to do if deleting this label leaves a message with no labels. expunge (default) moves it to the Recently-deleted tier; archive attaches the Archive label instead","in":"query","name":"orphans","required":false,"schema":{"description":"What to do if deleting this label leaves a message with no labels. expunge (default) moves it to the Recently-deleted tier; archive attaches the Archive label instead","enum":["expunge","archive"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelDeleteResult"}}},"description":"Deletion outcome"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"System labels cannot be deleted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or label not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"folder_shared — folder-scoped grants name this label, so deleting it would revoke them, which is the `a` right: use a full-scope credential, or remove the grants first"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large — the label refilled past the one-commit ceiling while it was being drained; retry. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete a custom label","tags":["Labels"]}},"/api/v1/mailboxes/{mailboxId}/labels/by-id/{labelId}":{"patch":{"description":"Keyed on the label's numeric `id` — as `GET /labels` and `POST /labels` report it — rather than on its name. The id survives a rename (it is what JMAP `Mailbox/set` and folder-scoped shares key on), so a client that renames folders should hold it: the by-name route's key changes as the operation succeeds. It also never contains a `/`, so a folder name that does need not be encoded into a path segment. Otherwise identical to the by-name operation.\n\nRenames a custom label and/or updates its display sort order, subscription state, and color. System labels cannot be renamed, but their sortOrder, isSubscribed, and color settings can still be updated.\n\n`withChildren: true` carries every `Old/…` sub-label with the rename, in one commit that is validated whole before it writes — so the tree cannot be left half-renamed. Filter rules naming any moved label follow it, and so do pickup sources that deliver into one. Raw user Sieve scripts are NOT rewritten.","operationId":"patch_LabelRenameById","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"The label's numeric `id`, as `GET /labels` and `POST /labels` report it","in":"path","name":"labelId","required":true,"schema":{"description":"The label's numeric `id`, as `GET /labels` and `POST /labels` report it","exclusiveMinimum":0,"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"color":{"description":"Hex color code for the label badge/chip, or null to clear","pattern":"^#[0-9a-f]{6}$","type":["string","null"]},"isSubscribed":{"description":"Whether folder is subscribed for client sync","type":"boolean"},"name":{"description":"New label name (custom labels only). May not start with `*`","maxLength":255,"minLength":1,"type":"string"},"sortOrder":{"description":"Presentation display sort order index","maximum":2147483647,"minimum":0,"type":"integer"},"withChildren":{"description":"With `name`, carry every `Old/…` sub-label along in the same commit. The whole move is validated before any of it is written, so it cannot half-apply. Default false, which leaves sub-labels under their old prefix.","type":"boolean"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenamedResult"}}},"description":"Update successful"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed name/sortOrder or empty patch"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"System labels cannot be renamed"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or label not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Target label name already exists"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Rename a label or update folder settings, by id","tags":["Labels"],"x-max-json-body-bytes":1048576},"delete":{"description":"Keyed on the label's numeric `id` — as `GET /labels` and `POST /labels` report it — rather than on its name. The id survives a rename (it is what JMAP `Mailbox/set` and folder-scoped shares key on), so a client that renames folders should hold it: the by-name route's key changes as the operation succeeds. It also never contains a `/`, so a folder name that does need not be encoded into a path segment. Otherwise identical to the by-name operation.\n\nDeletes a custom label. Messages carrying this label will retain any other labels they have. Messages with no other labels are expunged (moved to Recently deleted) by default, or moved to Archive when `?orphans=archive` is passed.\n\nFolder-scoped shares follow the folder into deletion: the folder is removed from every grant that names it, and a grant left naming no folders is revoked outright — the person it was shared with stops seeing the mailbox at once, exactly as if the grant had been DELETEd. Whole-mailbox grants are unaffected.","operationId":"delete_LabelDeleteById","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"The label's numeric `id`, as `GET /labels` and `POST /labels` report it","in":"path","name":"labelId","required":true,"schema":{"description":"The label's numeric `id`, as `GET /labels` and `POST /labels` report it","exclusiveMinimum":0,"type":"integer"}},{"description":"What to do if deleting this label leaves a message with no labels. expunge (default) moves it to the Recently-deleted tier; archive attaches the Archive label instead","in":"query","name":"orphans","required":false,"schema":{"description":"What to do if deleting this label leaves a message with no labels. expunge (default) moves it to the Recently-deleted tier; archive attaches the Archive label instead","enum":["expunge","archive"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelDeleteResult"}}},"description":"Deletion outcome"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"System labels cannot be deleted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or label not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"folder_shared — folder-scoped grants name this label, so deleting it would revoke them, which is the `a` right: use a full-scope credential, or remove the grants first"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large — the label refilled past the one-commit ceiling while it was being drained; retry. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete a custom label, by id","tags":["Labels"]}},"/api/v1/mailboxes/{mailboxId}/labels/{label}/messages":{"get":{"description":"Returns messages in a label ordered by UID, optionally filtered by a minimum and maximum UID range.","operationId":"get_LabelMessageList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Label or folder name (e.g. INBOX, Archive, custom)","in":"path","name":"label","required":true,"schema":{"description":"Label or folder name (e.g. INBOX, Archive, custom)","type":"string"}},{"description":"Minimum UID inclusive","in":"query","name":"uidMin","required":false,"schema":{"description":"Minimum UID inclusive","minimum":1,"type":"integer"}},{"description":"Maximum UID inclusive","in":"query","name":"uidMax","required":false,"schema":{"description":"Maximum UID inclusive","minimum":1,"type":"integer"}},{"description":"Maximum messages to return (default 25, max 1000)","in":"query","name":"limit","required":false,"schema":{"description":"Maximum messages to return (default 25, max 1000)","maximum":1000,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"messages":{"description":"List of message metadata summaries","items":{"$ref":"#/components/schemas/MessageMeta"},"type":"array"},"uidValidity":{"description":"UIDVALIDITY epoch of the label","format":"int64","type":"integer"}},"required":["messages","uidValidity"],"type":"object"}}},"description":"Messages with per-label UID and validity epoch"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed UID range or limit"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or label not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List messages in a label by UID","tags":["Labels"]},"patch":{"description":"Applies one patch to a UID RANGE of this label — the write twin of GET /labels/{label}/messages, and the way to act on a whole folder without naming its messages. PATCH /messages takes at most 200 ids, so \"archive everything in this folder\" means downloading every id and sending hundreds of calls, racing every arrival in between. Here the selection is a RULE the store resolves inside the same turn that writes it.\n\nTHE CEILING IS THE POINT. `uidMax` is resolved once and fixes the working set: a label's UIDs only increase and are never reused within a `uidValidity`, so mail that arrives — or that a rule files here — while the call runs takes a UID above the ceiling and is never touched. A client that showed a user \"all 5,420 messages\" can therefore act on the 5,420 they were looking at. Read `uidNext` from GET /labels and send `uidMax` = `uidNext - 1` with that response's `uidValidity` beside it.\n\nIT MAY ANSWER A CURSOR. The call spends a bounded budget and then stops, because the store is single-threaded and a mailbox has no size limit. `nextAfter` non-null means call again with `after` set to it, the same `uidMax` and the same patch, until it is null; `remaining` says how many memberships are left. Ordinary folders finish in one call. Every chunk has committed, so stopping early leaves the store consistent and the gesture partial — which is what `remaining` is there to make visible. Repeating a call is harmless.\n\nConversations do not enter into it: the patch reaches the messages FILED UNDER this label, which is what `threadLabelOnly` means on PATCH /messages. Removing a message's last label expunges it to the Recently-deleted tier, restorable until purge, exactly as it does by id.","operationId":"patch_LabelMessagesUpdate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Label or folder name (e.g. INBOX, Archive, custom)","in":"path","name":"label","required":true,"schema":{"description":"Label or folder name (e.g. INBOX, Archive, custom)","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"after":{"description":"Continuation cursor: resume above this UID. Pass the previous call's `nextAfter`.","format":"int64","minimum":0,"type":"integer"},"flagsClear":{"description":"Flags to remove","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"flagsSet":{"description":"Flags to set","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"hasFlags":{"description":"Narrow the selection to messages with ALL of these flags set","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"keywordsClear":{"description":"Custom keywords to remove","items":{"type":"string"},"type":"array"},"keywordsExact":{"description":"Exact replacement list of custom keywords","items":{"type":"string"},"type":"array"},"keywordsSet":{"description":"Custom keywords to add","items":{"type":"string"},"type":"array"},"labelsAdd":{"description":"Labels to add","items":{"type":"string"},"type":"array"},"labelsExact":{"description":"Exact replacement list of labels","items":{"type":"string"},"type":"array"},"labelsRemove":{"description":"Labels to remove","items":{"type":"string"},"type":"array"},"limit":{"description":"Lower the per-call update budget, for a client that wants finer progress than the server's own bound gives. Never raises it.","minimum":1,"type":"integer"},"notFlags":{"description":"Narrow the selection to messages with NONE of these set — `[\"seen\"]` for the unread-only gesture a folder's unread badge implies","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"orphans":{"description":"What to do if this write would leave the message with no label. 'expunge' (the default) sends the message to Recently deleted. 'archive' keeps the message live by attaching the Archive system label (attaching Archive needs no right beyond the grant's 't' for a scoped viewer). If the write removes Archive itself and would leave no labels, Archive is kept without error. A SCOPED viewer whose write lands the message in Archive has moved it out of their own scope: the answer is still `updated`, and the hydrated message carries an EMPTY `labels` list rather than naming a label the grant never included. `labelsAdded` omits Archive for the same reason.","enum":["expunge","archive"],"type":"string"},"uidMax":{"description":"Inclusive UID ceiling — the selection is every member with uid <= this. Omitted on a FIRST call, the label's current highest UID is used and echoed back. REQUIRED once `after` is given, so a continuation cannot move its own ceiling and sweep in mail that arrived mid-gesture.","format":"int64","minimum":1,"type":"integer"},"uidValidity":{"description":"Precondition: refuse with 409 uid_validity_mismatch unless the label still carries this epoch. A bump means the UIDs this selection was taken over no longer name the same messages.","format":"int64","type":"integer"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelMessagesUpdateResult"}}},"description":"Counts for this call, and a cursor if the range is not drained"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, patch_required (no change named), uidmax_required (after without uidMax), unknown_label (a name in the patch), or invalid_keyword"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or label not found, or outside this principal's folder grant"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"uid_validity_mismatch — the label's UIDVALIDITY is not the one given"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update flags, labels and keywords for every message in a folder","tags":["Labels"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/labels/by-id/{labelId}/messages":{"patch":{"description":"Keyed on the label's numeric `id` — as `GET /labels` and `POST /labels` report it — rather than on its name. The id survives a rename (it is what JMAP `Mailbox/set` and folder-scoped shares key on), so a client that renames folders should hold it: the by-name route's key changes as the operation succeeds. It also never contains a `/`, so a folder name that does need not be encoded into a path segment. Otherwise identical to the by-name operation.\n\nThis is the spelling a browser client needs: a nested folder IS the label called `Work/Projects`, and a name carrying a `/` cannot be a path segment.","operationId":"patch_LabelMessagesUpdateById","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"The label's numeric `id`, as `GET /labels` and `POST /labels` report it","in":"path","name":"labelId","required":true,"schema":{"description":"The label's numeric `id`, as `GET /labels` and `POST /labels` report it","exclusiveMinimum":0,"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"after":{"description":"Continuation cursor: resume above this UID. Pass the previous call's `nextAfter`.","format":"int64","minimum":0,"type":"integer"},"flagsClear":{"description":"Flags to remove","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"flagsSet":{"description":"Flags to set","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"hasFlags":{"description":"Narrow the selection to messages with ALL of these flags set","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"keywordsClear":{"description":"Custom keywords to remove","items":{"type":"string"},"type":"array"},"keywordsExact":{"description":"Exact replacement list of custom keywords","items":{"type":"string"},"type":"array"},"keywordsSet":{"description":"Custom keywords to add","items":{"type":"string"},"type":"array"},"labelsAdd":{"description":"Labels to add","items":{"type":"string"},"type":"array"},"labelsExact":{"description":"Exact replacement list of labels","items":{"type":"string"},"type":"array"},"labelsRemove":{"description":"Labels to remove","items":{"type":"string"},"type":"array"},"limit":{"description":"Lower the per-call update budget, for a client that wants finer progress than the server's own bound gives. Never raises it.","minimum":1,"type":"integer"},"notFlags":{"description":"Narrow the selection to messages with NONE of these set — `[\"seen\"]` for the unread-only gesture a folder's unread badge implies","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"orphans":{"description":"What to do if this write would leave the message with no label. 'expunge' (the default) sends the message to Recently deleted. 'archive' keeps the message live by attaching the Archive system label (attaching Archive needs no right beyond the grant's 't' for a scoped viewer). If the write removes Archive itself and would leave no labels, Archive is kept without error. A SCOPED viewer whose write lands the message in Archive has moved it out of their own scope: the answer is still `updated`, and the hydrated message carries an EMPTY `labels` list rather than naming a label the grant never included. `labelsAdded` omits Archive for the same reason.","enum":["expunge","archive"],"type":"string"},"uidMax":{"description":"Inclusive UID ceiling — the selection is every member with uid <= this. Omitted on a FIRST call, the label's current highest UID is used and echoed back. REQUIRED once `after` is given, so a continuation cannot move its own ceiling and sweep in mail that arrived mid-gesture.","format":"int64","minimum":1,"type":"integer"},"uidValidity":{"description":"Precondition: refuse with 409 uid_validity_mismatch unless the label still carries this epoch. A bump means the UIDs this selection was taken over no longer name the same messages.","format":"int64","type":"integer"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelMessagesUpdateResult"}}},"description":"Counts for this call, and a cursor if the range is not drained"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"As the by-name route"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or label not found, or outside this principal's folder grant"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"uid_validity_mismatch — the label's UIDVALIDITY is not the one given"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update flags, labels and keywords for every message in a folder, by label id","tags":["Labels"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/labels/{label}/uids":{"get":{"description":"Returns compact message records (UID, MODSEQ, flags, size, dates) ordered by UID for efficient folder synchronization (up to 10,000 per page).","operationId":"get_LabelUidList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Label or folder name (e.g. INBOX, Archive, custom)","in":"path","name":"label","required":true,"schema":{"description":"Label or folder name (e.g. INBOX, Archive, custom)","type":"string"}},{"description":"Minimum UID inclusive","in":"query","name":"uidMin","required":false,"schema":{"description":"Minimum UID inclusive","minimum":1,"type":"integer"}},{"description":"Maximum UID inclusive","in":"query","name":"uidMax","required":false,"schema":{"description":"Maximum UID inclusive","minimum":1,"type":"integer"}},{"description":"Maximum items to return (default 1000, max 10000)","in":"query","name":"limit","required":false,"schema":{"description":"Maximum items to return (default 1000, max 10000)","maximum":10000,"minimum":1,"type":"integer"}},{"description":"UID order within the page (default asc). `desc` pages from the newest end, for a client that must keep the NEWEST N under a row cap.","in":"query","name":"order","required":false,"schema":{"description":"UID order within the page (default asc). `desc` pages from the newest end, for a client that must keep the NEWEST N under a row cap.","enum":["asc","desc"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelUidPage"}}},"description":"Message index page with UID validity"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed UID range or limit"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or label not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List message sync index for a label","tags":["Labels"]}},"/api/v1/mailboxes/{mailboxId}/labels/{label}/vanished":{"get":{"description":"Returns UIDs of messages expunged from the label since a specified change sequence (MODSEQ) number.","operationId":"get_LabelVanished","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Label or folder name (e.g. INBOX, Archive, custom)","in":"path","name":"label","required":true,"schema":{"description":"Label or folder name (e.g. INBOX, Archive, custom)","type":"string"}},{"description":"Find UIDs expunged after this MODSEQ change sequence number","in":"query","name":"changedSince","required":false,"schema":{"description":"Find UIDs expunged after this MODSEQ change sequence number","minimum":0,"type":["integer","null"]}},{"description":"Maximum UIDs to return per page (max 2000)","in":"query","name":"limit","required":false,"schema":{"description":"Maximum UIDs to return per page (max 2000)","maximum":2000,"minimum":1,"type":"integer"}},{"description":"Pagination cursor for next page","in":"query","name":"cursor","required":false,"schema":{"description":"Pagination cursor for next page","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VanishedResult"}}},"description":"List of vanished UIDs and current highest change sequence number"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — malformed query"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or label not found"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"cannot_calculate_changes — requested modseq predates change tracking window"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List vanished (expunged) message UIDs","tags":["Labels"]}},"/api/v1/mailboxes/{mailboxId}/labels/{label}/expunge":{"post":{"description":"Detaches messages marked with the deleted flag from this label. Messages left with no remaining labels move to Recently deleted and can be restored until permanent purge.","operationId":"post_LabelExpunge","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Label or folder name (e.g. INBOX, Archive, custom)","in":"path","name":"label","required":true,"schema":{"description":"Label or folder name (e.g. INBOX, Archive, custom)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpungeResult"}}},"description":"Expunged message list"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or label not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Expunge deleted messages from a label","tags":["Labels"]}},"/api/v1/mailboxes/{mailboxId}/pickups":{"post":{"description":"Configures a remote POP3 email account to automatically fetch messages into this mailbox at a periodic interval.","operationId":"post_PickupCreate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"deleteAfterFetch":{"type":"boolean"},"host":{"maxLength":255,"minLength":1,"type":"string"},"intervalMinutes":{"maximum":1440,"minimum":5,"type":"integer"},"labelName":{"maxLength":255,"minLength":1,"type":"string"},"markRead":{"type":"boolean"},"mode":{"description":"sync = keep collecting; import = complete once the remote mailbox is drained and quiet for quietDays, then switch off and forget the password","enum":["sync","import"],"type":"string"},"name":{"maxLength":128,"type":"string"},"password":{"maxLength":1024,"minLength":1,"type":"string"},"port":{"maximum":65535,"minimum":1,"type":"integer"},"quietDays":{"description":"Days without a newly stored message, after a drained run, that complete an import (default 7)","maximum":90,"minimum":1,"type":"integer"},"tls":{"enum":["tls","starttls"],"type":"string"},"username":{"maxLength":320,"minLength":1,"type":"string"}},"required":["host","port","username","password"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PickupSource"}}},"description":"Created pickup source"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed; or source_is_self when the credentials would open the very mailbox this source delivers into. Pulling from ANOTHER mailbox on this platform is supported"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"duplicate_source — same host and username already configured for this mailbox; pickup_limit_reached — the mailbox already holds the maximum number of sources (`limit` says how many), a ceiling rather than a rate, so it is not retried; or conflict — destination preparation expired or is unavailable, so retry"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"pickup_not_configured — this deployment has no PICKUP_KEK, so a source password cannot be stored. temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create POP3 pickup source","tags":["Pickups"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns all configured POP3 pickup sources for this mailbox with pagination.","operationId":"get_PickupList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"},"pickups":{"items":{"$ref":"#/components/schemas/PickupSource"},"type":"array"}},"required":["pickups"],"type":"object"}}},"description":"Page of pickup sources"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List POP3 pickup sources","tags":["Pickups"]}},"/api/v1/mailboxes/{mailboxId}/pickups/{pickupId}":{"get":{"description":"Returns details of a specific POP3 pickup source including host, port, polling interval, and last run status.","operationId":"get_PickupGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Pickup source identifier","in":"path","name":"pickupId","required":true,"schema":{"description":"Pickup source identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PickupSource"}}},"description":"Pickup source details"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Not found or not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get a POP3 pickup source","tags":["Pickups"]},"patch":{"description":"Updates configuration settings for a POP3 pickup source such as polling interval, credentials, or enable status.","operationId":"patch_PickupUpdate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Pickup source identifier","in":"path","name":"pickupId","required":true,"schema":{"description":"Pickup source identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"deleteAfterFetch":{"description":"Whether to delete messages from remote POP3 server after fetch","type":"boolean"},"enabled":{"description":"Whether this pickup source is active. Re-enabling a completed import needs `password` in the same request (400 password_required): completion forgot it","type":"boolean"},"host":{"description":"POP3 server hostname or IP address","maxLength":255,"minLength":1,"type":"string"},"intervalMinutes":{"description":"Polling interval in minutes (5 to 1440)","maximum":1440,"minimum":5,"type":"integer"},"labelName":{"description":"Label (folder) fetched mail files into; null clears it back to INBOX","maxLength":255,"minLength":1,"type":["string","null"]},"markRead":{"description":"Whether every imported message lands read; false = the backlog heuristic (older than the source → read, newer → unread)","type":"boolean"},"mode":{"description":"sync = keep collecting; import = complete once the remote mailbox is drained and quiet for quietDays, then switch off and forget the password","enum":["sync","import"],"type":"string"},"name":{"description":"Optional display name for this pickup source","maxLength":128,"type":["string","null"]},"password":{"description":"POP3 account login password","maxLength":1024,"minLength":1,"type":"string"},"port":{"description":"POP3 server port number","maximum":65535,"minimum":1,"type":"integer"},"quietDays":{"description":"Days without a newly stored message, after a drained run, that complete an import (default 7)","maximum":90,"minimum":1,"type":"integer"},"tls":{"description":"TLS encryption mode ('tls' or 'starttls')","enum":["tls","starttls"],"type":"string"},"username":{"description":"POP3 account login username","maxLength":320,"minLength":1,"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PickupSource"}}},"description":"Updated pickup source details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed; source_is_self when the resulting host+username would open the very mailbox this source delivers into; or password_required when re-enabling a completed import without a password"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Not found or not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"conflict: destination configuration changed or a handoff is pending; retry"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"pickup_not_configured — a password change needs PICKUP_KEK, which this deployment has not set. temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update a POP3 pickup source","tags":["Pickups"],"x-max-json-body-bytes":1048576},"delete":{"description":"Deletes a POP3 pickup source configuration and stops its background polling schedule.","operationId":"delete_PickupDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Pickup source identifier","in":"path","name":"pickupId","required":true,"schema":{"description":"Pickup source identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Pickup source deleted successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Not found or not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"conflict: destination configuration changed or a handoff is pending; retry"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete a POP3 pickup source","tags":["Pickups"]}},"/api/v1/mailboxes/{mailboxId}/pickups/{pickupId}/run":{"post":{"description":"Manually triggers an immediate POP3 mail fetch out of band without changing the regular schedule.","operationId":"post_PickupRun","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Pickup source identifier","in":"path","name":"pickupId","required":true,"schema":{"description":"Pickup source identifier","type":"string"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PickupRunResult"}}},"description":"Pickup run queued successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"source_is_self — this source would fetch from the mailbox it delivers into, so the scheduler will not dispatch it"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Not found or not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"disabled — pickup source must be enabled before running"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"run_cooldown — the source was dispatched (by schedule or by hand) less than a minute ago; `retryAfter` and the Retry-After header say how many seconds to wait. A run already in flight absorbs the trigger, so this bounds the run AFTER the run","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Trigger immediate POP3 pickup","tags":["Pickups"]}},"/api/v1/mailboxes/{mailboxId}/messages":{"get":{"description":"Lists messages newest-first (or oldest-first with order=asc) with cursor pagination, optionally filtered to one label. sortBy=date orders by the Date header instead of arrival time. Set state=expunged to list trash/restorable messages. For UID-ordered listing use GET /mailboxes/:id/labels/:label/messages.","operationId":"get_MessageList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Only messages carrying this label (folder)","in":"query","name":"label","required":false,"schema":{"description":"Only messages carrying this label (folder)","type":"string"}},{"description":"System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.","in":"query","name":"excludeRoles","required":false,"schema":{"description":"System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.","items":{"enum":["inbox","sent","drafts","trash","archive","junk"],"type":"string"},"type":"array"}},{"description":"Opaque page cursor from a previous response using the same sortBy. Arrival cursors must be canonical uppercase ULIDs; the cursor message need not still exist.","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response using the same sortBy. Arrival cursors must be canonical uppercase ULIDs; the cursor message need not still exist.","type":"string"}},{"description":"Page size (max 200)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (max 200)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Comma-separated flag names; a message matches only if ALL are set (e.g. flagged)","in":"query","name":"hasFlags","required":false,"schema":{"description":"Comma-separated flag names; a message matches only if ALL are set (e.g. flagged)","type":"string"}},{"description":"Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)","in":"query","name":"notFlags","required":false,"schema":{"description":"Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)","type":"string"}},{"description":"Listing direction: desc (default) = newest first, asc = oldest first. Hold it constant across a cursor crawl — cursors do not encode direction, so switching mid-crawl re-windows the page rather than erroring","in":"query","name":"order","required":false,"schema":{"description":"Listing direction: desc (default) = newest first, asc = oldest first. Hold it constant across a cursor crawl — cursors do not encode direction, so switching mid-crawl re-windows the page rather than erroring","enum":["asc","desc"],"type":"string"}},{"description":"Sort key: arrival (default) = the order mail reached this mailbox (message id); date = the Date header, falling back to arrival where it is absent or unparseable (RFC 5256 SORT DATE). Cursors follow the key, so hold it constant across a crawl — unlike order, a mismatched cursor is refused with 400 invalid_cursor rather than silently re-windowing. Note that under arrival an imported message (APPEND with ?internaldate=) lists where it was imported, not at its receivedAt; date orders imported mail by its own header","in":"query","name":"sortBy","required":false,"schema":{"description":"Sort key: arrival (default) = the order mail reached this mailbox (message id); date = the Date header, falling back to arrival where it is absent or unparseable (RFC 5256 SORT DATE). Cursors follow the key, so hold it constant across a crawl — unlike order, a mismatched cursor is refused with 400 invalid_cursor rather than silently re-windowing. Note that under arrival an imported message (APPEND with ?internaldate=) lists where it was imported, not at its receivedAt; date orders imported mail by its own header","enum":["arrival","date"],"type":"string"}},{"description":"live (default): ordinary listing, including messages on the Trash LABEL. expunged: the Recently-deleted TIER — a different place, whose rows have no labels at all and are purged after purgeAfter — carrying expungedAt/purgeAfter, the labels held at expunge, and restoresTo","in":"query","name":"state","required":false,"schema":{"description":"live (default): ordinary listing, including messages on the Trash LABEL. expunged: the Recently-deleted TIER — a different place, whose rows have no labels at all and are purged after purgeAfter — carrying expungedAt/purgeAfter, the labels held at expunge, and restoresTo","enum":["live","expunged"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"messages":[{"auth":null,"bcc":null,"blobGen":"g1","blobHash":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","cc":[],"deliveryMeta":null,"deliveryState":null,"envelopeFrom":"ada@example.com","envelopeTo":"grace@acme.example","flags":["seen"],"from":[{"email":"ada@example.com","name":"Ada Lovelace"}],"hasAttachment":true,"id":"01J9MSGA8C2E5H1K4M00000000","inReplyTo":null,"keywords":[],"labels":[{"deleted":false,"modseq":91842,"name":"INBOX","uid":4213,"uidValidity":1722470400}],"messageIdHeader":"<7f2a1c9e4b8d@mail.example.com>","receivedAt":1788081300,"referencesIds":[],"sentAt":1788081272,"size":48213,"snippet":"Hi Grace, attached is the Q3 report draft we discussed on Friday…","subject":"Q3 report draft","threadId":"01J9THRD5E8G1J4M7P00000000","to":[{"email":"grace@acme.example","name":null}]}],"nextCursor":"MTc4ODA4MTMwMC4wMUo5TVNHQThDMkU1SDFLNE0"},"schema":{"anyOf":[{"properties":{"messages":{"items":{"$ref":"#/components/schemas/MessageMeta"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["messages"],"type":"object"},{"properties":{"messages":{"items":{"$ref":"#/components/schemas/ExpungedMessageMeta"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"}},"required":["messages"],"type":"object"}]}}},"description":"Messages page (live rows, or trash rows when state=expunged)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, label_not_applicable (label filter with state=expunged), or invalid_cursor (a malformed cursor or one from a different sortBy)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal, or unknown_label (the label filter names no existing label)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List mailbox messages","tags":["Messages"]},"patch":{"description":"Applies flag, label, and keyword updates across multiple messages in a single atomic operation. Name the targets by `ids`, by `threadIds`, or both: `threadIds` is expanded to the conversation's members server-side, in the same transaction as the write, so a reply that arrives while the request is in flight is either wholly in the gesture or wholly outside it. That is the difference from expanding it client-side, which also truncates at whatever page of members the client happened to hold. Expansion is the set GET /threads/{threadId} returns: live members in your grant, Trash and Junk excluded. `ids` may name a trashed, junked or otherwise excluded message directly — the operand chooses targets, it does not restrict them.","operationId":"patch_MessageBatchUpdate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"flagLabel":{"description":"The label (IMAP mailbox) the client had selected. When present, `deleted` in `flagsSet`/`flagsClear` marks the message's membership in THAT label only, leaves the message-wide bit untouched, and every other flag in the same patch keeps its message-wide meaning. Label-scoped listings (`/labels/{label}/uids`, `/labels/{label}/messages`, the label-filtered search) report this per-membership bit, `deletedCount` counts it, and `POST /labels/{label}/expunge` detaches exactly the memberships carrying it. A label the message is not filed in answers not_in_label with nothing written. Requires `deleted` in one of the two flag lists (validation_failed otherwise). Without `flagLabel`, `deleted` means every folder: the message-wide bit (JMAP's visibility rule; JMAP has no `\\Deleted`) and every membership move together. A scoped clear that unmarks the last marked membership clears the message-wide bit as well.","minLength":1,"type":"string"},"flagsClear":{"description":"Flags to remove","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"flagsSet":{"description":"Flags to set","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"ids":{"description":"Array of message IDs to update","items":{"type":"string"},"maxItems":200,"minItems":1,"type":"array"},"ifInLabel":{"additionalProperties":false,"description":"Apply each explicit ID only while it has the given UID in this label and UIDVALIDITY epoch. Checked atomically with the write; the identity condition alone permits intervening flag changes. Missing UID entries, absent or replaced memberships, and inaccessible labels answer not_in_label per entry, with nothing written. Cannot be combined with threadIds.","properties":{"label":{"minLength":1,"type":"string"},"uidValidity":{"maximum":4294967295,"minimum":1,"type":"integer"},"uids":{"additionalProperties":{"maximum":4294967295,"minimum":1,"type":"integer"},"type":"object"},"unchangedSince":{"additionalProperties":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"description":"Optional per-ID modseq ceilings in this label (at most 200 entries). A newer membership answers modified with its currentModseq; a missing entry answers not_in_label. Zero refuses every existing membership. Checked in addition to the top-level unchangedSince, if supplied.","type":"object"}},"required":["label","uidValidity","uids"],"type":"object"},"keywordsClear":{"description":"Custom keywords to remove","items":{"type":"string"},"type":"array"},"keywordsExact":{"description":"Exact replacement list of custom keywords","items":{"type":"string"},"type":"array"},"keywordsSet":{"description":"Custom keywords to add","items":{"type":"string"},"type":"array"},"label":{"description":"Label context for unchangedSince check","minLength":1,"type":"string"},"labelsAdd":{"description":"Labels to add","items":{"type":"string"},"type":"array"},"labelsExact":{"description":"Exact replacement list of labels","items":{"type":"string"},"type":"array"},"labelsRemove":{"description":"Labels to remove","items":{"type":"string"},"type":"array"},"orphans":{"description":"What to do if this write would leave the message with no label. 'expunge' (the default) sends the message to Recently deleted. 'archive' keeps the message live by attaching the Archive system label (attaching Archive needs no right beyond the grant's 't' for a scoped viewer). If the write removes Archive itself and would leave no labels, Archive is kept without error. A SCOPED viewer whose write lands the message in Archive has moved it out of their own scope: the answer is still `updated`, and the hydrated message carries an EMPTY `labels` list rather than naming a label the grant never included. `labelsAdded` omits Archive for the same reason.","enum":["expunge","archive"],"type":"string"},"threadExcludeRoles":{"description":"Roles to exclude from thread expansion (e.g. ['sent', 'drafts']). Members carrying any label with one of these roles are omitted from the expanded conversation. Trash and Junk members are already left out by the default expansion, so naming them here changes nothing unless `threadLabel` is that folder, where it empties the set. Explicit `ids` are unaffected. If every member is excluded, the conversation contributes nothing, which is not an error.","items":{"enum":["inbox","sent","drafts","trash","archive","junk"],"type":"string"},"type":"array"},"threadIds":{"description":"Conversation IDs whose members to update, expanded server-side. A stale ID from before a thread merge resolves transparently, as on GET /threads/{threadId}. Refused with thread_too_large past 1000 expanded messages, rather than acting on some of them.","items":{"type":"string"},"maxItems":50,"minItems":1,"type":"array"},"threadLabel":{"description":"The folder each conversation in `threadIds` was being viewed in — the same value passed to GET /threads/{threadId}?label=, so the patch reaches exactly the members that view rendered. Omitted, the expansion is the default view: live members in your grant with Trash and Junk excluded. Pass the Trash folder to patch a conversation's trashed members instead, or the Junk folder for its junked ones; the default deliberately leaves both alone. Optional here and REQUIRED on DELETE /messages, where guessing wrong destroys a member the user was not looking at rather than re-filing one they can see.","minLength":1,"type":"string"},"threadLabelOnly":{"description":"Narrow each conversation in `threadIds` to the members FILED UNDER `threadLabel`, which is then REQUIRED (thread_context_required without it). `threadLabel` alone is a view, not a filter: a conversation viewed in the Inbox includes the Sent copy of your replies and any member filed elsewhere, so a label patch over it re-files those too. Pass this for FILING gestures (archive, move, junk, delete-to-Trash) so they act on what the folder listing showed; leave it off for flags and keywords, which mean the whole conversation. `ids` are unaffected.","type":"boolean"},"unchangedSince":{"description":"Conditional update precondition: update only if modseq <= unchangedSince","minimum":0,"type":"integer"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchUpdateResult"}}},"description":"Batch update results per message. An entry answers not_in_label when flagLabel names a label that message is not filed in, or ifInLabel does not match its current accessible membership (nothing written for it)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed (including flagLabel without `deleted` in either flag list, malformed ifInLabel, or ifInLabel with threadIds), invalid label/keyword, target_required (neither ids nor threadIds given), thread_context_required (threadLabelOnly without threadLabel), or thread_too_large"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update flags and labels for multiple messages or whole conversations","tags":["Messages"],"x-max-json-body-bytes":1048576},"post":{"description":"Stores raw RFC 5322 email bytes directly into a mailbox under a label without sending (similar to IMAP APPEND). Supports custom flags, Sieve filtering, and historical internaldate. Lone CR and LF are normalized to CRLF before storage; the size limit applies to the normalized message.","operationId":"post_MessageAppend","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Target label or folder (default INBOX)","in":"query","name":"label","required":false,"schema":{"description":"Target label or folder (default INBOX)","type":"string"}},{"description":"Comma-separated initial flags, e.g. seen,draft","in":"query","name":"flags","required":false,"schema":{"description":"Comma-separated initial flags, e.g. seen,draft","type":"string"}},{"description":"Comma-separated initial keywords (e.g. $forwarded,$mdnsent), committed WITH the store flip — an IMAP APPEND with keywords is one call rather than a POST followed by a PATCH. Flag-shaped keywords ($seen, $answered, $flagged, $draft) fold onto their flag bit.","in":"query","name":"keywords","required":false,"schema":{"description":"Comma-separated initial keywords (e.g. $forwarded,$mdnsent), committed WITH the store flip — an IMAP APPEND with keywords is one call rather than a POST followed by a PATCH. Flag-shaped keywords ($seen, $answered, $flagged, $draft) fold onto their flag bit.","maxLength":2048,"type":"string"}},{"description":"Whether to run the mailbox's active Sieve filter on this append (default false)","in":"query","name":"filter","required":false,"schema":{"description":"Whether to run the mailbox's active Sieve filter on this append (default false)","enum":["true","false"],"type":"string"}},{"description":"Original receive timestamp in epoch seconds for migration/import (default now)","in":"query","name":"internaldate","required":false,"schema":{"description":"Original receive timestamp in epoch seconds for migration/import (default now)","maximum":253402300799,"minimum":-62135596800,"type":["integer","null"]}},{"description":"Envelope sender email address","in":"header","name":"x-envelope-from","required":false,"schema":{"description":"Envelope sender email address","type":"string"}},{"description":"Envelope recipient email address","in":"header","name":"x-envelope-to","required":false,"schema":{"description":"Envelope recipient email address","type":"string"}},{"description":"Optional client idempotency key to prevent duplicate imports. Stored NAMESPACED as `append:<your id>` (an append is the mailbox's own side writing its own row, announced as `message.imported`, not `message.new`), so the traffic log and the filtered response show that form — retry with your original value.","in":"header","name":"x-delivery-id","required":false,"schema":{"description":"Optional client idempotency key to prevent duplicate imports. Stored NAMESPACED as `append:<your id>` (an append is the mailbox's own side writing its own row, announced as `message.imported`, not `message.new`), so the traffic log and the filtered response show that form — retry with your original value.","type":"string"}},{"description":"Message payload size in bytes (required)","in":"header","name":"content-length","required":false,"schema":{"description":"Message payload size in bytes (required)","type":"string"}}],"requestBody":{"content":{"message/rfc822":{"schema":{"description":"Raw RFC 5322 message bytes","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendResult"}}},"description":"Message appended successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_header, or message exceeds size limit"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"receiving_disabled (policyScope \"mailbox\"): this mailbox's receive hold is `disabled`, and the caller reaches it through a share grant. A grantee's write is refused as arriving mail is; the mailbox's own user and its account write as ever."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Length Required — Content-Length header is required"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"receiving_paused (policyScope \"mailbox\", with Retry-After): this mailbox's receive hold is `paused`, and the caller reaches it through a share grant. Retry once the owner clears it.","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"superseded/reaped (lost pending intent; retry with the same X-Delivery-Id), or temporary_failure (this mailbox's receive policy could not be established for a grantee's write; retry)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"over_quota (mailbox storage limit), account_over_quota (the account storage pool), or store_metadata_full (the store's own metadata ceiling — no limit to raise; purging messages is the remedy) — distinct so the client knows which remedy applies"}},"summary":"Append raw MIME message to mailbox","tags":["Messages"]},"delete":{"description":"Permanently purges every row on the Recently-deleted tier with state=expunged, or deletes the messages named by `ids` and/or the conversations named by `threadIds`. These are the only two gestures in the API that cannot be undone by moving mail back (`purge=true` destroys; without it the rows drop to the Recently-deleted tier and age out), so a conversation named here MUST also carry `threadLabel`, the folder it was being viewed in. Omitting it is `thread_context_required`, never a default: a conversation routinely has one member in Trash and another still in the Inbox, and a Trash-view delete that expanded to the default set would take the Inbox copy with it. `threadIds` names LIVE conversations only — the Recently-deleted tier has no conversation view, so purging rows there is an `ids` gesture.","operationId":"delete_MessageEmptyTrash","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Set to 'expunged' to permanently purge all trash messages","in":"query","name":"state","required":false,"schema":{"description":"Set to 'expunged' to permanently purge all trash messages","enum":["expunged"],"type":"string"}},{"description":"When deleting by IDs, set to 'true' to permanently purge instead of expunging to trash","in":"query","name":"purge","required":false,"schema":{"description":"When deleting by IDs, set to 'true' to permanently purge instead of expunging to trash","enum":["true","false"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"ids":{"description":"Array of message IDs to delete","items":{"type":"string"},"maxItems":200,"minItems":1,"type":"array"},"threadExcludeRoles":{"description":"Roles to exclude from thread expansion (e.g. ['sent', 'drafts']). Members carrying any label with one of these roles are omitted from the expanded conversation. Trash and Junk members are already left out by the default expansion, so naming them here changes nothing unless `threadLabel` is that folder, where it empties the set. Explicit `ids` are unaffected. If every member is excluded, the conversation contributes nothing, which is not an error.","items":{"enum":["inbox","sent","drafts","trash","archive","junk"],"type":"string"},"type":"array"},"threadIds":{"description":"Conversation IDs to delete, expanded server-side to the members visible in `threadLabel` — which is REQUIRED alongside this. Refused with thread_too_large past 1000 expanded messages rather than deleting part of a conversation.","items":{"type":"string"},"maxItems":50,"minItems":1,"type":"array"},"threadLabel":{"description":"The folder each conversation in `threadIds` was being viewed in — the same value passed to GET /threads/{threadId}?label=, so the delete reaches exactly the members that view rendered. Inside Trash that is the trashed members, inside Junk the junked ones; anywhere else it is the live members carrying neither label. Required with `threadIds`, and validated: an unknown folder is unknown_label, not a fall back to the default set.","minLength":1,"type":"string"},"threadLabelOnly":{"description":"Narrow each conversation to the members FILED UNDER `threadLabel`, as on PATCH /messages. Without it a delete made in the Inbox also takes the Sent copy of your replies and any member filed elsewhere — they are all part of the conversation that view renders. Inside Trash it changes nothing: the trashed members are already exactly that set.","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EmptyTrashResult"},{"$ref":"#/components/schemas/BatchDeleteResult"}]}}},"description":"Purge count or batch deletion results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, delete_target_required, delete_target_exclusive, thread_context_required, unknown_label, or thread_too_large"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Empty trash, or delete a batch of messages or whole conversations","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/messages/{messageId}":{"get":{"description":"Returns metadata for a specific message including subject, sender/recipients, labels, flags, UIDs, and timestamps.","operationId":"get_MessageGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message ULID identifier","in":"path","name":"messageId","required":true,"schema":{"description":"Message ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"auth":null,"bcc":null,"blobGen":"g1","blobHash":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","cc":[],"deliveryMeta":null,"deliveryState":null,"envelopeFrom":"ada@example.com","envelopeTo":"grace@acme.example","flags":["seen"],"from":[{"email":"ada@example.com","name":"Ada Lovelace"}],"hasAttachment":true,"id":"01J9MSGA8C2E5H1K4M00000000","inReplyTo":null,"keywords":[],"labels":[{"deleted":false,"modseq":91842,"name":"INBOX","uid":4213,"uidValidity":1722470400}],"messageIdHeader":"<7f2a1c9e4b8d@mail.example.com>","receivedAt":1788081300,"referencesIds":[],"sentAt":1788081272,"size":48213,"snippet":"Hi Grace, attached is the Q3 report draft we discussed on Friday…","subject":"Q3 report draft","threadId":"01J9THRD5E8G1J4M7P00000000","to":[{"email":"grace@acme.example","name":null}]},"schema":{"$ref":"#/components/schemas/MessageMeta"}}},"description":"Message metadata"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or message not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get message metadata","tags":["Messages"]},"patch":{"description":"Updates message flags, adds or removes labels, and modifies custom keywords. Removing a message's LAST label expunges it to the Recently-deleted tier (restorable until purgeAfter) — it does not attach the Trash label. A label write that leaves the message carrying only Trash is a delete: its previous filing is recorded as restoresTo, and POST /messages/untrash reverses it. One that leaves it carrying only Junk is a spam report, recorded the same way and reversed by POST /messages/unjunk.","operationId":"patch_MessageUpdate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message ULID identifier","in":"path","name":"messageId","required":true,"schema":{"description":"Message ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"mark read":{"value":{"flagsSet":["seen"]}},"move to Archive":{"value":{"labelsAdd":["Archive"],"labelsRemove":["INBOX"]}},"trash (labelsExact leaving only Trash)":{"value":{"labelsExact":["Trash"]}}},"schema":{"additionalProperties":false,"properties":{"flagLabel":{"description":"The label (IMAP mailbox) the client had selected. When present, `deleted` in `flagsSet`/`flagsClear` marks the message's membership in THAT label only, leaves the message-wide bit untouched, and every other flag in the same patch keeps its message-wide meaning. Label-scoped listings (`/labels/{label}/uids`, `/labels/{label}/messages`, the label-filtered search) report this per-membership bit, `deletedCount` counts it, and `POST /labels/{label}/expunge` detaches exactly the memberships carrying it. A label the message is not filed in answers not_in_label with nothing written. Requires `deleted` in one of the two flag lists (validation_failed otherwise). Without `flagLabel`, `deleted` means every folder: the message-wide bit (JMAP's visibility rule; JMAP has no `\\Deleted`) and every membership move together. A scoped clear that unmarks the last marked membership clears the message-wide bit as well.","minLength":1,"type":"string"},"flagsClear":{"description":"Flags to remove","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"flagsSet":{"description":"Flags to set","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"keywordsClear":{"description":"Custom keywords to remove","items":{"type":"string"},"type":"array"},"keywordsExact":{"description":"Exact replacement list of custom keywords","items":{"type":"string"},"type":"array"},"keywordsSet":{"description":"Custom keywords to add","items":{"type":"string"},"type":"array"},"labelsAdd":{"description":"Labels to add","items":{"type":"string"},"type":"array"},"labelsExact":{"description":"Exact replacement list of labels","items":{"type":"string"},"type":"array"},"labelsRemove":{"description":"Labels to remove","items":{"type":"string"},"type":"array"},"mime":{},"orphans":{"description":"What to do if this write would leave the message with no label. 'expunge' (the default) sends the message to Recently deleted. 'archive' keeps the message live by attaching the Archive system label (attaching Archive needs no right beyond the grant's 't' for a scoped viewer). If the write removes Archive itself and would leave no labels, Archive is kept without error. A SCOPED viewer whose write lands the message in Archive has moved it out of their own scope: the answer is still `updated`, and the hydrated message carries an EMPTY `labels` list rather than naming a label the grant never included. `labelsAdded` omits Archive for the same reason.","enum":["expunge","archive"],"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"auth":null,"bcc":null,"blobGen":"g1","blobHash":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","cc":[],"deliveryMeta":null,"deliveryState":null,"envelopeFrom":"ada@example.com","envelopeTo":"grace@acme.example","flags":["seen","flagged"],"from":[{"email":"ada@example.com","name":"Ada Lovelace"}],"hasAttachment":true,"id":"01J9MSGA8C2E5H1K4M00000000","inReplyTo":null,"keywords":[],"labels":[{"deleted":false,"modseq":91842,"name":"INBOX","uid":4213,"uidValidity":1722470400}],"messageIdHeader":"<7f2a1c9e4b8d@mail.example.com>","receivedAt":1788081300,"referencesIds":[],"sentAt":1788081272,"size":48213,"snippet":"Hi Grace, attached is the Q3 report draft we discussed on Friday…","subject":"Q3 report draft","threadId":"01J9THRD5E8G1J4M7P00000000","to":[{"email":"grace@acme.example","name":null}]},"schema":{"$ref":"#/components/schemas/MessageUpdateResult"}}},"description":"Updated message metadata"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed (including flagLabel without `deleted` in either flag list) or invalid label/keyword name"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or message not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_in_label — flagLabel names a label the message is not filed in; nothing written"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update message flags and labels","tags":["Messages"],"x-max-json-body-bytes":1048576},"delete":{"description":"Soft-deletes a message to trash or permanently purges it. Use label to detach from a single label.","operationId":"delete_MessageDelete","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message ULID identifier","in":"path","name":"messageId","required":true,"schema":{"description":"Message ULID identifier","type":"string"}},{"description":"Remove message from this specific label only","in":"query","name":"label","required":false,"schema":{"description":"Remove message from this specific label only","type":"string"}},{"description":"Set to 'true' to permanently delete message immediately instead of moving to trash","in":"query","name":"purge","required":false,"schema":{"description":"Set to 'true' to permanently delete message immediately instead of moving to trash","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDeleteResult"}}},"description":"Message deletion result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed or label_purge_exclusive"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox, message, or label not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_labeled — message does not have the specified label"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete a message","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/messages/{messageId}/content":{"get":{"description":"Returns decoded email headers, inline plain text and HTML bodies, and attachment metadata for a message.","operationId":"get_MessageGetContent","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message ULID identifier","in":"path","name":"messageId","required":true,"schema":{"description":"Message ULID identifier","type":"string"}},{"description":"Revalidation ETag from a previous response; on match the answer is 304","in":"header","name":"if-none-match","required":false,"schema":{"description":"Revalidation ETag from a previous response; on match the answer is 304","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"attachments":[{"contentId":null,"contentType":"application/pdf","filename":"q3-report-draft.pdf","inline":false,"section":"3","size":44032}],"headers":{"cc":[],"date":1788081272,"from":[{"email":"ada@example.com","name":"Ada Lovelace"}],"inReplyTo":null,"messageIdHeader":"<7f2a1c9e4b8d@mail.example.com>","replyTo":[],"subject":"Q3 report draft","to":[{"email":"grace@acme.example","name":null}]},"html":{"charset":"utf-8","content":"<div>Hi Grace,<br><br>attached is the Q3 report draft we discussed on Friday.<br><br>Ada</div>","section":"2","size":95,"truncated":false},"text":{"charset":"utf-8","content":"Hi Grace,\n\nattached is the Q3 report draft we discussed on Friday.\n\nAda","section":"1","size":74,"truncated":false}},"schema":{"$ref":"#/components/schemas/ContentResult"}}},"description":"Parsed message body, headers, and attachments","headers":{"ETag":{"description":"Content hash for revalidation; send it back as If-None-Match","schema":{"type":"string"}}}},"304":{"description":"Not modified — If-None-Match matched content ETag"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or message not found"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"message_too_large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unparseable_message or message_too_complex"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"blob_missing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get parsed message content and attachments","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/messages/{messageId}/raw":{"get":{"description":"Streams the full raw RFC 5322 MIME message bytes directly from storage. Works for active messages and trash messages.","operationId":"get_MessageGetRaw","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message ULID identifier","in":"path","name":"messageId","required":true,"schema":{"description":"Message ULID identifier","type":"string"}},{"description":"Revalidation ETag from previous response","in":"header","name":"if-none-match","required":false,"schema":{"description":"Revalidation ETag from previous response","type":"string"}}],"responses":{"200":{"content":{"message/rfc822":{"schema":{"description":"Raw message bytes","type":"string"}}},"description":"Raw RFC 5322 message stream","headers":{"ETag":{"description":"The stored blob's ETag; send it back as If-None-Match","schema":{"type":"string"}}}},"304":{"description":"Not modified — If-None-Match matched the stored blob's ETag"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or message not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"blob_missing — metadata exists but message storage blob read failed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get raw MIME message body","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/messages/{messageId}/parts/{section}":{"get":{"description":"Streams a single decoded MIME part or raw encoded slice from message storage by section number.","operationId":"get_MessageGetPart","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message ULID identifier","in":"path","name":"messageId","required":true,"schema":{"description":"Message ULID identifier","type":"string"}},{"description":"IMAP section number (e.g. 1, 2, 3.1) from /content attachments[].section","in":"path","name":"section","required":true,"schema":{"description":"IMAP section number (e.g. 1, 2, 3.1) from /content attachments[].section","type":"string"}},{"description":"Set to 'true' to return raw undecoded transfer bytes instead of decoded content","in":"query","name":"raw","required":false,"schema":{"description":"Set to 'true' to return raw undecoded transfer bytes instead of decoded content","enum":["true","false"],"type":"string"}},{"description":"Revalidation ETag from a previous response; on match the answer is 304","in":"header","name":"if-none-match","required":false,"schema":{"description":"Revalidation ETag from a previous response; on match the answer is 304","type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"description":"Part bytes streamed from storage","type":"string"}}},"description":"MIME part content bytes","headers":{"ETag":{"description":"Content hash for revalidation; send it back as If-None-Match","schema":{"type":"string"}}}},"304":{"description":"Not modified — If-None-Match matched part ETag"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox, message, or MIME section not found"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"message_too_large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unparseable_message or message_too_complex"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"blob_missing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get specific message MIME part","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/messages/batch":{"post":{"description":"Retrieves metadata summaries for up to 200 messages in a single request.","operationId":"post_MessageBatchGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ids":{"description":"Array of message IDs to retrieve","items":{"type":"string"},"maxItems":200,"minItems":1,"type":"array"}},"required":["ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageBatch"}}},"description":"Dictionary of message metadata objects keyed by message ID"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Batch get message metadata","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/messages/heads":{"post":{"description":"Returns each message's raw header block (base64, byte-exact, separator line included) from one bounded head read per message — the projection an IMAP folder sync fetches, without downloading whole messages. A header block longer than 64 KB is reported truncated rather than served partially.","operationId":"post_MessageHeadBatch","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ids":{"description":"Array of message IDs (ULIDs)","items":{"maxLength":64,"minLength":1,"type":"string"},"maxItems":200,"minItems":1,"type":"array"}},"required":["ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeadBatch"}}},"description":"Map of message ID to header block"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Batch get raw header blocks","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/messages/mime":{"post":{"description":"Returns cached MIME envelope and body structure metadata for multiple messages without downloading raw blobs.","operationId":"post_MessageMimeBatch","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ids":{"description":"Array of message IDs","items":{"type":"string"},"maxItems":200,"minItems":1,"type":"array"}},"required":["ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MimeBatch"}}},"description":"Map of message ID to parsed MIME envelope and body structures"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Batch get cached MIME structures","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/keywords":{"get":{"description":"Every distinct keyword on this mailbox's LIVE messages, most-used first then alphabetical, with how many messages carry each.\n\nExpunged messages are excluded: they keep their keywords so a restore can put them back, but they are not mail the user has. Protocol keywords are NOT filtered out — `$forwarded`, `$junk` and the rest are returned like any other, because which of them are worth showing is a client's decision, not core's.\n\nScoped like every other read: a folder-scoped grant reports the keywords inside the grant and no others.","operationId":"get_MailboxKeywordList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Maximum distinct keywords to return (default 100, max 500). The cut falls on the least-used, since the order is by count.","in":"query","name":"limit","required":false,"schema":{"description":"Maximum distinct keywords to return (default 100, max 500). The cut falls on the least-used, since the order is by count.","maximum":500,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordListPage"}}},"description":"Keywords in use"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List the keywords in use, with counts","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/search":{"get":{"description":"Searches email messages across subject, sender/recipient addresses, and body text using BM25 relevance ranking. Optionally filter by label, flags, or group matches by thread.","operationId":"get_MailboxSearch","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Search keywords or phrases","in":"query","name":"q","required":true,"schema":{"description":"Search keywords or phrases","maxLength":512,"type":"string"}},{"description":"Restrict search to a specific label or folder","in":"query","name":"label","required":false,"schema":{"description":"Restrict search to a specific label or folder","type":"string"}},{"description":"System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.","in":"query","name":"excludeRoles","required":false,"schema":{"description":"System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.","items":{"enum":["inbox","sent","drafts","trash","archive","junk"],"type":"string"},"type":"array"}},{"description":"Comma-separated flag names; a message matches only if ALL are set (e.g. flagged)","in":"query","name":"hasFlags","required":false,"schema":{"description":"Comma-separated flag names; a message matches only if ALL are set (e.g. flagged)","type":"string"}},{"description":"Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)","in":"query","name":"notFlags","required":false,"schema":{"description":"Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)","type":"string"}},{"description":"Maximum messages to return (default 25, max 100 — or 2000 with `fields=ids`)","in":"query","name":"limit","required":false,"schema":{"description":"Maximum messages to return (default 25, max 100 — or 2000 with `fields=ids`)","maximum":2000,"minimum":1,"type":"integer"}},{"description":"Pagination cursor for next page of results","in":"query","name":"cursor","required":false,"schema":{"description":"Pagination cursor for next page of results","type":"string"}},{"description":"`ids`: answer the matching message IDS only, in rank order, under `ids` — no metadata rows, page cap 2000. What a client that needs a UID set (IMAP SEARCH) asks for: one call for what used to be twenty pages of full rows. Not combinable with `group` or `snippet`.","in":"query","name":"fields","required":false,"schema":{"description":"`ids`: answer the matching message IDS only, in rank order, under `ids` — no metadata rows, page cap 2000. What a client that needs a UID set (IMAP SEARCH) asks for: one call for what used to be twenty pages of full rows. Not combinable with `group` or `snippet`.","enum":["ids"],"type":"string"}},{"description":"Collapse matches to one top-ranked message per conversation thread","in":"query","name":"group","required":false,"schema":{"description":"Collapse matches to one top-ranked message per conversation thread","enum":["thread"],"type":"string"}},{"description":"Whether to include highlighted search text snippets in results","in":"query","name":"snippet","required":false,"schema":{"description":"Whether to include highlighted search text snippets in results","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"results":[{"auth":null,"bcc":null,"blobGen":"g1","blobHash":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","cc":[],"deliveryMeta":null,"deliveryState":null,"envelopeFrom":"ada@example.com","envelopeTo":"grace@acme.example","flags":["seen"],"from":[{"email":"ada@example.com","name":"Ada Lovelace"}],"hasAttachment":true,"id":"01J9MSGA8C2E5H1K4M00000000","inReplyTo":null,"keywords":[],"labels":[{"deleted":false,"modseq":91842,"name":"INBOX","uid":4213,"uidValidity":1722470400}],"messageIdHeader":"<7f2a1c9e4b8d@mail.example.com>","receivedAt":1788081300,"referencesIds":[],"sentAt":1788081272,"size":48213,"snippet":"Hi Grace, attached is the Q3 report draft we discussed on Friday…","subject":"Q3 report draft","threadId":"01J9THRD5E8G1J4M7P00000000","to":[{"email":"grace@acme.example","name":null}]}],"snippets":[{"id":"01J9MSGA8C2E5H1K4M00000000","preview":"attached is the <mark>Q3 report</mark> draft we discussed…","subject":"<mark>Q3 report</mark> draft"}],"truncated":false},"schema":{"properties":{"ids":{"description":"With `fields=ids`: the matching message IDs in rank order (`results` is then empty)","items":{"type":"string"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"},"results":{"items":{"$ref":"#/components/schemas/MessageMeta"},"type":"array"},"scanWindow":{"description":"The ranking window's size: the results were drawn from the newest this-many matching messages. Present only beside `truncated`, so a client can say \"more than N matches\" with the N the server applied.","type":"integer"},"snippets":{"description":"Highlighted search excerpts","items":{"$ref":"#/components/schemas/EmailSearchSnippet"},"type":"array"},"total":{"description":"Exact number of matching messages, under the same label and flag filters as the results. Absent when `truncated` (the ranking window clipped, so the count would describe the window rather than the match set) or when the page is past the end; absent also on grouped (`group=thread`) responses, whose conversation count is not known. Absent means unknown, never zero.","type":"integer"},"truncated":{"description":"True if query matched more messages than maximum ranking window","type":"boolean"}},"required":["results"],"type":"object"}}},"description":"Ranked search results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, empty_query, invalid_cursor, search_offset_too_deep, or grouped_search_unpaginated (grouped mode cannot be combined with cursor paging)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Full-text search a mailbox","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/search/query":{"post":{"description":"Executes a structured query over mailbox messages with complex filters (combinators, header conditions, date ranges, flag states) and custom sort orders.","operationId":"post_MailboxSearchQuery","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"boolean tree":{"value":{"calculateTotal":true,"filter":{"conditions":[{"after":"2026-08-01T00:00:00Z"},{"conditions":[{"from":"ada@example.com"},{"hasKeyword":"$flagged"}],"operator":"OR"}],"operator":"AND"},"limit":50}},"flat FilterCondition":{"value":{"filter":{"from":"ada@example.com","hasAttachment":true,"inMailbox":"L1"},"limit":25,"snippet":true,"sort":[{"isAscending":false,"property":"receivedAt"}]}}},"schema":{"$ref":"#/components/schemas/EmailSearchRequest"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"limit":25,"position":0,"results":[{"auth":null,"bcc":null,"blobGen":"g1","blobHash":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","cc":[],"deliveryMeta":null,"deliveryState":null,"envelopeFrom":"ada@example.com","envelopeTo":"grace@acme.example","flags":["seen"],"from":[{"email":"ada@example.com","name":"Ada Lovelace"}],"hasAttachment":true,"id":"01J9MSGA8C2E5H1K4M00000000","inReplyTo":null,"keywords":[],"labels":[{"deleted":false,"modseq":91842,"name":"INBOX","uid":4213,"uidValidity":1722470400}],"messageIdHeader":"<7f2a1c9e4b8d@mail.example.com>","receivedAt":1788081300,"referencesIds":[],"sentAt":1788081272,"size":48213,"snippet":"Hi Grace, attached is the Q3 report draft we discussed on Friday…","subject":"Q3 report draft","threadId":"01J9THRD5E8G1J4M7P00000000","to":[{"email":"grace@acme.example","name":null}]}],"snippets":[{"id":"01J9MSGA8C2E5H1K4M00000000","preview":"attached is the <mark>Q3 report</mark> draft we discussed…","subject":"<mark>Q3 report</mark> draft"}],"total":1},"schema":{"$ref":"#/components/schemas/EmailSearchResult"}}},"description":"Search results page with optional total count and snippets"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, unsupported_filter, unsupported_sort, or invalid_filter"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Structured filter and query messages","tags":["Messages"],"x-max-json-body-bytes":1048576},"patch":{"description":"Applies one patch to every message `POST /search/query` would return for the same `filter` — the way to act on a whole result set without naming its messages. The filter grammar, and the set it selects, are that route's own.\n\nSEND BACK THE `excludeRoles` YOU SEARCHED WITH. It narrows the selection here exactly as it narrows the results there, and it is not part of the filter — so a call that omits it patches the Trash and Junk mail the search left out.\n\nTHE CEILING. `idMax` is a message id (a ULID, so ordered by arrival) resolved on the first call and echoed back: mail that arrives while the gesture runs has a later id and is never touched. Send it back unchanged on every continuation.\n\nIT MAY ANSWER A CURSOR, exactly as `PATCH /labels/{label}/messages` does: the call spends a bounded budget, and a non-null `nextAfter` means call again with `after` set to it, the same `idMax`, the same filter and the same patch. Unlike that route it reports no `remaining` — measure progress against the search's own `total`.\n\nA FULL-TEXT filter is bounded: one that matches more than 5,000 messages is refused with `too_large`, having written nothing, rather than applied to some of them. Narrow the search. A filter is REQUIRED — this route will not patch a whole mailbox by omission.","operationId":"patch_MailboxSearchQueryUpdate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"after":{"description":"Continuation cursor: pass the previous call's `nextAfter`.","minLength":1,"type":"string"},"excludeRoles":{"description":"System label roles whose mail this query must not return — e.g. `[\"trash\", \"junk\"]` for an All-Mail view. A message carrying ANY label with one of these roles is excluded, whatever else it carries. Says in one argument what a filter would need a label lookup and one bound value per label to say; a role no label answers to is simply not excluded.","items":{"enum":["inbox","sent","drafts","trash","archive","junk"],"type":"string"},"type":"array"},"filter":{"$ref":"#/components/schemas/EmailSearchFilter"},"flagsClear":{"description":"Flags to remove","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"flagsSet":{"description":"Flags to set","items":{"enum":["seen","answered","flagged","draft","deleted"],"type":"string"},"type":"array"},"idMax":{"description":"ULID ceiling — the selection is every match with id <= this. Omitted on a FIRST call; REQUIRED once `after` is given.","minLength":1,"type":"string"},"keywordsClear":{"description":"Custom keywords to remove","items":{"type":"string"},"type":"array"},"keywordsExact":{"description":"Exact replacement list of custom keywords","items":{"type":"string"},"type":"array"},"keywordsSet":{"description":"Custom keywords to add","items":{"type":"string"},"type":"array"},"labelsAdd":{"description":"Labels to add","items":{"type":"string"},"type":"array"},"labelsExact":{"description":"Exact replacement list of labels","items":{"type":"string"},"type":"array"},"labelsRemove":{"description":"Labels to remove","items":{"type":"string"},"type":"array"},"limit":{"description":"Lower the per-call update budget. Never raises it.","minimum":1,"type":"integer"},"orphans":{"description":"What to do if this write would leave the message with no label. 'expunge' (the default) sends the message to Recently deleted. 'archive' keeps the message live by attaching the Archive system label (attaching Archive needs no right beyond the grant's 't' for a scoped viewer). If the write removes Archive itself and would leave no labels, Archive is kept without error. A SCOPED viewer whose write lands the message in Archive has moved it out of their own scope: the answer is still `updated`, and the hydrated message carries an EMPTY `labels` list rather than naming a label the grant never included. `labelsAdded` omits Archive for the same reason.","enum":["expunge","archive"],"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryMessagesUpdateResult"}}},"description":"Counts for this call, and a cursor if the selection is not drained"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, filter_required, patch_required, idmax_required (after without idMax), too_large (a full-text filter over the cap), unsupported_filter, invalid_filter, unknown_label (a name in the patch), or invalid_keyword"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update flags, labels and keywords for every message a search selects","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/search/snippets":{"post":{"description":"Builds the same highlighted <mark> excerpts (subject + body preview) the search surfaces return inline under `snippet`, for up to 50 result ids the caller already holds, so a client can paint a results page first and fill the highlights in afterwards. `filter` is the filter the results were found with (for the ranked GET, `{ text: q }`). Ids the caller cannot see are omitted.","operationId":"post_MailboxSearchSnippets","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSearchSnippetsRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSearchSnippetsResult"}}},"description":"One excerpt per visible id, in request order"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, unsupported_filter, or invalid_filter"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Highlighted excerpts for search results","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/search/semantic":{"get":{"description":"Finds the messages whose MEANING is closest to the query, ranked by similarity — 'the invoice from the Berlin supplier' finds it whether or not those words appear. Hybrid by default: the lexical BM25 ranking is fused in by reciprocal rank, which is what makes exact identifiers (invoice numbers, names) findable too. Requires the mailbox to have semantic search enabled (PATCH /identities/:id { semantic: true }). Bounded at the 100 most relevant candidates before filtering: this is 'the most relevant', never 'every match ranked' — deep paging is /search's job. Results are the same MessageMeta rows /search returns.","operationId":"get_MailboxSemanticSearch","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"The query, in natural language","in":"query","name":"q","required":true,"schema":{"description":"The query, in natural language","maxLength":512,"type":"string"}},{"description":"Maximum messages to return (default 25, max 100)","in":"query","name":"limit","required":false,"schema":{"description":"Maximum messages to return (default 25, max 100)","maximum":100,"minimum":1,"type":"integer"}},{"description":"Pagination cursor for the next page — an offset into the re-issued query's list","in":"query","name":"cursor","required":false,"schema":{"description":"Pagination cursor for the next page — an offset into the re-issued query's list","type":"string"}},{"description":"Only mail received at or after this epoch second (an ANN pre-filter, cheap)","in":"query","name":"since","required":false,"schema":{"description":"Only mail received at or after this epoch second (an ANN pre-filter, cheap)","minimum":0,"type":["integer","null"]}},{"description":"Only mail received before this epoch second","in":"query","name":"before","required":false,"schema":{"description":"Only mail received before this epoch second","minimum":0,"type":["integer","null"]}},{"description":"Restrict to one label or folder. A POST-filter over a candidate list bounded at 100, so it forces hybrid fusion and the answer carries scoped: candidate-bounded","in":"query","name":"label","required":false,"schema":{"description":"Restrict to one label or folder. A POST-filter over a candidate list bounded at 100, so it forces hybrid fusion and the answer carries scoped: candidate-bounded","type":"string"}},{"description":"lexical (default) fuses the BM25 ranking in — hybrid; none answers the semantic ranking alone (ignored when label is given)","in":"query","name":"fuse","required":false,"schema":{"description":"lexical (default) fuses the BM25 ranking in — hybrid; none answers the semantic ranking alone (ignored when label is given)","enum":["lexical","none"],"type":"string"}},{"description":"Whether to include highlighted excerpts","in":"query","name":"snippet","required":false,"schema":{"description":"Whether to include highlighted excerpts","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SemanticSearchResult"}}},"description":"Ranked results with coverage"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, empty_query, or invalid_cursor"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found, not accessible to this principal, or the caller is a folder-scoped viewer"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"semantic_not_enabled — the mailbox has not opted in, or its account lacks the plan gate"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited — the credential's semantic-search budget; Retry-After carries the wait","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"semantic_unavailable — a transient model or index fault; Retry-After carries the wait. Or semantic_misconfigured — a permanent refusal or an unconfigured shard, with NO Retry-After: retrying never resolves it, an operator does. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Semantic (meaning-based) search of a mailbox","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/messages/{messageId}/similar":{"get":{"description":"'More like this': the message's own embedding is the query. The message must already be embedded (semantic search on, and the backfill has reached it) — otherwise 409 not_embedded with the current floor, which is the prompt to lower it (PATCH /identities/:id { semanticFloor }). The read path never embeds inline.","operationId":"get_MessageSimilar","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message ULID","in":"path","name":"messageId","required":true,"schema":{"description":"Message ULID","type":"string"}},{"description":"Maximum messages to return (default 10, max 50)","in":"query","name":"limit","required":false,"schema":{"description":"Maximum messages to return (default 10, max 50)","maximum":50,"minimum":1,"type":"integer"}},{"description":"Only mail received at or after this epoch second","in":"query","name":"since","required":false,"schema":{"description":"Only mail received at or after this epoch second","minimum":0,"type":["integer","null"]}},{"description":"Only mail received before this epoch second","in":"query","name":"before","required":false,"schema":{"description":"Only mail received before this epoch second","minimum":0,"type":["integer","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilarMessagesResult"}}},"description":"Nearest messages by meaning"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — a malformed limit, since or before"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or message not found, or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"semantic_not_enabled — the mailbox has not opted in, or its account lacks the plan gate; or not_embedded — the index holds no vector for the message (below the floor, the backfill has not reached it, or its upsert has not landed); the body carries semanticFloor"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"rate_limited","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"semantic_unavailable (transient, with Retry-After) or semantic_misconfigured (permanent, without). Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Messages similar to one message","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/messages/changes":{"get":{"description":"Answers `created` / `updated` / `destroyed` message ids for everything that happened since `since`, plus a `newState` to send next time. Ids only: fetch what you need through the ordinary message endpoints.\n\n**The loop.** Call once with no `since` to get a starting `newState`; do your full listing; then poll with `since=<newState>`, or better, subscribe to `GET /mailboxes/{mailboxId}/events` and call this whenever a frame arrives (a `state.changed` frame's `Email` value is itself a valid `since`). Keep calling while `hasMore` is true.\n\n**What maps to what.** A delivery is `created`, and so is a restore from trash. Flag, keyword and label changes are `updated`, as is a message whose conversation was merged into another. An expunge (soft delete to trash) and a purge are both `destroyed` — this feed mirrors the ordinary live listing, so use `?state=expunged` if you present a trash view. The feed errs toward telling you too much: a message may be reported `created` where `updated` would have done, which costs one refetch. It never reports a message you still hold as `destroyed`.\n\n**When the token is too old** (or was minted by a mailbox that has since been rebuilt) you get `410 cannot_calculate_changes`. There is no repair: re-list the mailbox and bootstrap a fresh token. History is kept for 30 days, comfortably longer than the 14-day trash window, so this only happens to a client that has been away a long time.","operationId":"get_MessageChanges","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"A previous `newState`. Omit to bootstrap: returns the current state and no changes.","in":"query","name":"since","required":false,"schema":{"description":"A previous `newState`. Omit to bootstrap: returns the current state and no changes.","maxLength":200,"type":"string"}},{"description":"Maximum ids per response across all three sets (default and cap 500)","in":"query","name":"limit","required":false,"schema":{"description":"Maximum ids per response across all three sets (default and cap 500)","maximum":500,"minimum":1,"type":"integer"}},{"description":"Comma-separated companions computed in the SAME store turn as the feed, so they describe exactly the state `newState` names: `labels` — the label vector `GET /labels` returns (counts, UIDVALIDITY, UIDNEXT, HIGHESTMODSEQ), `sync` — for every id in `created` and `updated` on this page, the folder-sync projection (per-label uid/modseq, flags, keywords, blobHash, size, receivedAt) under `sync`. A sync client that asks for both makes ONE request per poll instead of `changes` + `labels` + N × `batch`.","in":"query","name":"include","required":false,"schema":{"description":"Comma-separated companions computed in the SAME store turn as the feed, so they describe exactly the state `newState` names: `labels` — the label vector `GET /labels` returns (counts, UIDVALIDITY, UIDNEXT, HIGHESTMODSEQ), `sync` — for every id in `created` and `updated` on this page, the folder-sync projection (per-label uid/modseq, flags, keywords, blobHash, size, receivedAt) under `sync`. A sync client that asks for both makes ONE request per poll instead of `changes` + `labels` + N × `batch`.","maxLength":64,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"examples":{"bootstrap (no since)":{"value":{"created":[],"destroyed":[],"hasMore":false,"newState":"MjgtOTE4NDI","updated":[]}},"incremental (since=<previous newState>)":{"value":{"created":["01J9MSGA8C2E5H1K4M00000000"],"destroyed":[],"hasMore":false,"newState":"MjgtOTE4NzA","oldState":"MjgtOTE4NDI","updated":["01J9MSGB3D7F9H2J5N00000000"]}}},"schema":{"$ref":"#/components/schemas/MessageChangesFeed"}}},"description":"The changes since `since` (or the current state, on a bootstrap call)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"cannot_calculate_changes — the token is too old or foreign; re-list and bootstrap a new one"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get message sync changes","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/events":{"get":{"description":"Upgrades to a WebSocket that streams best-effort change signals for this mailbox: message.new (delivery), message.updated / message.expunged / message.restored / message.purged, label.expunged (IMAP EXPUNGE), label.created / label.renamed / label.updated / label.deleted, trash.emptied, thread.merged (an arrival joined two conversations — re-list thread views, since thread ids are convergent rather than stable), shares.changed, forwarding.changed (owner-only: forwarding destinations or forward-everything changed, including via the recipient's disable link), pickup.failed / pickup.completed (owner-only), and state.changed. A subscriber holding a system or account key also receives identity.suspension_changed when the account owner suspends or resumes this mailbox (`{ identityId, suspended, generation, revision }`; a lower (generation, revision) never overrides a higher one). Each frame is `{ v, type, ts, data }` with identifiers only — never message content. The vocabulary is additive: treat an unrecognized `type` as a generic 'something changed' nudge rather than an error.\n\nSignals are not a journal: there is no replay or backlog, so on every (re)connect re-sync and treat each event as 'this changed, re-fetch it'. A `state.changed` frame carries the current state token for each type (`{ Email, Mailbox, Thread, EmailDelivery }`); its `Email` value is exactly what `GET /mailboxes/{mailboxId}/messages/changes` accepts as `since`, so a client can re-sync incrementally instead of re-listing. A `ready` frame with the session deadline is sent on connect; the session is closed with code 4401 (session_expired — reconnect with a fresh bearer) after 12h, 4403 (credential_revoked — the app password was revoked; do not reconnect with it) or 4410 (mailbox_gone — stop reconnecting). Keepalive: send a `ping` text frame, receive `pong`.","operationId":"get_MailboxEvents","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"`state`: subscribe to change SIGNALS only — `state.changed`, `label.*`, `trash.emptied`, `credential.revoked`, `ready` — and never the per-message `message.*` frames. For a consumer that treats every frame as the same 'something changed' nudge and re-syncs from `GET /messages/changes` (the IMAP gateway), this removes one frame per message on every bulk mutation. Omit for the full stream.","in":"query","name":"frames","required":false,"schema":{"description":"`state`: subscribe to change SIGNALS only — `state.changed`, `label.*`, `trash.emptied`, `credential.revoked`, `ready` — and never the per-message `message.*` frames. For a consumer that treats every frame as the same 'something changed' nudge and re-syncs from `GET /messages/changes` (the IMAP gateway), this removes one frame per message on every bulk mutation. Omit for the full stream.","enum":["state"],"type":"string"}},{"description":"Accepted and ignored. This socket no longer carries `pim.changed`: calendar, task and contact signals come from the PIM store's own channel (`GET /identities/{identityId}/pim/events`). `off` once opted out of a relay of them here, and stays valid so existing clients keep connecting.","in":"query","name":"pim","required":false,"schema":{"description":"Accepted and ignored. This socket no longer carries `pim.changed`: calendar, task and contact signals come from the PIM store's own channel (`GET /identities/{identityId}/pim/events`). `off` once opted out of a relay of them here, and stays valid so existing clients keep connecting.","enum":["off"],"type":"string"}}],"responses":{"101":{"description":"Switching Protocols — the WebSocket is established"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found (or not accessible to this principal)"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_gone — the mailbox is being deleted; stop reconnecting"},"426":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"upgrade_required — the request was not a WebSocket upgrade"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_many_subscribers — the per-mailbox subscriber cap is reached","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Subscribe to live mailbox change events over WebSocket","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/messages/compose":{"post":{"description":"Constructs and saves an email message from structured JSON (headers, body text/HTML, attachments) into a mailbox without sending.","operationId":"post_MessageCompose","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Target label (default INBOX)","in":"query","name":"label","required":false,"schema":{"description":"Target label (default INBOX)","type":"string"}},{"description":"Comma-separated initial flags, e.g. seen,draft","in":"query","name":"flags","required":false,"schema":{"description":"Comma-separated initial flags, e.g. seen,draft","type":"string"}},{"description":"Whether to run the mailbox's active Sieve filter (default false)","in":"query","name":"filter","required":false,"schema":{"description":"Whether to run the mailbox's active Sieve filter (default false)","enum":["true","false"],"type":"string"}},{"description":"Epoch seconds recorded as receivedAt (default now)","in":"query","name":"internaldate","required":false,"schema":{"description":"Epoch seconds recorded as receivedAt (default now)","maximum":253402300799,"minimum":-62135596800,"type":["integer","null"]}},{"description":"Optional client idempotency key to prevent duplicate imports. Stored NAMESPACED as `append:<your id>` (an append is the mailbox's own side writing its own row, announced as `message.imported`, not `message.new`), so the traffic log and the filtered response show that form — retry with your original value.","in":"header","name":"x-delivery-id","required":false,"schema":{"description":"Optional client idempotency key to prevent duplicate imports. Stored NAMESPACED as `append:<your id>` (an append is the mailbox's own side writing its own row, announced as `message.imported`, not `message.new`), so the traffic log and the filtered response show that form — retry with your original value.","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"from":{"email":"grace@acme.example","name":"Grace Hopper"},"inReplyTo":"<7f2a1c9e4b8d@mail.example.com>","references":["<7f2a1c9e4b8d@mail.example.com>"],"subject":"Re: Q3 report draft","text":"Thanks Ada, final version attached.\n\nGrace","to":[{"email":"ada@example.com","name":"Ada Lovelace"}]},"schema":{"properties":{"attachments":{"items":{"properties":{"blobId":{"description":"Staged-upload form: a blobId from POST /mailboxes/{id}/uploads (or JMAP /upload)","maxLength":64,"minLength":1,"type":"string"},"content":{"description":"Inline form: base64 payload","type":"string"},"contentId":{"maxLength":255,"type":["string","null"]},"contentType":{"description":"Defaults to the stored part's / upload's type for a reference or blob, else application/octet-stream","maxLength":255,"type":["string","null"]},"filename":{"description":"Required for an inline attachment. For a reference or a staged upload, defaults to the stored part's filename (or \"attachment\").","maxLength":255,"minLength":1,"type":"string"},"messageId":{"description":"Reference form: a message in THIS mailbox to take the part from","maxLength":64,"minLength":1,"type":"string"},"section":{"description":"Reference form: the part's section, as reported by /messages/{id}/content","maxLength":64,"pattern":"^[0-9]+(\\.[0-9]+)*$","type":"string"}},"type":"object"},"maxItems":50,"type":"array"},"bcc":{"items":{"$ref":"#/components/schemas/MailAddress"},"maxItems":100,"type":"array"},"cc":{"items":{"$ref":"#/components/schemas/MailAddress"},"maxItems":100,"type":"array"},"from":{"$ref":"#/components/schemas/MailAddress"},"headers":{"additionalProperties":{"type":"string"},"description":"Extra headers; structural ones (Content-Type, Date, …) are refused","type":"object"},"html":{"description":"HTML body; paired with text as multipart/alternative","type":["string","null"]},"inReplyTo":{"description":"Parent Message-ID, angle-bracketed","maxLength":512,"type":["string","null"]},"messageId":{"description":"Overrides the generated Message-ID","maxLength":998,"type":["string","null"]},"references":{"items":{"maxLength":512,"type":"string"},"maxItems":50,"type":"array"},"replyTo":{"items":{"$ref":"#/components/schemas/MailAddress"},"maxItems":10,"type":"array"},"subject":{"maxLength":2000,"type":["string","null"]},"text":{"description":"Plain-text body","type":["string","null"]},"to":{"items":{"$ref":"#/components/schemas/MailAddress"},"maxItems":100,"type":"array"}},"required":["from"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendResult"}}},"description":"Stored (uid + uidValidity answer IMAP APPENDUID), or status:filtered when an opted-in Sieve filter discarded it"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_flag, invalid delivery id, or a message the server refused to build (header_newline, reserved_header, invalid_address, invalid_base64, …) — the `field` names the offending input"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"receiving_disabled (policyScope \"mailbox\"): this mailbox's receive hold is `disabled`, and the caller reaches it through a share grant. A grantee's write is refused as arriving mail is; the mailbox's own user and its account write as ever."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found/not accessible, unknown_label, or mailbox_gone"},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Content-Length required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"JSON body exceeds MAX_JSON_BODY_BYTES, or the assembled message exceeds MAX_MESSAGE_BYTES"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"receiving_paused (policyScope \"mailbox\", with Retry-After): this mailbox's receive hold is `paused`, and the caller reaches it through a share grant. Retry once the owner clears it.","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"superseded/reaped (lost pending intent; retry with the same X-Delivery-Id), or temporary_failure (this mailbox's receive policy could not be established for a grantee's write; retry)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"over_quota (mailbox storage limit), account_over_quota (the account storage pool), or store_metadata_full (the store's own metadata ceiling — no limit to raise; purging messages is the remedy) — distinct so the client knows which remedy applies"}},"summary":"Save structured message to mailbox","tags":["Messages"],"x-max-json-body-bytes":26214400}},"/api/v1/mailboxes/{mailboxId}/messages/copy":{"post":{"description":"Stores each message again, from its original bytes, in a folder of another mailbox you can reach, with its flags, keywords and received time. With `move`, each message that landed is then deleted from this mailbox (recoverably, as DELETE /messages does). Within ONE mailbox use PATCH /messages instead: a label is a copy there, and nothing is duplicated.\n\nYou need `r` here (and `t` to move) and `i` on the destination. A folder-scoped grant works on either side: messages outside your folders are `not_found`, and `toLabel` must be one of your folders in the destination.\n\nThe call answers ONE PAGE of up to 20 messages. While `nextAfter` is not null, repeat the request with the same operands and `after` set to it. `nextAfter` is also null once the destination has refused a message (over quota, gone): the gesture is over, and `remaining` says how much was never attempted. Send one `gestureId` for the whole gesture: a retried page then answers `duplicate` for what it already stored instead of storing it twice.","operationId":"post_MessageCopy","parameters":[{"description":"The SOURCE mailbox ULID — the one the messages are read from","in":"path","name":"mailboxId","required":true,"schema":{"description":"The SOURCE mailbox ULID — the one the messages are read from","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"after":{"description":"The previous page's `nextAfter`","minLength":1,"type":"string"},"gestureId":{"description":"Your idempotency token for this gesture, the same on every page and every retry of it, and new for every new gesture. Required on a move. Omitted on a copy, every call is its own intent and a retry stores a second copy.","pattern":"^[A-Za-z0-9_-]{1,64}$","type":"string"},"ids":{"description":"Message IDs to copy","items":{"type":"string"},"maxItems":200,"minItems":1,"type":"array"},"move":{"description":"Delete each source message once its copy has landed. Only landed messages are deleted, and a failed delete is reported per message (`sourceRemoved: false`), never by undoing the copy. REQUIRES `gestureId` (gesture_required without it): a move is two commits in two stores, and the token is what lets a retry finish one that stopped between them instead of copying it again.","type":"boolean"},"threadIds":{"description":"Conversation IDs whose members to copy, expanded server-side on every page exactly as on PATCH /messages. Refused with thread_too_large past 1000 expanded messages.","items":{"type":"string"},"maxItems":50,"minItems":1,"type":"array"},"threadLabel":{"description":"The folder each conversation in `threadIds` was being viewed in, as on PATCH /messages. REQUIRED with `threadIds` on a move, as it is on DELETE /messages, because a move deletes what it expanded.","minLength":1,"type":"string"},"threadLabelOnly":{"description":"Narrow each conversation to the members FILED UNDER `threadLabel`, as on PATCH /messages — so a conversation moved out of the Inbox does not take the Sent copy of your replies with it.","type":"boolean"},"toLabel":{"description":"The destination folder, by name. It must exist; it is never created.","minLength":1,"type":"string"},"toMailboxId":{"description":"The destination mailbox ULID","minLength":1,"type":"string"}},"required":["toMailboxId","toLabel"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageCopyResult"}}},"description":"This page's outcome per source message"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, target_required (neither ids nor threadIds), same_mailbox, gesture_required (a move without gestureId), thread_context_required, thread_too_large, or unknown_label — with `label` naming the folder: `toLabel` when it is no folder you can file into in the destination, `threadLabel` when it is no folder of yours here"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — either mailbox is missing or not accessible with the rights this needs"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Copy or move messages and conversations into another mailbox","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/messages/{messageId}/learn":{"post":{"description":"Submits spam or ham training feedback for a specific email message to tune the spam filter. Idempotent per message and class: if this message was already taught this class — by an earlier call, or by the user moving it into or out of Junk (which trains on its own after a short undo window) — the call answers 202 without sending it again, and it supersedes a move-triggered sample still waiting out that window. The opposite class is always sent.","operationId":"post_MessageLearn","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message ULID identifier","in":"path","name":"messageId","required":true,"schema":{"description":"Message ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"class":{"description":"Feedback classification ('spam' for junk, 'ham' for legitimate)","enum":["spam","ham"],"type":"string"}},"required":["class"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}},"required":["status"],"type":"object"}}},"description":"Feedback accepted and queued for spam filter training"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or message not found"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"learning_unavailable — spam filter service is not configured. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Train spam filter from a message","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/messages/learn":{"post":{"description":"Submits spam or ham training feedback for a batch of messages in a single request. Same per-message idempotence as the single form: a message already taught this class is answered `accepted` but not sent again.","operationId":"post_MessageBatchLearn","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"class":{"description":"Feedback classification ('spam' for junk, 'ham' for legitimate)","enum":["spam","ham"],"type":"string"},"ids":{"description":"Array of message IDs to train on","items":{"type":"string"},"maxItems":200,"minItems":1,"type":"array"}},"required":["ids","class"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchLearnResult"}}},"description":"Batch feedback accepted with per-message queue status"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"learning_unavailable — spam filter service is not configured. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Train spam filter from multiple messages","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/messages/untrash":{"post":{"description":"Removes the Trash label from a batch of messages. Where each one lands is its restoresTo: whatever it carries besides Trash if anything, otherwise the filing recorded when it was trashed, otherwise Inbox. Reports as an update on /changes (the rows were never hidden), unlike POST /messages/restore, which reports `created`. For a message on the Recently-deleted TIER use that endpoint instead; here such an id answers not_found. `threadIds` puts a whole conversation back: it expands, server-side and in the same transaction, to the members that are IN the Trash — the mirror of the expansion on POST /messages/patch, and the only set this verb can act on. A conversation with nothing trashed expands to nothing and the call is a no-op.","operationId":"post_MessageBatchUntrash","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"ids":{"description":"Array of message IDs to take out of Trash","items":{"type":"string"},"maxItems":200,"minItems":1,"type":"array"},"threadIds":{"description":"Conversation IDs whose TRASHED members to take out of Trash, expanded server-side. Refused with thread_too_large past 1000 expanded messages.","items":{"type":"string"},"maxItems":50,"minItems":1,"type":"array"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchUntrashResult"}}},"description":"Batch untrash outcomes per message"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, target_required (neither ids nor threadIds given), or thread_too_large"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Take messages out of Trash, back to where they were filed","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/messages/unjunk":{"post":{"description":"Removes the Junk label from a batch of messages — the \"Not spam\" verb, and POST /messages/untrash's counterpart for the other state label. Where each one lands is its restoresTo: whatever it carries besides Junk if anything, otherwise the filing recorded when a label write left it carrying only Junk, otherwise Inbox. An origin label that has since been deleted is matched by name if a label of that name exists again. Reports as an update on /changes (the rows were never hidden). This does NOT train the spam filter; pair it with POST /messages/learn as before. `threadIds` takes a whole conversation out: it expands, server-side and in the same transaction, to the members that are IN Junk. A conversation with nothing junked expands to nothing and the call is a no-op.","operationId":"post_MessageBatchUnjunk","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"ids":{"description":"Array of message IDs to take out of Junk","items":{"type":"string"},"maxItems":200,"minItems":1,"type":"array"},"threadIds":{"description":"Conversation IDs whose JUNKED members to take out of Junk, expanded server-side. Refused with thread_too_large past 1000 expanded messages.","items":{"type":"string"},"maxItems":50,"minItems":1,"type":"array"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchUnjunkResult"}}},"description":"Batch unjunk outcomes per message"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, target_required (neither ids nor threadIds given), or thread_too_large"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Take messages out of Junk, back to where they were filed","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/messages/{messageId}/restore":{"post":{"description":"Restores one message from the Recently-deleted tier back to where it was filed (restoresTo), or Inbox when that is no longer resolvable. For a message on the Trash LABEL use POST /messages/untrash instead. Reports as `created` on /changes, since the row was hidden and is now back.","operationId":"post_MessageRestore","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message ULID identifier","in":"path","name":"messageId","required":true,"schema":{"description":"Message ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageRestoreResult"}}},"description":"Restored message metadata"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or message not found in trash"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Restore an expunged message from trash","tags":["Messages"]}},"/api/v1/mailboxes/{mailboxId}/messages/restore":{"post":{"description":"Restores a batch of messages from the Recently-deleted tier in a single atomic operation, each back to where it was filed (restoresTo). For messages on the Trash LABEL use POST /messages/untrash instead.","operationId":"post_MessageBatchRestore","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ids":{"description":"Array of message IDs to restore","items":{"type":"string"},"maxItems":200,"minItems":1,"type":"array"}},"required":["ids"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRestoreResult"}}},"description":"Batch restore outcomes per message"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Restore multiple messages from trash","tags":["Messages"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/threads":{"get":{"description":"Returns conversation threads, newest activity first, one row per conversation: participants, message and unread counts, and an exemplar message carrying the subject and snippet a row renders. Grouping is by REPLY CHAIN (In-Reply-To/References), never by subject — two unrelated messages sharing a subject are two conversations, and a renamed reply stays in the one it answers. Filtering by `label` and by unread/starred flags uses Gmail semantics: a conversation matches when ANY of its live members does, and the counts then span the whole conversation — but the exemplar is the newest member that MATCHED, so a label-filtered row is faced with the message that folder actually holds. See ThreadListItem.exemplar. Trash and Junk are HIDDEN ROLES: outside their own views a conversation is its live members carrying neither label — they do not qualify a row, are not counted, faced or listed in `participants`/`labels`. `label=Trash` lists conversations by their trashed members and `label=Junk` by their junked ones; a member in both is in the bin (shown in Trash, hidden in Junk). `excludeRoles` adds to that rule and never lifts it.","operationId":"get_ThreadList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Filter threads containing messages with this label (e.g. INBOX)","in":"query","name":"label","required":false,"schema":{"description":"Filter threads containing messages with this label (e.g. INBOX)","type":"string"}},{"description":"System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.","in":"query","name":"excludeRoles","required":false,"schema":{"description":"System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.","items":{"enum":["inbox","sent","drafts","trash","archive","junk"],"type":"string"},"type":"array"}},{"description":"Pagination cursor from previous page","in":"query","name":"cursor","required":false,"schema":{"description":"Pagination cursor from previous page","type":"string"}},{"description":"Maximum threads to return per page (max 100)","in":"query","name":"limit","required":false,"schema":{"description":"Maximum threads to return per page (max 100)","maximum":100,"minimum":1,"type":"integer"}},{"description":"Listing direction: desc (default) = newest first, asc = oldest first. Hold it constant across a cursor crawl — cursors do not encode direction, so switching mid-crawl re-windows the page rather than erroring","in":"query","name":"order","required":false,"schema":{"description":"Listing direction: desc (default) = newest first, asc = oldest first. Hold it constant across a cursor crawl — cursors do not encode direction, so switching mid-crawl re-windows the page rather than erroring","enum":["asc","desc"],"type":"string"}},{"description":"Sort key: arrival (default) = the order mail reached this mailbox (message id); date = the Date header, falling back to arrival where it is absent or unparseable (RFC 5256 SORT DATE). Cursors follow the key, so hold it constant across a crawl — unlike order, a mismatched cursor is refused with 400 invalid_cursor rather than silently re-windowing. Note that under arrival an imported message (APPEND with ?internaldate=) lists where it was imported, not at its receivedAt; date orders imported mail by its own header","in":"query","name":"sortBy","required":false,"schema":{"description":"Sort key: arrival (default) = the order mail reached this mailbox (message id); date = the Date header, falling back to arrival where it is absent or unparseable (RFC 5256 SORT DATE). Cursors follow the key, so hold it constant across a crawl — unlike order, a mismatched cursor is refused with 400 invalid_cursor rather than silently re-windowing. Note that under arrival an imported message (APPEND with ?internaldate=) lists where it was imported, not at its receivedAt; date orders imported mail by its own header","enum":["arrival","date"],"type":"string"}},{"description":"Comma-separated flag names; a message matches only if ALL are set (e.g. flagged)","in":"query","name":"hasFlags","required":false,"schema":{"description":"Comma-separated flag names; a message matches only if ALL are set (e.g. flagged)","type":"string"}},{"description":"Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)","in":"query","name":"notFlags","required":false,"schema":{"description":"Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"threads":[{"exemplar":{"auth":null,"bcc":null,"blobGen":"g1","blobHash":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","cc":[],"deliveryMeta":null,"deliveryState":null,"envelopeFrom":"ada@example.com","envelopeTo":"grace@acme.example","flags":["seen"],"from":[{"email":"ada@example.com","name":"Ada Lovelace"}],"hasAttachment":true,"id":"01J9MSGA8C2E5H1K4M00000000","inReplyTo":null,"keywords":[],"labels":[{"deleted":false,"modseq":91842,"name":"INBOX","uid":4213,"uidValidity":1722470400}],"messageIdHeader":"<7f2a1c9e4b8d@mail.example.com>","receivedAt":1788081300,"referencesIds":[],"sentAt":1788081272,"size":48213,"snippet":"Hi Grace, attached is the Q3 report draft we discussed on Friday…","subject":"Q3 report draft","threadId":"01J9THRD5E8G1J4M7P00000000","to":[{"email":"grace@acme.example","name":null}]},"flaggedCount":0,"labels":["INBOX"],"lastReceivedAt":1788081300,"messageCount":3,"participants":[{"email":"ada@example.com","name":"Ada Lovelace"},{"email":"grace@acme.example","name":"Grace Hopper"}],"threadId":"01J9THRD5E8G1J4M7P00000000","unseenCount":1}]},"schema":{"properties":{"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"},"threads":{"items":{"$ref":"#/components/schemas/ThreadListItem"},"type":"array"}},"required":["threads"],"type":"object"}}},"description":"List of conversation threads"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed — invalid query parameters or mismatched cursor"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or label not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List conversation threads","tags":["Threads"]}},"/api/v1/mailboxes/{mailboxId}/threads/{threadId}":{"get":{"description":"Returns all messages in a conversation thread in chronological order, with pre-computed reply context (In-Reply-To, References, suggested subject and recipient). Automatically resolves merged threads.","operationId":"get_ThreadGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Conversation thread identifier","in":"path","name":"threadId","required":true,"schema":{"description":"Conversation thread identifier","type":"string"}},{"description":"Pagination cursor for next page of messages within thread","in":"query","name":"cursor","required":false,"schema":{"description":"Pagination cursor for next page of messages within thread","type":"string"}},{"description":"Maximum messages to return per page (max 200)","in":"query","name":"limit","required":false,"schema":{"description":"Maximum messages to return per page (max 200)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Folder context for the hidden-role filter — same label the listing was filtered by. Without it, and in every folder but Trash and Junk, members carrying the Trash or Junk label are excluded from both `messages` and `messageCount`; pass the Trash label to see exactly the trashed members, or the Junk label for the junked ones (a member in both is in Trash, not in Junk). This is the member set PATCH /messages's `threadIds` expands to, so a client that renders this view is acting on what it rendered.","in":"query","name":"label","required":false,"schema":{"description":"Folder context for the hidden-role filter — same label the listing was filtered by. Without it, and in every folder but Trash and Junk, members carrying the Trash or Junk label are excluded from both `messages` and `messageCount`; pass the Trash label to see exactly the trashed members, or the Junk label for the junked ones (a member in both is in Trash, not in Junk). This is the member set PATCH /messages's `threadIds` expands to, so a client that renders this view is acting on what it rendered.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadView"}}},"description":"Conversation thread details and message history"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or thread not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get a conversation thread","tags":["Threads"]}},"/api/v1/mailboxes/{mailboxId}/uploads":{"post":{"description":"Streams the request body (the file's raw bytes, NOT base64, NOT multipart) into staging storage and returns a `blobId` to reference from `/send`, `/compose` or `/reply` (the `blobId` form of an attachment). `Content-Length` is required and enforced against the per-message size ceiling. The staged blob expires at the result's `expiresAt`, or earlier when the uploader's oldest temporary blobs must be reclaimed for a new upload. Recorded send retries recover their durable message bytes.","operationId":"post_UploadCreate","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Exact size of the uploaded binary in bytes","in":"header","name":"content-length","required":true,"schema":{"description":"Exact size of the uploaded binary in bytes","type":"string"}},{"description":"MIME type of the uploaded file (default application/octet-stream)","in":"header","name":"content-type","required":false,"schema":{"description":"MIME type of the uploaded file (default application/octet-stream)","type":"string"}}],"requestBody":{"content":{"application/octet-stream":{"schema":{"description":"The file's raw bytes, streamed as sent","format":"binary","type":"string"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"blobId":"01J9B0B4D7F1H3K6M000000000","expiresAt":1788436800,"size":48123,"type":"application/pdf"},"schema":{"$ref":"#/components/schemas/UploadResult"}}},"description":"Staged upload metadata"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"empty_body — request body was empty"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"length_required — Content-Length header is required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large — file exceeds maximum message size; metadata_too_large — Content-Type exceeds metadata limit"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"upload_busy — concurrent upload allowance is full","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"upload_cleanup_pending — temporary storage reclamation must be retried. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"store_full — owner storage is full and this uploader has no reclaimable space"}},"summary":"Stage a binary attachment upload","tags":["Uploads"]}},"/api/v1/mailboxes/{mailboxId}/send":{"post":{"description":"Sends an email from this mailbox to one or more recipients. The server builds the RFC 5322 MIME message, signs DKIM, applies outbound address list policies, and returns delivery results per recipient. Supports immediate and scheduled sending.","operationId":"post_MessageSend","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Save a copy to Sent folder (default true)","in":"query","name":"save","required":false,"schema":{"description":"Save a copy to Sent folder (default true)","enum":["true","false"],"type":"string"}},{"description":"Deliver a bounce notice (DSN) to this mailbox if relay fails (default true)","in":"query","name":"bounce","required":false,"schema":{"description":"Deliver a bounce notice (DSN) to this mailbox if relay fails (default true)","enum":["true","false"],"type":"string"}},{"description":"Optional idempotency key to prevent duplicate sends on network retries. A retry with the same id converges on the original submission instead of sending again, and is not charged against the send allowance a second time. It does not get around a sending hold: while the sender is paused or disabled the retry is refused like any submission (429 sending_paused, 403 sending_disabled), and once the hold lifts it continues at its original charge.","in":"header","name":"x-delivery-id","required":false,"schema":{"description":"Optional idempotency key to prevent duplicate sends on network retries. A retry with the same id converges on the original submission instead of sending again, and is not charged against the send allowance a second time. It does not get around a sending hold: while the sender is paused or disabled the retry is refused like any submission (429 sending_paused, 403 sending_disabled), and once the hold lifts it continues at its original charge.","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"attachments":[{"blobId":"01J9B0B4D7F1H3K6M000000000","contentType":"application/pdf","filename":"q3-report-final.pdf"}],"from":{"email":"grace@acme.example","name":"Grace Hopper"},"html":"<p>Thanks Ada, final version attached.</p><p>Grace</p>","inReplyTo":"<7f2a1c9e4b8d@mail.example.com>","references":["<7f2a1c9e4b8d@mail.example.com>"],"subject":"Re: Q3 report draft","text":"Thanks Ada, final version attached.\n\nGrace","to":[{"email":"ada@example.com","name":"Ada Lovelace"}]},"schema":{"properties":{"attachments":{"description":"List of file attachments","items":{"properties":{"blobId":{"description":"Staged-upload form: a blobId from POST /mailboxes/{id}/uploads (or JMAP /upload)","maxLength":64,"minLength":1,"type":"string"},"content":{"description":"Inline form: base64 payload","type":"string"},"contentId":{"maxLength":255,"type":["string","null"]},"contentType":{"description":"Defaults to the stored part's / upload's type for a reference or blob, else application/octet-stream","maxLength":255,"type":["string","null"]},"filename":{"description":"Required for an inline attachment. For a reference or a staged upload, defaults to the stored part's filename (or \"attachment\").","maxLength":255,"minLength":1,"type":"string"},"messageId":{"description":"Reference form: a message in THIS mailbox to take the part from","maxLength":64,"minLength":1,"type":"string"},"section":{"description":"Reference form: the part's section, as reported by /messages/{id}/content","maxLength":64,"pattern":"^[0-9]+(\\.[0-9]+)*$","type":"string"}},"type":"object"},"maxItems":50,"type":"array"},"autoSubmitted":{"description":"RFC 3834 marker for mail an automaton sends: auto-generated (a notification) or auto-replied (an answer to a message). Written as the Auto-Submitted header so a receiver's loop guards recognise it; refused alongside a free-form Auto-Submitted in headers (auto_submitted_conflict)","enum":["auto-generated","auto-replied"],"type":["string","null"]},"bcc":{"description":"Blind carbon copy recipient email addresses (hidden from message headers)","items":{"$ref":"#/components/schemas/MailAddress"},"maxItems":50,"type":"array"},"cc":{"description":"Carbon copy recipient email addresses","items":{"$ref":"#/components/schemas/MailAddress"},"maxItems":50,"type":"array"},"from":{"allOf":[{"$ref":"#/components/schemas/MailAddress"},{"description":"Sender email address (must belong to this mailbox)"}]},"headers":{"additionalProperties":{"type":"string"},"description":"Additional custom email headers","type":"object"},"html":{"description":"HTML body","type":["string","null"]},"inReplyTo":{"description":"In-Reply-To Message-ID","maxLength":512,"type":["string","null"]},"references":{"description":"References header Message-IDs","items":{"maxLength":512,"type":"string"},"maxItems":50,"type":"array"},"replyTo":{"description":"Reply-To email addresses","items":{"$ref":"#/components/schemas/MailAddress"},"maxItems":10,"type":"array"},"sendAt":{"description":"Release time, epoch seconds. In the future ⇒ the message is stored as a draft and sent then (202 + a schedule); at or before now ⇒ sent immediately. Requires the Sent copy (`?save` may not be false).","format":"int64","type":["integer","null"]},"subject":{"description":"Message subject line","maxLength":2000,"type":["string","null"]},"text":{"description":"Plain text body","type":["string","null"]},"to":{"description":"Primary recipient email addresses","items":{"$ref":"#/components/schemas/MailAddress"},"maxItems":50,"type":"array"}},"required":["from"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"deliveryId":"01J9DVRY2C5E8G1J4M00000000","recipients":[{"address":"ada@example.com","deliveryId":"01J9DVRY2C5E8G1J4M00000001","status":"queued"}],"sentCopy":"saved","sentThreadId":"01J9THRD5E8G1J4M7P00000000"},"schema":{"$ref":"#/components/schemas/SendResult"}}},"description":"Every recipient was accepted (delivered, queued, or filtered)"},"202":{"content":{"application/json":{"example":{"attempts":0,"createdAt":1788264000,"deferrals":0,"deliveryId":"01J9DVRY2C5E8G1J4M00000000","error":null,"finishedAt":null,"messageId":"01J9MSGB3D7F9H2J5N00000000","recipients":["ada@example.com"],"releaseAt":1788858000,"result":null,"scheduleId":"01J9SCHD6F9H2K5N8Q00000000","sendAt":1788858000,"state":"pending","threadId":"01J9THRD5E8G1J4M7P00000000"},"schema":{"$ref":"#/components/schemas/ScheduledSend"}}},"description":"Scheduled (`sendAt` in the future): the message is stored as a draft and released at that time. The delivery id is SPENT by the schedule — a later submission carrying the same `X-Delivery-Id` answers this same resource rather than sending again, whatever state it has reached (`state` says which), so a retry can never un-cancel or double-send"},"207":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}},"description":"Mixed: at least one recipient failed. The array carries each address's own status and error; retry with the same X-Delivery-Id to converge only the failures. A hold placed on the sender while the request runs refuses the recipients not yet handled with sending_paused (temporary) or sending_disabled (permanent); recipients already delivered or queued keep their status"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, no_recipients, too_many_recipients, auto_submitted_conflict (autoSubmitted alongside a free-form Auto-Submitted header), a refused build (header_newline, reserved_header, invalid_address, invalid_base64, …), a bad attachment reference (unknown_message / unknown_part / part_unresolvable, each carrying the offending `index`), or a refused schedule: send_at_too_far, send_at_requires_save, recipient_not_permitted, recipient_not_verified (the account is not yet vetted and may send only to its verified recipients; carries the first `address` that is not one)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Permanent — sender_not_owned | sender_not_local | sending_disabled (the mailbox, its domain, or its account may not send) | credential_scope (the credential is scoped below `send`, design D50; carries `scope` and `required`) | mailbox_gone (the sending mailbox was torn down mid-submission) | too_many_recipients (the submission's own recipient count exceeds the sender's recipient cap — an empty window would refuse it too, so unlike the 429 rate_limited this can never clear; distinct from the 400 of the same name, which is the per-request recipient-list bound)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Permanent — not_found (the mailbox does not exist, or is not this caller's: cross-tenant and missing collapse to one indistinguishable answer) or mailbox_gone (the sending mailbox was torn down mid-submission)."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Permanent — delivery_id_reused: this X-Delivery-Id belongs to an accepted message with a different sender or additional recipients, an incompatible scheduled submission, or an immediate send outside its 14-day retry window. Use a fresh id for a new message. Same-key retries of the original recipient set or a subset use the original MIME, acceptance time and save/bounce choices, including when no Sent copy was saved. Expunging Sent does not release a retained immediate admission key."},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Content-Length required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"JSON body exceeds MAX_JSON_BODY_BYTES, the assembled message exceeds MAX_MESSAGE_BYTES, or attachments_too_large (referenced + inline attachment bytes exceed the per-message budget)"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"TEMPORARY, and the only 4xx here that is — retry, never surface it as a permanent failure. rate_limited (the sender is over its daily msgs/rcpts allowance) and sending_paused (a reversible hold: non-payment, an investigation, or the account's deletion window) both carry `Retry-After` plus `retryAfterSeconds`; too_many_scheduled means the mailbox is at its cap of pending scheduled sends and carries `limit`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"internal — a required Sent or Drafts label is missing; blob_unavailable — an attachment source disappeared, changed length or failed while streaming, before submission admission. Retry when the source is available."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Sent copy lost its pending intent (superseded or reaped), or submission_record_unavailable: canonical message bytes, the original Sent reference, durable admission or submission plan could not be recovered or prepared before recipient dispatch. Retry with the same X-Delivery-Id; a permanently missing canonical source requires a new submission with a fresh id. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"over_quota, account_over_quota, or store_metadata_full (the store's metadata ceiling; the remedy is purging messages) — a SCHEDULED send only: the draft it must store has nowhere to live. An immediate send is never refused for storage; a Sent copy that cannot be stored degrades to `sentCopy: \"over_quota\"` in the result instead (one collapsed word for every storage refusal)"}},"summary":"Send an email message","tags":["Delivery"],"x-max-json-body-bytes":26214400}},"/api/v1/mailboxes/{mailboxId}/threads/{threadId}/reply":{"post":{"description":"Sends a reply to an existing email conversation. The server automatically derives recipient addresses, Subject line, In-Reply-To, and References headers from the conversation thread. A same-key retry of a stored reply retains its original recipient and MIME even if the conversation has advanced.","operationId":"post_ThreadReply","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Conversation thread identifier to reply to","in":"path","name":"threadId","required":true,"schema":{"description":"Conversation thread identifier to reply to","type":"string"}},{"description":"Whether to save a copy in the Sent folder (default true)","in":"query","name":"save","required":false,"schema":{"description":"Whether to save a copy in the Sent folder (default true)","enum":["true","false"],"type":"string"}},{"description":"Whether to deliver a non-delivery report if relay fails (default true)","in":"query","name":"bounce","required":false,"schema":{"description":"Whether to deliver a non-delivery report if relay fails (default true)","enum":["true","false"],"type":"string"}},{"description":"Client-provided idempotency key for this submission. A retry with the same id converges on the original submission instead of sending again, and is not charged against the send allowance a second time. It does not get around a sending hold: while the sender is paused or disabled the retry is refused like any submission (429 sending_paused, 403 sending_disabled), and once the hold lifts it continues at its original charge.","in":"header","name":"x-delivery-id","required":false,"schema":{"description":"Client-provided idempotency key for this submission. A retry with the same id converges on the original submission instead of sending again, and is not charged against the send allowance a second time. It does not get around a sending hold: while the sender is paused or disabled the retry is refused like any submission (429 sending_paused, 403 sending_disabled), and once the hold lifts it continues at its original charge.","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"html":"<p>Thanks, looks good. Shipping it.</p>","text":"Thanks, looks good. Shipping it."},"schema":{"properties":{"attachments":{"items":{"properties":{"blobId":{"description":"Staged-upload form: a blobId from POST /mailboxes/{id}/uploads (or JMAP /upload)","maxLength":64,"minLength":1,"type":"string"},"content":{"description":"Inline form: base64 payload","type":"string"},"contentId":{"maxLength":255,"type":["string","null"]},"contentType":{"description":"Defaults to the stored part's / upload's type for a reference or blob, else application/octet-stream","maxLength":255,"type":["string","null"]},"filename":{"description":"Required for an inline attachment. For a reference or a staged upload, defaults to the stored part's filename (or \"attachment\").","maxLength":255,"minLength":1,"type":"string"},"messageId":{"description":"Reference form: a message in THIS mailbox to take the part from","maxLength":64,"minLength":1,"type":"string"},"section":{"description":"Reference form: the part's section, as reported by /messages/{id}/content","maxLength":64,"pattern":"^[0-9]+(\\.[0-9]+)*$","type":"string"}},"type":"object"},"maxItems":50,"type":"array"},"autoSubmitted":{"description":"RFC 3834 marker for mail an automaton sends: auto-generated (a notification) or auto-replied (an answer to a message). Written as the Auto-Submitted header so a receiver's loop guards recognise it; refused alongside a free-form Auto-Submitted in headers (auto_submitted_conflict)","enum":["auto-generated","auto-replied"],"type":["string","null"]},"fromAddress":{"description":"Address to send the reply as; must be one this mailbox may send as (else 403 sender_not_owned). Defaults to the address the conversation reached this mailbox at, while it still routes here, else the primary address","format":"email","maxLength":254,"type":["string","null"]},"fromName":{"description":"Display name for the From header","maxLength":320,"type":["string","null"]},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"html":{"type":["string","null"]},"sendAt":{"description":"Release time, epoch seconds. In the future ⇒ the message is stored as a draft and sent then (202 + a schedule); at or before now ⇒ sent immediately. Requires the Sent copy (`?save` may not be false).","format":"int64","type":["integer","null"]},"subject":{"description":"Overrides the derived \"Re: …\" subject","maxLength":2000,"type":["string","null"]},"text":{"type":["string","null"]}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}},"description":"The reply was accepted for its recipient"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledSend"}}},"description":"Scheduled (`sendAt` in the future): the reply is stored as a draft and released then"},"207":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}},"description":"The recipient failed; the array carries the reason. sending_paused there is temporary (a hold landed while the request ran): retry with the same X-Delivery-Id once it lifts"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, no_reply_target (the thread has no answerable address, e.g. a null-sender DSN), auto_submitted_conflict (autoSubmitted alongside a free-form Auto-Submitted header), no_primary_address (no fromAddress was given, the conversation's own address does not route here, and the mailbox has no primary address to fall back on), delivery_id_too_long, reserved_delivery_id, or a refused build"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Permanent — sender_not_owned | sender_not_local | sending_disabled (the mailbox, its domain, or its account may not send) | credential_scope (the credential is scoped below `send`, design D50) | mailbox_gone (the sending mailbox was torn down mid-submission)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or thread not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"delivery_id_reused — the key belongs to another conversation, a message without a single visible reply recipient, a recorded message with a different sender or recipient set, an incompatible scheduled submission, or an immediate send outside its 14-day retry window. Use a fresh X-Delivery-Id for a new message."},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Content-Length required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"JSON body exceeds MAX_JSON_BODY_BYTES, the assembled message exceeds MAX_MESSAGE_BYTES, or attachments_too_large (referenced + inline attachment bytes exceed the per-message budget)"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"TEMPORARY, and the only 4xx here that is — retry, never surface it as a permanent failure. rate_limited and sending_paused (a reversible hold) carry `Retry-After` plus `retryAfterSeconds`; too_many_scheduled carries `limit`. This route shares /send's submission path (performSend), so it answers the same refusals.","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"internal — a required Sent or Drafts label is missing; blob_unavailable — an attachment source disappeared, changed length or failed while streaming, before submission admission. Retry when the source is available."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Sent copy lost its pending intent (superseded or reaped), or submission_record_unavailable: the submission plan could not be durably prepared before recipient dispatch. Retry with the same X-Delivery-Id. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"over_quota or account_over_quota — a SCHEDULED reply only: the draft it must store has nowhere to live. An immediate reply is never refused for storage"}},"summary":"Reply to a conversation thread","tags":["Delivery"],"x-max-json-body-bytes":26214400}},"/api/v1/mailboxes/{mailboxId}/messages/{messageId}/submit":{"post":{"description":"Sends a message already stored in this mailbox as a draft, byte-for-byte as stored: the `Bcc` header is stripped from the wire copy, the envelope is derived from the message's own `Sender`/`From` (return path) and `To`/`Cc`/`Bcc` (recipients), and the draft row itself becomes the Sent copy — no rebuild, no second copy. Every `From` address must be this mailbox's own. Answers one result per recipient like `/send` (`200` all accepted, `207` mixed). A retryable per-recipient outcome is retried by the server (`202`, state `pending`) rather than reported as `failed`; a replay under the same `X-Delivery-Id` answers `202` with the submission's own record.","operationId":"post_MessageSubmit","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"The draft's message ULID","in":"path","name":"messageId","required":true,"schema":{"description":"The draft's message ULID","type":"string"}},{"description":"Deliver a bounce notice (DSN) to this mailbox if relay fails (default true)","in":"query","name":"bounce","required":false,"schema":{"description":"Deliver a bounce notice (DSN) to this mailbox if relay fails (default true)","enum":["true","false"],"type":"string"}},{"description":"Optional idempotency key: a replay answers 202 with this submission's own record instead of sending again","in":"header","name":"x-delivery-id","required":false,"schema":{"description":"Optional idempotency key: a replay answers 202 with this submission's own record instead of sending again","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}},"description":"Every recipient was accepted (delivered, queued, or filtered); the draft is now in Sent"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledSend"}}},"description":"The submission is on record as this schedule and is not (or not yet) a finished send — a REPLAY under the same `X-Delivery-Id` (`state` says what became of it), or a release the server deferred to retry itself (`state: pending`, `error` names why). The draft keeps `$submitpending` until it settles"},"207":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}},"description":"Mixed: at least one recipient failed permanently. The draft moved to Sent if any recipient was accepted, else stays a draft wearing `$submitfailed`"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, no_recipients, too_many_recipients, invalid_recipients (a To/Cc/Bcc header is not a valid address list, so the envelope cannot be derived — never guessed at), invalid_from (no usable Sender/From), invalid_address (an envelope address contains ASCII controls), ambiguous_sender (more than one Sender/From address, so no return path can be derived), or a malformed X-Delivery-Id"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Permanent — sender_not_owned | sender_not_local | sending_disabled (the mailbox, its domain, or its account may not send) | credential_scope (the credential is scoped below `send`, design D50) | recipient_not_permitted (a recipient of the draft is outside the submitting credential's own allowlist, naming the `address`) | from_not_owned | from_sending_disabled (an RFC 5322 From address is not this mailbox's to send under)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found (the mailbox or message does not exist, or is not this caller's) or mailbox_gone (the mailbox was torn down mid-submission)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_a_draft — the message is not (or no longer) a draft: moved out of Drafts, in Trash, `\\Draft` cleared, or already sent. already_scheduled — a pending schedule holds this draft; cancel it first (carries `scheduleId`). delivery_id_reused — the delivery ID belongs to another submission mode or its original retry window has expired."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"TEMPORARY — rate_limited (over the daily allowance), sending_paused or from_sending_paused (a reversible hold), all with `Retry-After` and `retryAfterSeconds`; retry with the same X-Delivery-Id","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"blob_unreadable — the draft's bytes could not be read right now; submission_record_unavailable — the durable admission could not be read or reserved. Retry with the same delivery ID. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Send a stored draft","tags":["Delivery"]}},"/api/v1/mailboxes/{mailboxId}/scheduled":{"get":{"description":"Returns scheduled email sends for this mailbox. By default lists pending sends; pass state to view historical or completed scheduled sends.","operationId":"get_ScheduledList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Filter by state ('pending', 'releasing', 'sent', 'failed', 'canceled')","in":"query","name":"state","required":false,"schema":{"description":"Filter by state ('pending', 'releasing', 'sent', 'failed', 'canceled')","enum":["pending","releasing","sent","failed","canceled"],"type":"string"}},{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"nextCursor":{"description":"Opaque cursor for the next page; absent on the last page","type":"string"},"scheduled":{"items":{"$ref":"#/components/schemas/ScheduledSend"},"type":"array"}},"required":["scheduled"],"type":"object"}}},"description":"List of scheduled sends"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List scheduled sends","tags":["Delivery"]}},"/api/v1/mailboxes/{mailboxId}/scheduled/{scheduleId}":{"get":{"description":"Returns the details and delivery status of a specific scheduled email send.","operationId":"get_ScheduledGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Scheduled send ULID identifier","in":"path","name":"scheduleId","required":true,"schema":{"description":"Scheduled send ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledSend"}}},"description":"Scheduled send details"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or schedule not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get a scheduled send","tags":["Delivery"]},"patch":{"description":"Moves WHEN a pending scheduled send fires. The message itself is untouched — same draft, same delivery id, same recipients — so this is not the draft-replacing 'edit in place' the design rules out; editing the MESSAGE remains cancel + resubmit. Pending sends only: once a release has started its legs may already be on the wire, and moving the time would neither recall them nor stop it.","operationId":"patch_ScheduledReschedule","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Scheduled send ULID identifier","in":"path","name":"scheduleId","required":true,"schema":{"description":"Scheduled send ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"sendAt":{"description":"New release time, epoch seconds. Must be in the future and within the same horizon a schedule may be created at.","format":"int64","type":"integer"}},"required":["sendAt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledSend"}}},"description":"The schedule, with its new time"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"send_at_in_past or send_at_too_far"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or schedule not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"cannot_unsend (release already started), schedule_failed, or already_canceled"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Change a scheduled send's release time","tags":["Delivery"],"x-max-json-body-bytes":1048576}},"/api/v1/mailboxes/{mailboxId}/scheduled/{scheduleId}/cancel":{"post":{"description":"Cancels a pending scheduled send. The draft message is preserved as an editable draft in the mailbox.","operationId":"post_ScheduledCancel","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Scheduled send ULID identifier","in":"path","name":"scheduleId","required":true,"schema":{"description":"Scheduled send ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"canceled":{"description":"True if scheduled send was canceled","type":"boolean"}},"required":["canceled"],"type":"object"}}},"description":"Cancellation confirmed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox or schedule not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"cannot_unsend (release already started) or schedule_failed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Cancel a scheduled send","tags":["Delivery"]}},"/api/v1/mailboxes/{mailboxId}/scheduled/cancel":{"post":{"description":"Cancels all pending scheduled sends for this mailbox, optionally scoped to a specific creator credential.","operationId":"post_ScheduledCancelAll","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Filter cancellation to schedules created by this specific credential or API key ID","in":"query","name":"actorId","required":false,"schema":{"description":"Filter cancellation to schedules created by this specific credential or API key ID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"canceled":{"description":"Number of scheduled sends canceled","type":"integer"}},"required":["canceled"],"type":"object"}}},"description":"Count of canceled scheduled sends"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Cancel all scheduled sends for a mailbox","tags":["Delivery"]}},"/api/v1/mailboxes/{mailboxId}/messages/{messageId}/delivery":{"get":{"description":"Delivery status and per-recipient progress for a sent message: local acceptance, acceptance by the destination mail system, or the bounce/rejection reason. `messageId` accepts the Sent copy's message id, the delivery id returned by /send, or the submission id. Answers 404 when there is no delivery record — a message older than the 30-day retention window, or one this mailbox did not send — which callers should render as plain 'sent', not as an error.","operationId":"get_MessageDeliveryGet","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message, delivery or submission identifier","in":"path","name":"messageId","required":true,"schema":{"description":"Message, delivery or submission identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDeliveryStatus"}}},"description":"Delivery status for the requested message"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found, or the message has no delivery record"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get delivery status of a sent message","tags":["Delivery"]}},"/api/v1/mailboxes/{mailboxId}/deliveries":{"get":{"description":"Batch delivery status, so a thread or a page of the Sent folder costs one request rather than one per message. Exactly one of `threadId` or `messageIds` is required. Messages with no delivery record are simply absent from the response — the list is never padded with placeholders. Pages contain at most 100 statuses and may be shorter to fit the response byte budget. Follow nextCursor until absent; cursors expire after one hour.","operationId":"get_DeliveriesList","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Conversation thread identifier","in":"query","name":"threadId","required":false,"schema":{"description":"Conversation thread identifier","type":"string"}},{"description":"Maximum statuses per page; defaults to 100","in":"query","name":"limit","required":false,"schema":{"description":"Maximum statuses per page; defaults to 100","maximum":100,"minimum":1,"type":"integer"}},{"description":"Continuation cursor from the preceding page","in":"query","name":"cursor","required":false,"schema":{"description":"Continuation cursor from the preceding page","type":"string"}},{"description":"Comma-separated message identifiers (at most 100)","in":"query","name":"messageIds","required":false,"schema":{"description":"Comma-separated message identifiers (at most 100)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDeliveryList"}}},"description":"Delivery statuses for the messages that have one"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"invalid_request for invalid selectors or limit; invalid_cursor for a malformed, expired, or differently scoped cursor"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"delivery_status_too_large: a single delivery status exceeds the response byte budget"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List delivery statuses for a thread or a set of messages","tags":["Delivery"]}},"/api/v1/deliver/check":{"get":{"description":"Advisory RCPT-time pre-flight check. By default it is the inbound MTA's question: does the recipient exist here, and do its blocklists and routing rules accept this sender? With `submission=true` it is the submission MTA's question instead: may the authenticated sender (`from`, judged as /deliver/outbound judges X-Envelope-From for the same caller) submit to this recipient under its OWN rules, the identity's and credential's recipient allowlists, its outbound address lists, and its account's verified-recipients rule? That mode answers nothing about the recipient's existence: an outside recipient is accepted when the sender's rules allow it, and /deliver/outbound at DATA stays the authority for everything else. Its verdict depends on `from`, so an MTA must never cache it under the recipient alone.","operationId":"get_DeliverCheck","parameters":[{"description":"Recipient email address being checked","in":"query","name":"to","required":true,"schema":{"description":"Recipient email address being checked","minLength":1,"type":"string"}},{"description":"Sender email address (MAIL FROM). With `submission=true` it names the sender whose rules are judged; absent or empty (the null return path), nothing is judged and the recipient is accepted.","in":"query","name":"from","required":false,"schema":{"description":"Sender email address (MAIL FROM). With `submission=true` it names the sender whose rules are judged; absent or empty (the null return path), nothing is judged and the recipient is accepted.","type":["string","null"]}},{"description":"Connecting client IP address","in":"query","name":"ip","required":false,"schema":{"description":"Connecting client IP address","type":["string","null"]}},{"description":"Connecting client reverse DNS PTR hostname","in":"query","name":"ptr","required":false,"schema":{"description":"Connecting client reverse DNS PTR hostname","type":["string","null"]}},{"description":"Connecting client HELO/EHLO identity","in":"query","name":"helo","required":false,"schema":{"description":"Connecting client HELO/EHLO identity","type":["string","null"]}},{"description":"`true`: judge the SENDER's rules for an authenticated submission instead of the recipient's inbound acceptance (default false). Accepted from system and account keys; a sender the caller may not send as, or one that is held, frozen or gone, is accepted here and refused by /deliver/outbound at DATA, which answers it for the whole message.","in":"query","name":"submission","required":false,"schema":{"description":"`true`: judge the SENDER's rules for an authenticated submission instead of the recipient's inbound acceptance (default false). Accepted from system and account keys; a sender the caller may not send as, or one that is held, frozen or gone, is accepted here and refused by /deliver/outbound at DATA, which answers it for the whole message.","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientAccepted"}}},"description":"Recipient is accepted: deliverable here (default), or permitted by the sender's own rules (`submission=true`)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"FIVE codes, split by the error CODE — the MTA must never map this status alone. receiving_disabled: the address resolves but its domain is not accepting, or the destination mailbox's receive hold is `disabled` (then `policyScope: \"mailbox\"`) — a recipient verdict, reject permanently (550); the mailbox-scope one is never cached, since its owner can clear it. recipient_not_verified, TWO meanings by mode, both permanent (550) and never cached, since vetting the account or the owner confirming lifts them. By default: the address forwards (a remote route, a pattern or catch-all whose destination is remote, or an alias pattern) for an account that is not yet vetted, to a target that is not one of its verified recipients (an address on its own domains, or one whose owner confirmed it; another customer's address is not) — a recipient verdict; /deliver/inbound refuses the same recipient with the same code at DATA. With `submission=true`: the SENDING account is not yet vetted, so it may send only to its verified recipients, and this recipient is neither; the body carries `source: \"verified_recipients\"`, the same code and source /deliver/outbound answers at DATA, for this recipient alone (550 5.7.1), and the verdict depends on `from`. sender_blocked: an address list refuses this MAIL FROM for this recipient — also 550, but note the verdict depends on `from`, so it must NOT be cached under the recipient key alone. recipient_not_permitted (`submission=true` only): one of the SENDER's own policies excludes this recipient, the identity's or credential's recipient allowlist or the sender's outbound address lists; `source` says which (`permitted_recipients` | `address_list`), and an address list also names the deciding `list` and `pattern`. Permanent: 550 5.7.1 for this recipient alone, the same code /deliver/outbound answers at DATA; it depends on `from`, so it may not be cached under the recipient alone. insufficient_scope: this caller may not check at all (mailbox principals never can; with `submission=true`, neither can a system key that must name `X-Acting-Credential` and did not, nor one that sent `X-Acting-Credential` without its `X-Acting-Identity` companion) — a fault in the CALLER's configuration, not a fact about the recipient, so it must DEFER (451). A 550 here rejects every message the server sees, on a mistake an operator can fix in a minute."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unknown_address — recipient address does not resolve to an active route. Permanent: 550 5.1.1. For SYSTEM callers the body also carries `domain_hosted`; when it is false the recipient's domain was never ours, the session is a relay attempt, and the honest SMTP reply is 550 5.7.1 (relaying denied) rather than 5.1.1 — then `sender_hosted: true` additionally means the MAIL FROM domain IS hosted here, i.e. one of our own users' clients submitting to the MX instead of ports 465/587, and the MTA should say so in the reply text. Both fields are absent for account callers (the foreign-domain collapse must stay indistinguishable from a miss) and on non-core backends; an MTA must treat absence as unknown and keep 5.1.1."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"TEMPORARY, every code here. receiving_paused: the recipient's account is inside its deletion window, or the destination mailbox's receive hold is `paused` (then `policyScope: \"mailbox\"`). DEFER (451), never reject: a sending MTA queues a 4xx for days, longer than the window, so a restore (or a cleared hold) still receives what arrived meanwhile. Carries Retry-After, and this verdict is deliberately NOT cached: a restored account must stop deferring immediately. rate_limited: the recipient's tenant or a hosted destination tenant reached through an alias or forward is over its delivery admission share, or that admission check is temporarily unavailable; DEFER (451) the same way, also uncached, with a Retry-After. recently_unknown: a hosted address did not resolve moments ago, as remembered by the colo-wide RCPT cache or the directory's negative memo; DEFER (451), never reject, because it may have been created since. Retry-After is at most the seconds left before the original miss expires (within a minute), and repeat hits never extend that expiry. Only the first authoritative miss answers 404.","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure — the check could not be answered just now: storage or the recipient's directory home failed transiently, or a forward's verified-recipient policy or verdict could not be established (including an outage fallback whose old flag cannot settle an unverified target). With `submission=true`, also the SENDING account's verified-recipients verdict for this recipient (for example a recipient domain mid-removal), as /deliver/outbound answers it at DATA. Nothing about the recipient is known, so DEFER (451), never reject; carries Retry-After and is never cached.","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Check recipient deliverability","tags":["Delivery"]}},"/api/v1/deliver/outbound":{"post":{"description":"Submits a raw MIME message for outbound relay, local delivery, forwarding, or webhook execution with per-recipient fan-out. Who calls it: the platform's SMTP submission gateway (system key, submitting on the authenticated user's behalf); an account key may also call it directly to submit pre-built MIME as any sender address the account owns. For structured sending prefer POST /mailboxes/{mailboxId}/send, which builds the MIME for you; this door is for callers that already have the bytes. Lone CR and LF are normalized to CRLF before parsing or delivery; the size limit applies to the normalized message.","operationId":"post_DeliverOutbound","parameters":[{"description":"Save a copy to the sender's Sent folder","in":"query","name":"save","required":false,"schema":{"description":"Save a copy to the sender's Sent folder","enum":["true","false"],"type":"string"}},{"description":"Generate a bounce report (DSN) to the sender if relay fails permanently (default true)","in":"query","name":"bounce","required":false,"schema":{"description":"Generate a bounce report (DSN) to the sender if relay fails permanently (default true)","enum":["true","false"],"type":"string"}},{"description":"Caller transaction ID and idempotency key","in":"header","name":"x-delivery-id","required":true,"schema":{"description":"Caller transaction ID and idempotency key","minLength":1,"type":"string"}},{"description":"Sender email address (MAIL FROM)","in":"header","name":"x-envelope-from","required":true,"schema":{"description":"Sender email address (MAIL FROM)","type":"string"}},{"description":"Recipient email address (RCPT TO)","in":"header","name":"x-envelope-to","required":true,"schema":{"description":"Recipient email address (RCPT TO)","type":"string"}},{"description":"`1` from the system key: smtp-in's submission re-post of a recipient it set aside because the recipient mailbox's receive hold refused it (`policyScope: \"mailbox\"`) after another recipient of the same transaction committed. The leg is accepted and staged (202) instead of refused: a paused one is delivered once the hold clears, or reported to the sender as expired at the paced queue's deadline; a disabled one is reported at once by a delivery-status notice in the sending mailbox. Ignored from any other caller and for any other refusal.","in":"header","name":"x-accept-held","required":false,"schema":{"description":"`1` from the system key: smtp-in's submission re-post of a recipient it set aside because the recipient mailbox's receive hold refused it (`policyScope: \"mailbox\"`) after another recipient of the same transaction committed. The leg is accepted and staged (202) instead of refused: a paused one is delivered once the hold clears, or reported to the sender as expired at the paced queue's deadline; a disabled one is reported at once by a delivery-status notice in the sending mailbox. Ignored from any other caller and for any other refusal.","type":"string"}},{"description":"MTA submission hostname","in":"header","name":"x-source-host","required":false,"schema":{"description":"MTA submission hostname","type":"string"}},{"description":"JSON delivery metadata string (max 8 KB)","in":"header","name":"x-delivery-meta","required":false,"schema":{"description":"JSON delivery metadata string (max 8 KB)","type":"string"}},{"description":"MIME message size in bytes","in":"header","name":"content-length","required":true,"schema":{"description":"MIME message size in bytes","type":"string"}}],"requestBody":{"content":{"message/rfc822":{"schema":{"description":"Raw RFC 5322 MIME message bytes","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverResult"}}},"description":"Message delivered to local recipient mailbox"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverResult"}}},"description":"Message staged and queued for outbound relay or forwarding, or (with X-Accept-Held from the system key) for a local mailbox whose receive hold refused it"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"Permanent — the request is malformed and a retry cannot help: validation_failed, missing_delivery_id, invalid_envelope, invalid_save / invalid_bounce, empty_body, delivery_meta_too_large / delivery_meta_not_object / delivery_meta_invalid_json, invalid_from (missing or unparseable RFC5322 From, non-system callers), header_block_too_large (the header block runs past the 64 KB parse window, so a Bcc could not be ruled out and the message cannot safely be relayed)."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Permanent submission refusals, which the MTA answers with an in-session 550 and never retries: sender_not_owned (one indistinguishable reply for EVERY not-yours case — an anti-enumeration collapse, so the caller learns nothing about which addresses exist), sender_not_local, sending_disabled (ONE code across three scopes — this mailbox's own freeze, its domain's, or its account's; same code, same permanence, so an operator debugging a refusal checks all three), from_not_owned, from_sending_disabled (the RFC 5322 From is not the sender's to use), mailbox_gone (the sending mailbox was deleted mid-submission), recipient_not_permitted (one of the sender's own policies excludes this recipient: the outbound recipient allowlist — the identity's, or the credential's own — or the sender's outbound address lists, which a `block *@*` makes \"send to nobody but\"; the body's `source` says which, and for a list names the deciding `list` and `pattern`), recipient_not_verified (the sending account is not yet vetted, so it may send only to its verified recipients: addresses on its own domains, and outside addresses whose owners confirmed them; this recipient is neither, `source: \"verified_recipients\"`; vetting the account or the owner confirming lifts it. The same code when the recipient is a hosted address that forwards — a remote route, a pattern or catch-all whose destination is remote, or an alias pattern — for an account not yet vetted, to a target that is not one of THAT account's verified recipients: the forward's owner is judged, never the sender), sender_blocked (a LOCAL recipient's inbound address lists refuse this sender; permanent, and the recipient's list is not named), credential_scope (the credential in play — the bearer's, or the one X-Acting-Credential names — is scoped below `send`; permanent for that credential, carrying `scope` and `required`), receiving_disabled (a local recipient is not accepting mail: its domain, or the recipient mailbox's receive hold is `disabled`, then with `policyScope: \"mailbox\"`, never to be cached or gossiped), posting_denied (a members-only group refused this poster), too_many_recipients (the submission's own recipient count exceeds the sender's recipient cap — an empty window would refuse it too, so unlike the 429 rate_limited this can never clear and must bounce). **Key on the CODE, never on 403 alone**: two classes of 403 are NOT permanent and must DEFER (451). insufficient_scope / system_credentials_required say the caller's own bearer may not submit here — an operator fault, and a 550 would reject every message the server handles. account_deleted says the CALLING account is inside its deletion window, which a restore reverses (see isPermanentHold in src/db/sendhold.ts, which excludes it deliberately), so the backlog must be held rather than bounced."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_gone (the recipient's mailbox was deleted mid-flight) or unknown_address (the recipient is on a domain we host and receive for, and no route matches). Both are permanent — 550 5.1.1. A 404 carrying NO error code is something else entirely: this route was never reached and the delivery URL is missing its /api/v1/deliver/outbound path, so it must DEFER, exactly as core's own relay defers on 404/405/415 rather than bouncing on an operator typo (MTA_MISCONFIG_STATUSES in src/queues/relay.ts)."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"delivery_id_reused — this delivery ID belongs to a composed or scheduled submission, or its original retry window has expired. Use a fresh ID for a new submission."},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"length_required — Content-Length header is required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large — message exceeds maximum allowed size"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"TEMPORARY — retry, never bounce; every code carries `Retry-After`. rate_limited (the sender is over a send allowance), sending_paused (a reversible hold on the sender — non-payment, an investigation — at any of the three scopes), from_sending_paused (the same hold, found via the RFC5322 From address's domain), receiving_paused (a LOCAL recipient's account is inside its deletion window, or the recipient mailbox's receive hold is `paused`, then with `policyScope: \"mailbox\"`; the message must be retried so a restore, or a cleared hold, receives what arrived meanwhile).","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"internal_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Temporary — retry with the same delivery ID: temporary_failure (staging or infrastructure fault, a local recipient's receive policy could not be established, or a recipient's forward could not establish its verified-recipient policy or verdict, including an old unrestricted flag from an outage fallback), superseded / reaped (this attempt lost its pending intent; a keyed retry converges), staging_missing (the staged upload vanished before the recipient leg ran; a retry re-stages), submission_record_unavailable (the delivery ID's durable admission could not be read, reserved, or validated).","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Temporary — out of room, so the MTA queues. THREE codes, and the difference is the remedy: over_quota is the recipient mailbox's own quota, account_over_quota is the recipient tenant's shared storage pool (a mailbox well under its own quota can still be refused) — both are numbers an operator can raise — while store_metadata_full is the recipient store's own metadata ceiling, which no number clears: only purging messages does. A client that cannot tell them apart tells the customer the wrong remedy."}},"summary":"Submit outbound email message","tags":["Delivery"]}},"/api/v1/deliver/inbound":{"post":{"description":"Processes and delivers an inbound MIME email message to a mailbox, webhook, forwarding address, or mailing group with Sieve filter execution. Who calls it: the platform's inbound MTA at DATA time (system key, any recipient); an account key may also call it to inject mail, confined to recipients on domains the account owns. Mailbox app passwords are refused (403 insufficient_scope). Most integrations never call this: mail arrives by being sent to your address.","operationId":"post_DeliverInbound","parameters":[{"description":"Caller transaction ID and idempotency key","in":"header","name":"x-delivery-id","required":true,"schema":{"description":"Caller transaction ID and idempotency key","minLength":1,"type":"string"}},{"description":"SMTP envelope sender (MAIL FROM)","in":"header","name":"x-envelope-from","required":true,"schema":{"description":"SMTP envelope sender (MAIL FROM)","type":"string"}},{"description":"SMTP envelope recipient (RCPT TO)","in":"header","name":"x-envelope-to","required":true,"schema":{"description":"SMTP envelope recipient (RCPT TO)","type":"string"}},{"description":"MTA receiving hostname","in":"header","name":"x-source-host","required":false,"schema":{"description":"MTA receiving hostname","type":"string"}},{"description":"JSON delivery metadata string (max 8 KB)","in":"header","name":"x-delivery-meta","required":false,"schema":{"description":"JSON delivery metadata string (max 8 KB)","type":"string"}},{"description":"`1` from the system key: smtp-in's re-post of a recipient it set aside because the recipient mailbox's receive hold refused it (`policyScope: \"mailbox\"`) after another recipient of the same transaction committed. The leg is accepted and staged (202) instead of refused: a paused one is delivered once the hold clears, or reported to the sender as expired at the paced queue's deadline; a disabled one is reported to the sender at once (a delivery-status notice; none to a null reverse-path, whose leg is kept for the operator). Ignored from any other caller and for any other refusal.","in":"header","name":"x-accept-held","required":false,"schema":{"description":"`1` from the system key: smtp-in's re-post of a recipient it set aside because the recipient mailbox's receive hold refused it (`policyScope: \"mailbox\"`) after another recipient of the same transaction committed. The leg is accepted and staged (202) instead of refused: a paused one is delivered once the hold clears, or reported to the sender as expired at the paced queue's deadline; a disabled one is reported to the sender at once (a delivery-status notice; none to a null reverse-path, whose leg is kept for the operator). Ignored from any other caller and for any other refusal.","type":"string"}},{"description":"MIME message size in bytes","in":"header","name":"content-length","required":true,"schema":{"description":"MIME message size in bytes","type":"string"}}],"requestBody":{"content":{"message/rfc822":{"schema":{"description":"Raw RFC 5322 MIME message bytes","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverResult"}}},"description":"Message delivered to mailbox or processed by Sieve filter"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverResult"}}},"description":"Message staged and queued for webhook or forwarding, a paced mailbox, or (with X-Accept-Held from the system key) a mailbox whose receive hold refused it"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"Permanent — the request is malformed and a retry cannot help: validation_failed, missing_delivery_id, invalid_envelope, empty_body, delivery_meta_too_large / delivery_meta_not_object / delivery_meta_invalid_json."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Permanent per-message refusals, which the MTA answers with an in-session 550: receiving_disabled (the recipient's domain is not accepting mail, or the destination mailbox's receive hold is `disabled`: then the body carries `policyScope: \"mailbox\"`, never to be cached or gossiped), sender_blocked (an inbound address list refused this sender), posting_denied (a members-only group refused a poster who is not an authenticated member), recipient_not_verified (the address forwards — a remote route, a pattern or catch-all whose destination is remote, or an alias pattern — for an account that is not yet vetted, to a target that is not one of its verified recipients: an address on its own domains, or one whose owner confirmed it, another customer's address included; nothing is stored or relayed, and vetting the account or the owner confirming lifts it; GET /deliver/check refuses the same recipient with the same code at RCPT). **Key on the CODE, never on 403 alone**: two classes of 403 are NOT permanent and must DEFER (451). insufficient_scope / system_credentials_required say the caller's own bearer may not deliver here — a deployment fault rather than a fact about the message, and a 550 would hard-bounce every message the server sees. account_deleted says the CALLING account is inside its deletion window, which a restore reverses. Note sender_blocked depends on the ENVELOPE SENDER as well as the recipient, so it must never be cached under a recipient key alone."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unknown_address or mailbox_gone"},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"length_required — Content-Length header is required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large — message exceeds maximum allowed size"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Temporary, retry after the specified delay: receiving_paused (the recipient account is inside its deletion window, or the destination mailbox's receive hold is `paused`, then with `policyScope: \"mailbox\"`; a restore or a cleared hold receives the backlog) or rate_limited (the domain's forwarding budget is exhausted: the wire code is rate_limited; forward_rate_limited is the traffic log's detail, never the response body's error). rate_limited also answers a recipient whose tenant is over its delivery admission share, or whose admission check could not answer just now; the traffic log's detail is then admission_shed or admission_unavailable respectively. recently_unknown: the recipient did not resolve moments ago and is not asked again until that answer is a minute old (the object directory's negative memo); it may have been created since, so this DEFERS and never bounces, and Retry-After is at most the seconds left before it is asked again. Only the first miss answers 404 unknown_address.","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"internal_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure — retry with the same delivery ID. Also the answer when the destination mailbox's receive policy could not be established (its store could not confirm whether a receive hold is set): nothing was stored, and the retry decides. And when a forward's verified-recipient policy or verdict could not be established, including an outage fallback whose old flag cannot settle an unverified target: before staging for a route, so nothing was stored; after storing for a forward TAP's copy, whose retry is answered as a duplicate and owes the copy again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Temporary — out of room, so the MTA queues. THREE codes, and the difference is the remedy: over_quota is THIS mailbox's own quota, account_over_quota is the tenant's shared storage pool (a mailbox well under its quota can still be refused) — both are numbers an operator can raise — while store_metadata_full is the store's own metadata ceiling, which no number clears: only purging messages does. A client that cannot tell them apart tells the customer the wrong remedy."}},"summary":"Deliver inbound email message","tags":["Delivery"]}},"/api/v1/suppressions":{"get":{"description":"Lists deployment-global suppressions for system callers. With accountId, lists that account's complaints; account callers may select only their own account.","operationId":"get_SuppressionListEndpoint","parameters":[{"description":"Page size (default 100)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 100)","maximum":200,"minimum":1,"type":"integer"}},{"description":"Opaque page cursor from a previous response","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor from a previous response","type":"string"}},{"description":"Sending account whose complaint suppressions to inspect or modify","in":"query","name":"accountId","required":false,"schema":{"description":"Sending account whose complaint suppressions to inspect or modify","maxLength":128,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionList"}}},"description":"List of suppressed email addresses"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"insufficient_scope — mailbox credentials or a foreign account; system_credentials_required — the global listing requires system credentials"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"suppression_moving: the address's bucket is being moved; retry after the Retry-After delay. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List email suppressions","tags":["Suppressions"]}},"/api/v1/suppressions/{address}":{"get":{"description":"Inspects the global list by default; account callers see global hard bounces only. With accountId, inspects an account complaint; account callers may select only their own account.","operationId":"get_SuppressionGet","parameters":[{"description":"Recipient email address to check","in":"path","name":"address","required":true,"schema":{"description":"Recipient email address to check","type":"string"}},{"description":"Sending account whose complaint suppressions to inspect or modify","in":"query","name":"accountId","required":false,"schema":{"description":"Sending account whose complaint suppressions to inspect or modify","maxLength":128,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suppression"}}},"description":"Address suppression record"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"insufficient_scope — mailbox credentials or a foreign account; system_credentials_required — the global listing requires system credentials"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the address is not suppressed, or not visible to this caller"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"suppression_moving: the address's bucket is being moved; retry after the Retry-After delay. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get suppression status for an address","tags":["Suppressions"]},"delete":{"description":"Lifts a global suppression by default; account callers may lift global hard bounces only. With accountId, lifts that account's complaint, which requires system credentials: an account may inspect its own complaints but not lift them.","operationId":"delete_SuppressionDelete","parameters":[{"description":"Recipient email address to lift from suppression","in":"path","name":"address","required":true,"schema":{"description":"Recipient email address to lift from suppression","type":"string"}},{"description":"Sending account whose complaint suppressions to inspect or modify","in":"query","name":"accountId","required":false,"schema":{"description":"Sending account whose complaint suppressions to inspect or modify","maxLength":128,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Suppression removed successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"insufficient_scope — mailbox credentials; system_credentials_required — lifting an account complaint requires system credentials"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found — the address was not suppressed or is not liftable by this caller"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"suppression_moving: the address's bucket is being moved; retry after the Retry-After delay. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove email address from suppression list","tags":["Suppressions"]}},"/api/v1/push-subscriptions":{"post":{"description":"Registers a Web Push endpoint (from `PushManager.subscribe` in a browser or PWA, or a UnifiedPush distributor on Android) for content-free `StateChange` wakes. The subscription starts UNVERIFIED: the server immediately pushes a `PushVerification` payload (`{\"@type\":\"PushVerification\",pushSubscriptionId,verificationCode}`) to the endpoint, and nothing else is ever pushed until the device echoes the code back via `PATCH /push-subscriptions/{id}`. Re-registering an existing `deviceClientId` replaces that subscription (and resets verification: new keys mean a new handshake) rather than counting against the cap. Each pushed StateChange carries per-type state tokens usable verbatim as `since` on `GET /mailboxes/{mailboxId}/messages/changes`. Requires a mailbox app password (`oemp_…`): subscriptions belong to the credential that creates them, so account and system keys are refused with 403 `mailbox_credential_required`.","operationId":"post_PushSubscriptionCreate","requestBody":{"content":{"application/json":{"example":{"deviceClientId":"graces-pixel-openemail-app","keys":{"auth":"yLoWJcS0DcS9Zt7kQaXeYw","p256dh":"BClYgnQx1uT5rDGz0lJ0O5xkT6PZQyCkV0Zr9hFm3nS2wJc8dK2xNc0Zt7kQaXeYw4Uu0aPbvUwWqBhI5f2m1oE"},"types":["Email","EmailDelivery"],"url":"https://fcm.googleapis.com/fcm/send/dK2xNc0Zt7k:APA91bE5aC1"},"schema":{"properties":{"deviceClientId":{"description":"Client-chosen identifier for this app installation on this device. Stable across launches, so re-registration replaces rather than accumulates","maxLength":255,"minLength":1,"type":"string"},"expires":{"description":"Requested expiry in epoch seconds. The server caps it 30 days out (the cap also applies when absent); extend with PATCH before it lapses","minimum":1,"type":"integer"},"keys":{"properties":{"auth":{"description":"The device's 16-byte auth secret, base64url","minLength":1,"type":"string"},"p256dh":{"description":"The device's public key: base64url uncompressed P-256 point","minLength":1,"type":"string"}},"required":["p256dh","auth"],"type":"object"},"types":{"description":"Type names to wake this device for, or null/absent for all: Email, Mailbox, Thread, EmailDelivery, EmailSubmission, VacationResponse, plus the PIM types (Calendar, CalendarEvent, AddressBook, ContactCard, Task). Unknown names are ignored","items":{"type":"string"},"type":["array","null"]},"url":{"description":"The push service endpoint the device was handed when it subscribed. HTTPS only. Treated as a bearer capability and never returned by any read","format":"uri","type":"string"}},"required":["deviceClientId","url","keys"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"createdAt":1788260400,"deviceClientId":"graces-pixel-openemail-app","expires":1790856000,"id":"01J9PUSH4C7E1G4J8M00000000","types":["Email","EmailDelivery"],"verified":true},"schema":{"$ref":"#/components/schemas/PushSubscription"}}},"description":"Registered, verification push fired; verified stays false until the PATCH"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed (https-only url; keys.p256dh and keys.auth required)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_credential_required, or web_push_not_configured"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_many_push_subscriptions: the account already holds its cap of live subscriptions (the refusal carries `limit`). Re-registering an existing deviceClientId is exempt","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Register a push subscription","tags":["Push"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns the subscriptions registered by the CALLING credential (another app password's registrations on the same mailbox are not visible: they belong to that credential), plus `vapidPublicKey`, the applicationServerKey a client passes to `PushManager.subscribe` before POSTing the resulting endpoint here. A null `vapidPublicKey` means Web Push is not configured on this deployment and POST would refuse. Requires a mailbox app password (`oemp_…`): subscriptions belong to the credential that creates them, so account and system keys are refused with 403 `mailbox_credential_required`.","operationId":"get_PushSubscriptionList","responses":{"200":{"content":{"application/json":{"example":{"subscriptions":[{"createdAt":1788260400,"deviceClientId":"graces-pixel-openemail-app","expires":1790856000,"id":"01J9PUSH4C7E1G4J8M00000000","types":["Email","EmailDelivery"],"verified":true}],"vapidPublicKey":"BNVi6qkeqrGDbcbc6V9ZYzZ2Xv3zqZBhBiuOPyfCrKuk2fZzTBnyxbGCkyIAZ8zqYYUwbHbLcbWjrGtrqXcNvVE"},"schema":{"$ref":"#/components/schemas/PushSubscriptionPage"}}},"description":"The calling credential's subscriptions and the server's VAPID public key"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_credential_required"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List push subscriptions","tags":["Push"]}},"/api/v1/push-subscriptions/{id}":{"patch":{"description":"The two mutations a subscription supports (RFC 8620 §7.2): echoing back the `verificationCode` the handshake push delivered (which is what arms the subscription: a wrong code is refused, never silently accepted, or an unproven endpoint would start receiving state), and extending `expires` (capped 30 days out). Requires a mailbox app password (`oemp_…`): subscriptions belong to the credential that creates them, so account and system keys are refused with 403 `mailbox_credential_required`.","operationId":"patch_PushSubscriptionUpdate","parameters":[{"description":"Push subscription ULID","in":"path","name":"id","required":true,"schema":{"description":"Push subscription ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"verificationCode":"01J9MBX7F4Q2K9T3W6PUSHCODE"},"schema":{"properties":{"expires":{"description":"New expiry in epoch seconds; the server caps it 30 days out","minimum":1,"type":"integer"},"verificationCode":{"description":"The code delivered inside the PushVerification push","minLength":1,"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"createdAt":1788260400,"deviceClientId":"graces-pixel-openemail-app","expires":1790856000,"id":"01J9PUSH4C7E1G4J8M00000000","types":["Email","EmailDelivery"],"verified":true},"schema":{"$ref":"#/components/schemas/PushSubscription"}}},"description":"The subscription after the mutation"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, or invalid_verification_code"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_credential_required"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such subscription for THIS credential (another credential's ids are indistinguishable from absent), or it expired"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window. A request carrying both verificationCode and expires applies them as two writes, so its verification can already stand when the expiry is the write refused: the retry converges (a verified subscription accepts its code again, and the expiry then applies)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Verify or extend a push subscription","tags":["Push"],"x-max-json-body-bytes":1048576},"delete":{"description":"Stops pushes to this device immediately. A device that unsubscribed locally should also delete its registration; a device that merely lost its endpoint (the push service answers 404/410) is cleaned up automatically. Requires a mailbox app password (`oemp_…`): subscriptions belong to the credential that creates them, so account and system keys are refused with 403 `mailbox_credential_required`.","operationId":"delete_PushSubscriptionDelete","parameters":[{"description":"Push subscription ULID","in":"path","name":"id","required":true,"schema":{"description":"Push subscription ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResult"}}},"description":"Removed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_credential_required"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such subscription for this credential, or already expired"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete a push subscription","tags":["Push"]}},"/api/v1/identities/{identityId}/free-busy":{"get":{"description":"Busy intervals across every calendar this identity owns, inside the asked-for window. Intervals only — when, and whether the commitment is firm or tentative (RFC 5545 FBTYPE) — never event details of any kind. Readable by identities in the SAME account; refused as 404 across an account boundary.","operationId":"get_IdentityFreeBusy","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Window start, unix seconds","in":"query","name":"start","required":false,"schema":{"description":"Window start, unix seconds","type":["integer","null"]}},{"description":"Window end, unix seconds (exclusive)","in":"query","name":"end","required":false,"schema":{"description":"Window end, unix seconds (exclusive)","type":["integer","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreeBusy"}}},"description":"Busy intervals"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed: the window is missing, inverted, or too wide"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such identity, or not visible to this principal"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"window_too_large: the window holds more calendar data than one answer can carry. REFUSED rather than answered partially — an under-reported busy list is what double-books people"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Free/busy for an identity","tags":["PIM"]}},"/api/v1/identities/{identityId}/pim/free-busy":{"post":{"description":"Busy intervals for each of the given calendar-user addresses, inside one window, asked as the identity in the path. Subjects the caller may not see — and addresses that do not exist — are reported as not visible, indistinguishably.","operationId":"post_FreeBusyBatch","parameters":[{"description":"Identity ULID the question is asked AS, not asked about","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID the question is asked AS, not asked about","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"addresses":{"description":"Calendar-user addresses, with or without a mailto: prefix","items":{"type":"string"},"type":"array"},"end":{"description":"Window end, unix seconds (exclusive)","type":"integer"},"start":{"description":"Window start, unix seconds","type":"integer"}},"required":["start","end","addresses"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreeBusyBatchResult"}}},"description":"One answer per address, in the order asked"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed: the window or the subject count is out of bounds"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Identity not found, or not one this credential may ask as"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"window_too_large: refused rather than answered partially"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Free/busy for several addresses","tags":["PIM"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/scheduling-inbox":{"get":{"description":"What arrived for this identity and what became of it — applied, or refused and why. The scheduling Inbox RFC 6638 clients read. Owner-only.","operationId":"get_SchedulingInbox","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Page size, default and max 200","in":"query","name":"limit","required":false,"schema":{"description":"Page size, default and max 200","type":["integer","null"]}},{"description":"`true` lists only the Inbox members: held messages the client has not yet DELETEd","in":"query","name":"pending","required":false,"schema":{"description":"`true` lists only the Inbox members: held messages the client has not yet DELETEd","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingInboxPage"}}},"description":"Arrivals, newest first"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Identity not found, or not this principal's"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List arriving scheduling messages","tags":["PIM"]}},"/api/v1/identities/{identityId}/scheduling-inbox/{entryId}":{"get":{"description":"The scheduling message an Inbox entry holds — METHOD and all — as text/calendar. Owner-only. 404 once the entry has been consumed.","operationId":"get_SchedulingInboxEntry","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Inbox entry ULID, from the listing","in":"path","name":"entryId","required":true,"schema":{"description":"Inbox entry ULID, from the listing","type":"string"}}],"responses":{"200":{"content":{"text/calendar":{"schema":{"type":"string"}}},"description":"The iTIP message"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such pending entry, or not this principal's identity"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Read one scheduling Inbox entry","tags":["PIM"]},"delete":{"description":"Acknowledges one Inbox entry: its message is dropped and it leaves the pending listing. The audit row stays. Owner-only. 404 when nothing is pending under that id.","operationId":"delete_SchedulingInboxConsume","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Inbox entry ULID, from the listing","in":"path","name":"entryId","required":true,"schema":{"description":"Inbox entry ULID, from the listing","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"consumed":{"enum":[true],"type":"boolean"}},"required":["consumed"],"type":"object"}}},"description":"Consumed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such pending entry, or not this principal's identity"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Consume a scheduling Inbox entry","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars":{"post":{"description":"Creates a new calendar collection for a mailbox.","operationId":"post_CalendarCreate","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"color":{"maxLength":32,"type":"string"},"components":{"description":"Nonempty set of supported calendar primary components. Omitted on create means both VEVENT and VTODO; omitted on patch leaves the set unchanged.","items":{"enum":["VEVENT","VTODO"],"type":"string"},"maxItems":2,"minItems":1,"type":"array"},"description":{"maxLength":1024,"type":"string"},"descriptionLang":{"maxLength":64,"type":["string","null"]},"displayName":{"maxLength":256,"type":"string"},"name":{"description":"URL slug: letters, digits, and . _ ~ - (the DAV path segment)","maxLength":64,"minLength":1,"type":"string"},"role":{"maxLength":32,"type":["string","null"]},"visibility":{"description":"Access visibility scope","enum":["private","shared","public"],"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimCollection"}}},"description":"Collection created successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_name, or invalid_components"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"name_taken, or too_many_collections (max 10)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create calendar","tags":["PIM"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns all calendars for a mailbox with their sync tokens.","operationId":"get_CalendarList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"calendars":{"items":{"$ref":"#/components/schemas/PimCollection"},"type":"array"}},"required":["calendars"],"type":"object"}}},"description":"List of collections and sync tokens"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List calendars","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}":{"get":{"description":"Returns collection details and sync token for a calendar by its ID.","operationId":"get_CalendarGet","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimCollection"}}},"description":"Collection details and current sync token"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get calendar by ID","tags":["PIM"]},"patch":{"description":"Updates properties (name, color, description, visibility) for a calendar collection.","operationId":"patch_CalendarUpdate","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"color":{"maxLength":32,"type":["string","null"]},"components":{"description":"Nonempty set of supported calendar primary components. Omitted on create means both VEVENT and VTODO; omitted on patch leaves the set unchanged.","items":{"enum":["VEVENT","VTODO"],"type":"string"},"maxItems":2,"minItems":1,"type":"array"},"description":{"maxLength":1024,"type":["string","null"]},"descriptionLang":{"maxLength":64,"type":["string","null"]},"displayName":{"maxLength":256,"type":["string","null"]},"expectedVisibility":{"description":"Access visibility scope","enum":["private","shared","public"],"type":"string"},"name":{"maxLength":64,"minLength":1,"type":"string"},"role":{"maxLength":32,"type":["string","null"]},"scheduleTransp":{"enum":["opaque","transparent"],"type":["string","null"]},"visibility":{"description":"Access visibility scope","enum":["private","shared","public"],"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimCollection"}}},"description":"Updated collection details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_name, or invalid_components"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"name_taken; visibility_conflict (CAS lost); or components_conflict with count of incompatible live and restorable trashed objects. No properties change on refusal."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update calendar","tags":["PIM"],"x-max-json-body-bytes":1048576},"delete":{"description":"Deletes a calendar collection and all objects stored within it. Both move to the trash tier: GET …/calendars/trash lists them, POST …/trash/{id}/restore brings the collection and its members back (private, since grants and feed tokens were retired), and the purge duty removes them for good fourteen days after deletion.","operationId":"delete_CalendarDelete","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"Send iTIP scheduling messages for this write: 'true' cancels as organizer or declines as attendee, 'false' sends nothing. Absent keeps the default — organizers schedule, attendees stay silent.","in":"query","name":"notify","required":false,"schema":{"description":"Send iTIP scheduling messages for this write: 'true' cancels as organizer or declines as attendee, 'false' sends nothing. Absent keeps the default — organizers schedule, attendees stay silent.","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"boolean"},"objectsDestroyed":{"type":"integer"}},"required":["deleted","objectsDestroyed"],"type":"object"}}},"description":"Deleted; objectsDestroyed counts the members that went with it"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"default_collection — default collection cannot be deleted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_unavailable: preparation could not complete; no deletion committed. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_backlog_full: pending-work or batch budget exhausted; no deletion committed"}},"summary":"Delete calendar","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/by-name/{name}":{"get":{"description":"Returns collection details and sync token for a calendar by its URL name slug.","operationId":"get_CalendarGetByName","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"The collection's name slug (exact match)","in":"path","name":"name","required":true,"schema":{"description":"The collection's name slug (exact match)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimCollection"}}},"description":"Collection details and current sync token"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No collection by that name, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get calendar by name","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/objects":{"get":{"description":"Returns a paginated list of calendar objects, optionally filtered by time range and expanded for recurring events.","operationId":"get_CalendarObjectList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"Page size (default 500)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 500)","maximum":5000,"minimum":1,"type":"integer"}},{"description":"Pagination cursor from previous page","in":"query","name":"cursor","required":false,"schema":{"description":"Pagination cursor from previous page","type":"string"}},{"description":"Sort order by creation time ('asc' or 'desc')","in":"query","name":"order","required":false,"schema":{"description":"Sort order by creation time ('asc' or 'desc')","enum":["asc","desc"],"type":"string"}},{"description":"Fields to include: 'meta' (headers/timestamps only), 'full' (raw text body), 'json' (parsed JSCalendar/JSContact JSON)","in":"query","name":"fields","required":false,"schema":{"description":"Fields to include: 'meta' (headers/timestamps only), 'full' (raw text body), 'json' (parsed JSCalendar/JSContact JSON)","enum":["meta","full","json"],"type":"string"}},{"description":"Filter by exact UID","in":"query","name":"uid","required":false,"schema":{"description":"Filter by exact UID","type":"string"}},{"description":"Window start (epoch seconds)","in":"query","name":"start","required":false,"schema":{"description":"Window start (epoch seconds)","type":["integer","null"]}},{"description":"Window end (epoch seconds)","in":"query","name":"end","required":false,"schema":{"description":"Window end (epoch seconds)","type":["integer","null"]}},{"description":"Component type filter","in":"query","name":"component","required":false,"schema":{"description":"Component type filter","enum":["VEVENT","VTODO","VJOURNAL"],"type":"string"}},{"description":"Expand recurring events into instances","in":"query","name":"expand","required":false,"schema":{"description":"Expand recurring events into instances","enum":["true","false"],"type":"string"}},{"description":"With expand=true: give each instance its RFC 5545 FBTYPE (`fbType`), decided as RFC 4791 §7.10's table and the OWNER's own PARTSTAT decide it. Opt-in because it costs a read of the owner's addresses, which only a free-busy caller needs","in":"query","name":"fbtype","required":false,"schema":{"description":"With expand=true: give each instance its RFC 5545 FBTYPE (`fbType`), decided as RFC 4791 §7.10's table and the OWNER's own PARTSTAT decide it. Opt-in because it costs a read of the owner's addresses, which only a free-busy caller needs","enum":["true","false"],"type":"string"}},{"description":"Task completion filter (VTODO only, and narrows to VTODO on its own). 'active' (not completed or cancelled) and 'closed' (completed or cancelled) are exact complements, so a working list and an archive between them lose no task; the rest are JSTask's own progress values. An absent or unrecognized STATUS counts as needs-action, per RFC 5545","in":"query","name":"progress","required":false,"schema":{"description":"Task completion filter (VTODO only, and narrows to VTODO on its own). 'active' (not completed or cancelled) and 'closed' (completed or cancelled) are exact complements, so a working list and an archive between them lose no task; the rest are JSTask's own progress values. An absent or unrecognized STATUS counts as needs-action, per RFC 5545","enum":["active","closed","needs-action","in-process","completed","cancelled"],"type":"string"}},{"description":"Case-insensitive substring over each event's summary and location","in":"query","name":"q","required":false,"schema":{"description":"Case-insensitive substring over each event's summary and location","minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimObjectPage"}}},"description":"Page of collection objects"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"expand_requires_range, search_term_too_long, or progress_requires_vtodo (progress is a task filter and cannot be combined with a non-VTODO component)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List calendar objects","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/objects/{href}":{"put":{"description":"Creates or updates a calendar object from raw text/calendar text or JSCalendar JSON (RFC 8984).","operationId":"put_CalendarObjectPut","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","in":"path","name":"href","required":true,"schema":{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","maxLength":512,"minLength":1,"type":"string"}},{"description":"Send iTIP scheduling messages for this write: 'true' cancels as organizer or declines as attendee, 'false' sends nothing. Absent keeps the default — organizers schedule, attendees stay silent.","in":"query","name":"notify","required":false,"schema":{"description":"Send iTIP scheduling messages for this write: 'true' cancels as organizer or declines as attendee, 'false' sends nothing. Absent keeps the default — organizers schedule, attendees stay silent.","enum":["true","false"],"type":"string"}},{"description":"Match target ETag for optimistic concurrency","in":"header","name":"if-match","required":false,"schema":{"description":"Match target ETag for optimistic concurrency","type":"string"}},{"description":"RFC 6638 §3.2.10.1 — match the target's Schedule-Tag. Unlike the ETag this does not move when an arriving REPLY patches PARTSTAT into the stored copy, so an organizer's client can still write conditionally after its attendees answer. Sent together with If-Match, BOTH must validate","in":"header","name":"if-schedule-tag-match","required":false,"schema":{"description":"RFC 6638 §3.2.10.1 — match the target's Schedule-Tag. Unlike the ETag this does not move when an arriving REPLY patches PARTSTAT into the stored copy, so an organizer's client can still write conditionally after its attendees answer. Sent together with If-Match, BOTH must validate","type":"string"}},{"description":"Set to '*' to only create if resource does not exist","in":"header","name":"if-none-match","required":false,"schema":{"description":"Set to '*' to only create if resource does not exist","type":"string"}}],"requestBody":{"content":{"text/calendar":{"schema":{"description":"Raw iCalendar or vCard text","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimPutResult"}}},"description":"Object replaced successfully"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimPutResult"}}},"description":"Object created successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"empty_body, invalid_href, multiple_uids, unsatisfiable_recurrence (an RRULE no date after DTSTART satisfies), or validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"forbidden: read-only grant"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"uid_conflict: the href holds a different UID, or the UID already lives at another href (conflictHref names it); unsupported_component: the calendar does not accept the object's component"},"412":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"precondition_failed: If-Match/If-None-Match not satisfied"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"object_too_large (max 1048576 bytes)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_unavailable: preparation could not complete; no mutation committed. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_backlog_full, too_many_objects (collection or store object cap) or store_full (the store's 268435456-byte total would be exceeded)"}},"summary":"Create or replace calendar object","tags":["PIM"]},"get":{"description":"Returns a calendar object in raw text/calendar format, or as JSCalendar JSON (RFC 8984) when requested with Accept: application/json.","operationId":"get_CalendarObjectGet","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","in":"path","name":"href","required":true,"schema":{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","maxLength":512,"minLength":1,"type":"string"}},{"description":"Look up object by UID instead of href slug","in":"query","name":"uid","required":false,"schema":{"description":"Look up object by UID instead of href slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimObjectJson"}},"text/calendar":{"schema":{"type":"string"}}},"description":"Stored object body and metadata"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such object, collection, or mailbox"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get calendar object","tags":["PIM"]},"delete":{"description":"Deletes a calendar object by its href slug or UID. The object moves to the collection's trash (GET …/trash lists it, POST …/trash/{objectId}/restore brings it back) and is purged for good fourteen days later.","operationId":"delete_CalendarObjectDelete","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","in":"path","name":"href","required":true,"schema":{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","maxLength":512,"minLength":1,"type":"string"}},{"description":"Match by UID instead of href","in":"query","name":"uid","required":false,"schema":{"description":"Match by UID instead of href","type":"string"}},{"description":"Send iTIP scheduling messages for this write: 'true' cancels as organizer or declines as attendee, 'false' sends nothing. Absent keeps the default — organizers schedule, attendees stay silent.","in":"query","name":"notify","required":false,"schema":{"description":"Send iTIP scheduling messages for this write: 'true' cancels as organizer or declines as attendee, 'false' sends nothing. Absent keeps the default — organizers schedule, attendees stay silent.","enum":["true","false"],"type":"string"}},{"description":"Target ETag validator","in":"header","name":"if-match","required":false,"schema":{"description":"Target ETag validator","type":"string"}},{"description":"RFC 6638 §3.2.10.1 Schedule-Tag validator; validated independently of If-Match","in":"header","name":"if-schedule-tag-match","required":false,"schema":{"description":"RFC 6638 §3.2.10.1 Schedule-Tag validator; validated independently of If-Match","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"boolean"},"href":{"type":"string"},"id":{"type":"string"},"syncToken":{"type":"string"},"uid":{"type":"string"}},"required":["deleted","id","href","uid","syncToken"],"type":"object"}}},"description":"Object deleted successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"forbidden: read-only grant"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such object, collection, or mailbox"},"412":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"precondition_failed: If-Match not satisfied"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_unavailable: preparation could not complete; no deletion committed. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_backlog_full: scheduling admission budget exhausted; no deletion committed"}},"summary":"Delete calendar object","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/objects/{href}/move":{"post":{"description":"Moves a calendar object to another collection, renames its href slug, or both. Optional overwrite validates the destination and replaces an unscheduled occupant atomically; the replaced object remains recoverable in trash.","operationId":"post_CalendarObjectMove","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","in":"path","name":"href","required":true,"schema":{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","maxLength":512,"minLength":1,"type":"string"}},{"description":"Target ETag validator","in":"header","name":"if-match","required":false,"schema":{"description":"Target ETag validator","type":"string"}},{"description":"RFC 6638 schedule-tag validator; 412 on a mismatch","in":"header","name":"if-schedule-tag-match","required":false,"schema":{"description":"RFC 6638 schedule-tag validator; 412 on a mismatch","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"overwrite":{"description":"Replace an existing destination atomically (default false); scheduled calendar occupants cannot be replaced","type":"boolean"},"to":{"description":"New resource href slug","maxLength":512,"minLength":1,"type":"string"},"toCalendarId":{"description":"Destination collection ULID or name slug","type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"collectionId":{"description":"Where the object now lives","type":"string"},"etag":{"type":"string"},"id":{"type":"string"},"overwritten":{"description":"Whether an existing destination object was replaced","type":"boolean"},"scheduleTag":{"description":"RFC 6638 schedule-tag of the object at its new href","type":"string"},"syncToken":{"type":"string"}},"required":["id","etag","scheduleTag","syncToken","collectionId","overwritten"],"type":"object"}}},"description":"Object moved or renamed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"invalid_href, or neither to nor destination was supplied"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"forbidden — read-only grant on source or destination"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such object, source collection, destination collection, or mailbox"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"href_taken, uid_conflict, wrong_kind, unsupported_component, or scheduled_overwrite: a scheduled calendar destination cannot be replaced"},"412":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"precondition_failed: If-Match not satisfied"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Move or rename calendar object","tags":["PIM"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/calendars/{calendarId}/objects/{href}/respond":{"post":{"description":"Records an attendee's participation status (ACCEPTED, DECLINED, TENTATIVE) and notifies the meeting organizer via direct update or iTIP reply message.","operationId":"post_CalendarObjectRespond","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"Resource href slug","in":"path","name":"href","required":true,"schema":{"description":"Resource href slug","maxLength":512,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"partstat":{"description":"RFC 5545 PARTSTAT to record for the caller","enum":["ACCEPTED","DECLINED","TENTATIVE","NEEDS-ACTION"],"type":"string"}},"required":["partstat"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"etag":{"type":"string"},"organizerUpdated":{"type":"boolean"},"partstat":{"enum":["ACCEPTED","DECLINED","TENTATIVE","NEEDS-ACTION"],"type":"string"},"refusal":{"description":"Present when the answer was recorded but the organizer could not be told: a sharee answered on the calendar owner's behalf and the organizer is remote, so a reply would have been sent as the owner. The RSVP itself succeeded.","enum":["delegate"],"type":"string"},"replySent":{"type":"boolean"}},"required":["partstat","etag","organizerUpdated","replySent"],"type":"object"}}},"description":"RSVP recorded successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_attendee: the caller is not on this event"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such object, collection, or mailbox"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"conflict: the copy changed concurrently under the reply; retry"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"RSVP to calendar invitation","tags":["PIM"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/calendars/{calendarId}/objects/{href}/scheduling":{"get":{"description":"Every invitation, update, cancellation and reply this identity sent for the event, and what became of each delivery: delivered, sent, being retried, refused, rejected by the remote server, or never sent and why. Owner-only.","operationId":"get_CalendarObjectScheduling","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","in":"path","name":"href","required":true,"schema":{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","maxLength":512,"minLength":1,"type":"string"}},{"description":"Rows, the latest ones (default and max 500)","in":"query","name":"limit","required":false,"schema":{"description":"Rows, the latest ones (default and max 500)","maximum":500,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectSchedulingLog"}}},"description":"The event's outbound scheduling record, oldest first"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such object, collection, or mailbox, or not this principal's own"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List what was sent for one event","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/trash":{"get":{"description":"The objects deleted out of this calendar within the last fourteen days, newest first, metadata only (a restore is how the body comes back). Owner only.","operationId":"get_CalendarObjectTrashList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Live collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Live collection ULID or its name slug","type":"string"}},{"description":"Page size (default 200)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 200)","maximum":1000,"minimum":1,"type":"integer"}},{"description":"nextCursor from the previous page","in":"query","name":"cursor","required":false,"schema":{"description":"nextCursor from the previous page","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimTrashedObjectPage"}}},"description":"Deleted objects, newest deletion first"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"invalid_cursor"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such live collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List deleted calendar objects","tags":["PIM"]},"delete":{"description":"Removes every deleted object of this calendar from the trash for good. Irreversible. Owner only, full scope.","operationId":"delete_CalendarObjectTrashEmpty","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Live collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Live collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimTrashPurged"}}},"description":"Emptied; objectsPurged counts what went"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such live collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Empty calendar trash","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/trash/{objectId}/restore":{"post":{"description":"Brings a deleted object back into this calendar under its own id, href and UID, byte-identical. For a meeting this mailbox organizes, the body's SEQUENCE is then advanced by one and a fresh REQUEST is sent to its attendees (the delete sent them a CANCEL), unless notify=false; an attendee's copy is restored locally and nothing is sent. Owner only, write scope.","operationId":"post_CalendarObjectTrashRestore","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Live collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Live collection ULID or its name slug","type":"string"}},{"description":"The trashed object's ULID (the id it had while live)","in":"path","name":"objectId","required":true,"schema":{"description":"The trashed object's ULID (the id it had while live)","type":"string"}},{"description":"Send iTIP scheduling messages for this write: 'true' cancels as organizer or declines as attendee, 'false' sends nothing. Absent keeps the default — organizers schedule, attendees stay silent.","in":"query","name":"notify","required":false,"schema":{"description":"Send iTIP scheduling messages for this write: 'true' cancels as organizer or declines as attendee, 'false' sends nothing. Absent keeps the default — organizers schedule, attendees stay silent.","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimObjectRestored"}}},"description":"Restored"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such deleted object in this collection, no such live collection, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"href_taken: a live object holds the deleted one's href; uid_conflict: a live object holds its UID (conflictHref names it); unsupported_component: the calendar no longer accepts the deleted object's component"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_unavailable: preparation could not complete; nothing restored. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_backlog_full or too_many_objects: the scheduling or object cap; nothing restored"}},"summary":"Restore deleted calendar object","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/trash/{objectId}":{"delete":{"description":"Removes one deleted object from the trash for good. Irreversible. Owner only, full scope.","operationId":"delete_CalendarObjectTrashPurge","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Live collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Live collection ULID or its name slug","type":"string"}},{"description":"The trashed object's ULID (the id it had while live)","in":"path","name":"objectId","required":true,"schema":{"description":"The trashed object's ULID (the id it had while live)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimTrashPurged"}}},"description":"Purged"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such deleted object in this collection, no such live collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Purge deleted calendar object","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/changes":{"get":{"description":"Returns added, updated, and deleted object delta changes since a previous sync token (RFC 6578 sync-collection).","operationId":"get_CalendarChanges","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"Sync token from previous response (omit for initial sync)","in":"query","name":"since","required":false,"schema":{"description":"Sync token from previous response (omit for initial sync)","type":"string"}},{"description":"Maximum changes to return","in":"query","name":"limit","required":false,"schema":{"description":"Maximum changes to return","maximum":500,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimChanges"}}},"description":"Delta changes, updated sync token, and more-remaining flag"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_sync_token — token expired or invalid; full resync required"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Sync changes for calendar","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/import":{"post":{"description":"Imports multiple calendar items in bulk from a text/calendar file (iCalendar .ics or vCard .vcf).","operationId":"post_CalendarImport","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"requestBody":{"content":{"text/calendar":{"schema":{"description":"iCalendar file contents (.ics) with one or more VEVENT components","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimImportResult"}}},"description":"All items imported successfully"},"207":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimImportResult"}}},"description":"Multi-status: some items succeeded while others failed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"empty_body, not_calendar, or empty_import"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"forbidden: read-only grant"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"import_too_large (max 16777216 bytes) or too_many_items (max 500 items)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Import calendar data","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/export":{"get":{"description":"Exports the entire calendar collection as a single iCalendar (.ics) text stream.","operationId":"get_CalendarExport","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"text/calendar":{"schema":{"type":"string"}}},"description":"Merged file contents ready to save or import"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Export whole calendar","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/shares/{shareeIdentityId}":{"put":{"description":"Grants read or write access to a mailbox for a calendar collection.","operationId":"put_CalendarSharePut","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The grantee's mailbox identity ULID","in":"path","name":"shareeIdentityId","required":true,"schema":{"description":"The grantee's mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"permission":{"description":"Permission level ('read' or 'write')","enum":["read","read-write"],"type":"string"}},"required":["permission"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimShare"}}},"description":"Access grant created or updated"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, sharee, or mailbox"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Grant calendar access","tags":["PIM"],"x-max-json-body-bytes":1048576},"delete":{"description":"Revokes a mailbox's access grant to a calendar collection.","operationId":"delete_CalendarShareDelete","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The grantee's mailbox identity ULID","in":"path","name":"shareeIdentityId","required":true,"schema":{"description":"The grantee's mailbox identity ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"type":"object"}}},"description":"Access grant revoked successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such grant, collection, or mailbox"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Revoke calendar access","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/shares":{"get":{"description":"Returns access grants configured on a calendar collection.","operationId":"get_CalendarShareList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"shares":{"items":{"$ref":"#/components/schemas/PimShare"},"type":"array"}},"required":["shares"],"type":"object"}}},"description":"List of access grants"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List calendar access grants","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/tokens":{"post":{"description":"Generates a secret read-only feed token URL for syncing a calendar in external apps (webcal/.ics/.vcf).","operationId":"post_CalendarTokenCreate","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"expiresAt":{"description":"Unix expiration timestamp in seconds (omit for never)","type":"integer"},"label":{"description":"Human-readable token description (e.g. 'Apple Calendar')","maxLength":128,"type":"string"}},"type":"object"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimTokenCreated"}}},"description":"Feed token created successfully (token and URL are shown once)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create calendar feed token","tags":["PIM"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns active read-only subscription tokens for a calendar collection.","operationId":"get_CalendarTokenList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"tokens":{"items":{"$ref":"#/components/schemas/PimToken"},"type":"array"}},"required":["tokens"],"type":"object"}}},"description":"List of feed tokens"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List calendar feed tokens","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/{calendarId}/tokens/{tokenId}":{"delete":{"description":"Revokes a read-only feed token for a calendar collection.","operationId":"delete_CalendarTokenRevoke","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"calendarId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"Feed token ULID identifier","in":"path","name":"tokenId","required":true,"schema":{"description":"Feed token ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"type":"object"}}},"description":"Feed token revoked successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such token, collection, or mailbox"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Revoke calendar feed token","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/trash":{"get":{"description":"The calendars this mailbox deleted within the last fourteen days, newest first, each with the count of members that went with it. Owner only.","operationId":"get_CalendarTrashList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"calendars":{"items":{"$ref":"#/components/schemas/PimTrashedCollection"},"type":"array"}},"required":["calendars"],"type":"object"}}},"description":"Deleted collections, newest deletion first"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: mailbox not found, or not this principal's to administer"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List deleted calendars","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/trash/{trashedCalendarId}/restore":{"post":{"description":"Brings a deleted calendar back under its own id, with exactly the members that were deleted with it (members deleted individually beforehand stay in the trash, restorable once the collection is live). It comes back private: grants, feed tokens and any public listing were retired when it was deleted. For a calendar, each restored meeting this mailbox organizes is re-sent to its attendees as a REQUEST with SEQUENCE advanced by one, off the response path, unless notify=false. Owner only, write scope.","operationId":"post_CalendarTrashRestore","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"The trashed collection's ULID (the id it had while live)","in":"path","name":"trashedCalendarId","required":true,"schema":{"description":"The trashed collection's ULID (the id it had while live)","type":"string"}},{"description":"Send iTIP scheduling messages for this write: 'true' cancels as organizer or declines as attendee, 'false' sends nothing. Absent keeps the default — organizers schedule, attendees stay silent.","in":"query","name":"notify","required":false,"schema":{"description":"Send iTIP scheduling messages for this write: 'true' cancels as organizer or declines as attendee, 'false' sends nothing. Absent keeps the default — organizers schedule, attendees stay silent.","enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimCollectionRestored"}}},"description":"Restored; the live collection and what came back with it"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such deleted collection of this kind, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"name_taken: a live collection of this kind now holds the deleted one's name; rename it first"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_unavailable: preparation could not complete; nothing restored. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_backlog_full, too_many_collections, or too_many_objects: the restore would exceed the admission budget"}},"summary":"Restore deleted calendar","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/trash/{trashedCalendarId}":{"delete":{"description":"Removes a deleted calendar from the trash for good, with every trashed object that belonged to it. Irreversible. Owner only, full scope.","operationId":"delete_CalendarTrashPurge","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"The trashed collection's ULID (the id it had while live)","in":"path","name":"trashedCalendarId","required":true,"schema":{"description":"The trashed collection's ULID (the id it had while live)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimTrashPurged"}}},"description":"Purged"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such deleted collection of this kind, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Purge deleted calendar","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/invitations":{"get":{"description":"Checks whether an event with a specific iCalendar UID is already filed across any of the mailbox's calendars and returns the user's current RSVP response.","operationId":"get_PimInvitationStatusRoute","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"iCalendar event UID","in":"query","name":"uid","required":true,"schema":{"description":"iCalendar event UID","maxLength":512,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimInvitationStatus"}}},"description":"Invitation status and current RSVP response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Check invitation status by UID","tags":["PIM"]}},"/api/v1/identities/{identityId}/calendars/invitations/respond":{"post":{"description":"Files an emailed calendar invitation to the default calendar and submits the user's RSVP response (ACCEPT, DECLINE, TENTATIVE) to the organizer.","operationId":"post_PimInvitationRespond","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ics":{"description":"Inline form: the raw text/calendar part from the message","maxLength":262144,"minLength":1,"type":"string"},"messageId":{"description":"Reference form: a message in THIS mailbox carrying the invitation","maxLength":64,"minLength":1,"type":"string"},"partstat":{"description":"RFC 5545 PARTSTAT to record for the caller","enum":["ACCEPTED","DECLINED","TENTATIVE","NEEDS-ACTION"],"type":"string"},"section":{"description":"Reference form, optional: the part's section as reported by …/messages/{id}/invitation. Omitted, the server picks the message's scheduling part itself","maxLength":64,"pattern":"^[0-9]+(\\.[0-9]+)*$","type":"string"}},"required":["partstat"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimRsvpResult"}}},"description":"Recorded. `filed` says whether a copy had to be created; `organizerUpdated` / `replySent` report how the organizer was told, exactly as the collection-scoped RSVP does"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"invalid_invitation (the body is not a parseable VEVENT) or multiple_uids (a scheduling message carries one event; overrides share its UID)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_attendee (no address of this mailbox is on the event) or is_organizer (the event names this mailbox as ORGANIZER — on ANY routing tier, not just its literal identities — an organizer answers by editing their own copy, and filing it here would schedule invitations on their behalf)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found, it has no calendar to file into, or — on the messageId form — the message is unknown (`not_found`) or carries no scheduling part (`no_invitation`)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"conflict — the copy changed concurrently under the reply; retry"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"messageId form: message_too_large | invitation_too_large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"messageId form: unparseable_message | message_too_complex"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Accept or decline emailed invitation","tags":["PIM"],"x-max-json-body-bytes":2097152}},"/api/v1/mailboxes/{mailboxId}/messages/{messageId}/invitation":{"get":{"description":"Extracts and parses the iCalendar (.ics) meeting invitation from an email message with filing status and RSVP options.","operationId":"get_MessageInvitationRoute","parameters":[{"description":"Mailbox ULID identifier","in":"path","name":"mailboxId","required":true,"schema":{"description":"Mailbox ULID identifier","type":"string"}},{"description":"Message ULID identifier","in":"path","name":"messageId","required":true,"schema":{"description":"Message ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageInvitation"}}},"description":"Parsed meeting invitation details and RSVP options"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found or no_invitation (message has no calendar invitation part)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"message_too_large or invitation_too_large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unparseable_message"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"blob_missing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get invitation from email message","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks":{"post":{"description":"Creates a new addressbook collection for a mailbox.","operationId":"post_AddressbookCreate","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"color":{"maxLength":32,"type":"string"},"description":{"maxLength":1024,"type":"string"},"descriptionLang":{"maxLength":64,"type":["string","null"]},"displayName":{"maxLength":256,"type":"string"},"name":{"description":"URL slug: letters, digits, and . _ ~ - (the DAV path segment)","maxLength":64,"minLength":1,"type":"string"},"role":{"maxLength":32,"type":["string","null"]},"visibility":{"description":"Access visibility scope","enum":["private","shared","public"],"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimCollection"}}},"description":"Collection created successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_name, or invalid_components"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"name_taken, or too_many_collections (max 10)"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create addressbook","tags":["PIM"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns all addressbooks for a mailbox with their sync tokens.","operationId":"get_AddressbookList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"addressbooks":{"items":{"$ref":"#/components/schemas/PimCollection"},"type":"array"}},"required":["addressbooks"],"type":"object"}}},"description":"List of collections and sync tokens"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List addressbooks","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}":{"get":{"description":"Returns collection details and sync token for a addressbook by its ID.","operationId":"get_AddressbookGet","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimCollection"}}},"description":"Collection details and current sync token"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get addressbook by ID","tags":["PIM"]},"patch":{"description":"Updates properties (name, color, description, visibility) for a addressbook collection.","operationId":"patch_AddressbookUpdate","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"color":{"maxLength":32,"type":["string","null"]},"description":{"maxLength":1024,"type":["string","null"]},"descriptionLang":{"maxLength":64,"type":["string","null"]},"displayName":{"maxLength":256,"type":["string","null"]},"expectedVisibility":{"description":"Access visibility scope","enum":["private","shared","public"],"type":"string"},"name":{"maxLength":64,"minLength":1,"type":"string"},"role":{"maxLength":32,"type":["string","null"]},"visibility":{"description":"Access visibility scope","enum":["private","shared","public"],"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimCollection"}}},"description":"Updated collection details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"validation_failed, invalid_name, or invalid_components"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"name_taken; visibility_conflict (CAS lost); or components_conflict with count of incompatible live and restorable trashed objects. No properties change on refusal."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update addressbook","tags":["PIM"],"x-max-json-body-bytes":1048576},"delete":{"description":"Deletes a addressbook collection and all objects stored within it. Both move to the trash tier: GET …/addressbooks/trash lists them, POST …/trash/{id}/restore brings the collection and its members back (private, since grants and feed tokens were retired), and the purge duty removes them for good fourteen days after deletion.","operationId":"delete_AddressbookDelete","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"boolean"},"objectsDestroyed":{"type":"integer"}},"required":["deleted","objectsDestroyed"],"type":"object"}}},"description":"Deleted; objectsDestroyed counts the members that went with it"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"default_collection — default collection cannot be deleted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_unavailable: preparation could not complete; no deletion committed. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_backlog_full: pending-work or batch budget exhausted; no deletion committed"}},"summary":"Delete addressbook","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/by-name/{name}":{"get":{"description":"Returns collection details and sync token for a addressbook by its URL name slug.","operationId":"get_AddressbookGetByName","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"The collection's name slug (exact match)","in":"path","name":"name","required":true,"schema":{"description":"The collection's name slug (exact match)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimCollection"}}},"description":"Collection details and current sync token"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No collection by that name, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get addressbook by name","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/objects":{"get":{"description":"Returns a paginated list of contacts in an addressbook collection.","operationId":"get_AddressbookObjectList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"Page size (default 500)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 500)","maximum":5000,"minimum":1,"type":"integer"}},{"description":"Pagination cursor from previous page","in":"query","name":"cursor","required":false,"schema":{"description":"Pagination cursor from previous page","type":"string"}},{"description":"Sort order by creation time ('asc' or 'desc')","in":"query","name":"order","required":false,"schema":{"description":"Sort order by creation time ('asc' or 'desc')","enum":["asc","desc"],"type":"string"}},{"description":"Fields to include: 'meta' (headers/timestamps only), 'full' (raw text body), 'json' (parsed JSCalendar/JSContact JSON)","in":"query","name":"fields","required":false,"schema":{"description":"Fields to include: 'meta' (headers/timestamps only), 'full' (raw text body), 'json' (parsed JSCalendar/JSContact JSON)","enum":["meta","full","json"],"type":"string"}},{"description":"Filter by exact UID","in":"query","name":"uid","required":false,"schema":{"description":"Filter by exact UID","type":"string"}},{"description":"Case-insensitive substring over name, email and structured name","in":"query","name":"q","required":false,"schema":{"description":"Case-insensitive substring over name, email and structured name","minLength":1,"type":"string"}},{"description":"Case-insensitive substring over formatted name","in":"query","name":"name","required":false,"schema":{"description":"Case-insensitive substring over formatted name","minLength":1,"type":"string"}},{"description":"Case-insensitive substring over email addresses","in":"query","name":"email","required":false,"schema":{"description":"Case-insensitive substring over email addresses","minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimObjectPage"}}},"description":"Page of collection objects"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"expand_requires_range, search_term_too_long, or progress_requires_vtodo (progress is a task filter and cannot be combined with a non-VTODO component)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List addressbook objects","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/objects/{href}":{"put":{"description":"Creates or updates a addressbook object from raw text/vcard text or JSContact JSON (RFC 9553).","operationId":"put_AddressbookObjectPut","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","in":"path","name":"href","required":true,"schema":{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","maxLength":512,"minLength":1,"type":"string"}},{"description":"Match target ETag for optimistic concurrency","in":"header","name":"if-match","required":false,"schema":{"description":"Match target ETag for optimistic concurrency","type":"string"}},{"description":"RFC 6638 §3.2.10.1 — match the target's Schedule-Tag. Unlike the ETag this does not move when an arriving REPLY patches PARTSTAT into the stored copy, so an organizer's client can still write conditionally after its attendees answer. Sent together with If-Match, BOTH must validate","in":"header","name":"if-schedule-tag-match","required":false,"schema":{"description":"RFC 6638 §3.2.10.1 — match the target's Schedule-Tag. Unlike the ETag this does not move when an arriving REPLY patches PARTSTAT into the stored copy, so an organizer's client can still write conditionally after its attendees answer. Sent together with If-Match, BOTH must validate","type":"string"}},{"description":"Set to '*' to only create if resource does not exist","in":"header","name":"if-none-match","required":false,"schema":{"description":"Set to '*' to only create if resource does not exist","type":"string"}}],"requestBody":{"content":{"text/vcard":{"schema":{"description":"Raw iCalendar or vCard text","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimPutResult"}}},"description":"Object replaced successfully"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimPutResult"}}},"description":"Object created successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"empty_body, invalid_href, multiple_uids, unsatisfiable_recurrence (an RRULE no date after DTSTART satisfies), or validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"forbidden: read-only grant"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"uid_conflict: the href holds a different UID, or the UID already lives at another href (conflictHref names it); unsupported_component: the calendar does not accept the object's component"},"412":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"precondition_failed: If-Match/If-None-Match not satisfied"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"object_too_large (max 1048576 bytes)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_unavailable: preparation could not complete; no mutation committed. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_backlog_full, too_many_objects (collection or store object cap) or store_full (the store's 268435456-byte total would be exceeded)"}},"summary":"Create or replace addressbook object","tags":["PIM"]},"get":{"description":"Returns a addressbook object in raw text/vcard format, or as JSContact JSON (RFC 9553) when requested with Accept: application/json.","operationId":"get_AddressbookObjectGet","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","in":"path","name":"href","required":true,"schema":{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","maxLength":512,"minLength":1,"type":"string"}},{"description":"Look up object by UID instead of href slug","in":"query","name":"uid","required":false,"schema":{"description":"Look up object by UID instead of href slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimObjectJson"}},"text/vcard":{"schema":{"type":"string"}}},"description":"Stored object body and metadata"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such object, collection, or mailbox"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get addressbook object","tags":["PIM"]},"delete":{"description":"Deletes a addressbook object by its href slug or UID. The object moves to the collection's trash (GET …/trash lists it, POST …/trash/{objectId}/restore brings it back) and is purged for good fourteen days later.","operationId":"delete_AddressbookObjectDelete","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","in":"path","name":"href","required":true,"schema":{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","maxLength":512,"minLength":1,"type":"string"}},{"description":"Match by UID instead of href","in":"query","name":"uid","required":false,"schema":{"description":"Match by UID instead of href","type":"string"}},{"description":"Target ETag validator","in":"header","name":"if-match","required":false,"schema":{"description":"Target ETag validator","type":"string"}},{"description":"RFC 6638 §3.2.10.1 Schedule-Tag validator; validated independently of If-Match","in":"header","name":"if-schedule-tag-match","required":false,"schema":{"description":"RFC 6638 §3.2.10.1 Schedule-Tag validator; validated independently of If-Match","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"boolean"},"href":{"type":"string"},"id":{"type":"string"},"syncToken":{"type":"string"},"uid":{"type":"string"}},"required":["deleted","id","href","uid","syncToken"],"type":"object"}}},"description":"Object deleted successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"forbidden: read-only grant"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such object, collection, or mailbox"},"412":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"precondition_failed: If-Match not satisfied"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_unavailable: preparation could not complete; no deletion committed. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_backlog_full: scheduling admission budget exhausted; no deletion committed"}},"summary":"Delete addressbook object","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/objects/{href}/move":{"post":{"description":"Moves a addressbook object to another collection, renames its href slug, or both. Optional overwrite validates the destination and replaces an unscheduled occupant atomically; the replaced object remains recoverable in trash.","operationId":"post_AddressbookObjectMove","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","in":"path","name":"href","required":true,"schema":{"description":"The object's href: its filename segment within the collection (e.g. 1a2b3c.ics)","maxLength":512,"minLength":1,"type":"string"}},{"description":"Target ETag validator","in":"header","name":"if-match","required":false,"schema":{"description":"Target ETag validator","type":"string"}},{"description":"RFC 6638 schedule-tag validator; 412 on a mismatch","in":"header","name":"if-schedule-tag-match","required":false,"schema":{"description":"RFC 6638 schedule-tag validator; 412 on a mismatch","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"overwrite":{"description":"Replace an existing destination atomically (default false); scheduled calendar occupants cannot be replaced","type":"boolean"},"to":{"description":"New resource href slug","maxLength":512,"minLength":1,"type":"string"},"toAddressbookId":{"description":"Destination collection ULID or name slug","type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"collectionId":{"description":"Where the object now lives","type":"string"},"etag":{"type":"string"},"id":{"type":"string"},"overwritten":{"description":"Whether an existing destination object was replaced","type":"boolean"},"scheduleTag":{"description":"RFC 6638 schedule-tag of the object at its new href","type":"string"},"syncToken":{"type":"string"}},"required":["id","etag","scheduleTag","syncToken","collectionId","overwritten"],"type":"object"}}},"description":"Object moved or renamed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"invalid_href, or neither to nor destination was supplied"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"forbidden — read-only grant on source or destination"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such object, source collection, destination collection, or mailbox"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"href_taken, uid_conflict, wrong_kind, unsupported_component, or scheduled_overwrite: a scheduled calendar destination cannot be replaced"},"412":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"precondition_failed: If-Match not satisfied"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Move or rename addressbook object","tags":["PIM"],"x-max-json-body-bytes":1048576}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/trash":{"get":{"description":"The objects deleted out of this addressbook within the last fourteen days, newest first, metadata only (a restore is how the body comes back). Owner only.","operationId":"get_AddressbookObjectTrashList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Live collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Live collection ULID or its name slug","type":"string"}},{"description":"Page size (default 200)","in":"query","name":"limit","required":false,"schema":{"description":"Page size (default 200)","maximum":1000,"minimum":1,"type":"integer"}},{"description":"nextCursor from the previous page","in":"query","name":"cursor","required":false,"schema":{"description":"nextCursor from the previous page","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimTrashedObjectPage"}}},"description":"Deleted objects, newest deletion first"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"invalid_cursor"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such live collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List deleted addressbook objects","tags":["PIM"]},"delete":{"description":"Removes every deleted object of this addressbook from the trash for good. Irreversible. Owner only, full scope.","operationId":"delete_AddressbookObjectTrashEmpty","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Live collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Live collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimTrashPurged"}}},"description":"Emptied; objectsPurged counts what went"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such live collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Empty addressbook trash","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/trash/{objectId}/restore":{"post":{"description":"Brings a deleted object back into this addressbook under its own id, href and UID, byte-identical. For a meeting this mailbox organizes, the body's SEQUENCE is then advanced by one and a fresh REQUEST is sent to its attendees (the delete sent them a CANCEL), unless notify=false; an attendee's copy is restored locally and nothing is sent. Owner only, write scope.","operationId":"post_AddressbookObjectTrashRestore","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Live collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Live collection ULID or its name slug","type":"string"}},{"description":"The trashed object's ULID (the id it had while live)","in":"path","name":"objectId","required":true,"schema":{"description":"The trashed object's ULID (the id it had while live)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimObjectRestored"}}},"description":"Restored"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such deleted object in this collection, no such live collection, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"href_taken: a live object holds the deleted one's href; uid_conflict: a live object holds its UID (conflictHref names it); unsupported_component: the calendar no longer accepts the deleted object's component"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_unavailable: preparation could not complete; nothing restored. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_backlog_full or too_many_objects: the scheduling or object cap; nothing restored"}},"summary":"Restore deleted addressbook object","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/trash/{objectId}":{"delete":{"description":"Removes one deleted object from the trash for good. Irreversible. Owner only, full scope.","operationId":"delete_AddressbookObjectTrashPurge","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Live collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Live collection ULID or its name slug","type":"string"}},{"description":"The trashed object's ULID (the id it had while live)","in":"path","name":"objectId","required":true,"schema":{"description":"The trashed object's ULID (the id it had while live)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimTrashPurged"}}},"description":"Purged"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such deleted object in this collection, no such live collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Purge deleted addressbook object","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/changes":{"get":{"description":"Returns added, updated, and deleted object delta changes since a previous sync token (RFC 6578 sync-collection).","operationId":"get_AddressbookChanges","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"Sync token from previous response (omit for initial sync)","in":"query","name":"since","required":false,"schema":{"description":"Sync token from previous response (omit for initial sync)","type":"string"}},{"description":"Maximum changes to return","in":"query","name":"limit","required":false,"schema":{"description":"Maximum changes to return","maximum":500,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimChanges"}}},"description":"Delta changes, updated sync token, and more-remaining flag"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"invalid_sync_token — token expired or invalid; full resync required"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Sync changes for addressbook","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/import":{"post":{"description":"Imports multiple addressbook items in bulk from a text/vcard file (iCalendar .ics or vCard .vcf).","operationId":"post_AddressbookImport","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"requestBody":{"content":{"text/vcard":{"schema":{"description":"vCard file contents (.vcf) with one or more VCARD components","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimImportResult"}}},"description":"All items imported successfully"},"207":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimImportResult"}}},"description":"Multi-status: some items succeeded while others failed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"empty_body, not_calendar, or empty_import"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"forbidden: read-only grant"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"import_too_large (max 16777216 bytes) or too_many_items (max 500 items)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Import addressbook data","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/export":{"get":{"description":"Exports the entire addressbook collection as a single vCard (.vcf) text stream.","operationId":"get_AddressbookExport","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"text/vcard":{"schema":{"type":"string"}}},"description":"Merged file contents ready to save or import"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Export whole addressbook","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/shares/{shareeIdentityId}":{"put":{"description":"Grants read or write access to a mailbox for a addressbook collection.","operationId":"put_AddressbookSharePut","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The grantee's mailbox identity ULID","in":"path","name":"shareeIdentityId","required":true,"schema":{"description":"The grantee's mailbox identity ULID","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"permission":{"description":"Permission level ('read' or 'write')","enum":["read","read-write"],"type":"string"}},"required":["permission"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimShare"}}},"description":"Access grant created or updated"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, sharee, or mailbox"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Grant addressbook access","tags":["PIM"],"x-max-json-body-bytes":1048576},"delete":{"description":"Revokes a mailbox's access grant to a addressbook collection.","operationId":"delete_AddressbookShareDelete","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"The grantee's mailbox identity ULID","in":"path","name":"shareeIdentityId","required":true,"schema":{"description":"The grantee's mailbox identity ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"type":"object"}}},"description":"Access grant revoked successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such grant, collection, or mailbox"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Revoke addressbook access","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/shares":{"get":{"description":"Returns access grants configured on a addressbook collection.","operationId":"get_AddressbookShareList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"shares":{"items":{"$ref":"#/components/schemas/PimShare"},"type":"array"}},"required":["shares"],"type":"object"}}},"description":"List of access grants"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List addressbook access grants","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/tokens":{"post":{"description":"Generates a secret read-only feed token URL for syncing a addressbook in external apps (webcal/.ics/.vcf).","operationId":"post_AddressbookTokenCreate","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"expiresAt":{"description":"Unix expiration timestamp in seconds (omit for never)","type":"integer"},"label":{"description":"Human-readable token description (e.g. 'Apple Calendar')","maxLength":128,"type":"string"}},"type":"object"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimTokenCreated"}}},"description":"Feed token created successfully (token and URL are shown once)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create addressbook feed token","tags":["PIM"],"x-max-json-body-bytes":1048576},"get":{"description":"Returns active read-only subscription tokens for a addressbook collection.","operationId":"get_AddressbookTokenList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"tokens":{"items":{"$ref":"#/components/schemas/PimToken"},"type":"array"}},"required":["tokens"],"type":"object"}}},"description":"List of feed tokens"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such collection, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List addressbook feed tokens","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/{addressbookId}/tokens/{tokenId}":{"delete":{"description":"Revokes a read-only feed token for a addressbook collection.","operationId":"delete_AddressbookTokenRevoke","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Collection ULID or its name slug","in":"path","name":"addressbookId","required":true,"schema":{"description":"Collection ULID or its name slug","type":"string"}},{"description":"Feed token ULID identifier","in":"path","name":"tokenId","required":true,"schema":{"description":"Feed token ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"type":"object"}}},"description":"Feed token revoked successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such token, collection, or mailbox"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Revoke addressbook feed token","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/trash":{"get":{"description":"The addressbooks this mailbox deleted within the last fourteen days, newest first, each with the count of members that went with it. Owner only.","operationId":"get_AddressbookTrashList","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"addressbooks":{"items":{"$ref":"#/components/schemas/PimTrashedCollection"},"type":"array"}},"required":["addressbooks"],"type":"object"}}},"description":"Deleted collections, newest deletion first"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: mailbox not found, or not this principal's to administer"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List deleted addressbooks","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/trash/{trashedAddressbookId}/restore":{"post":{"description":"Brings a deleted addressbook back under its own id, with exactly the members that were deleted with it (members deleted individually beforehand stay in the trash, restorable once the collection is live). It comes back private: grants, feed tokens and any public listing were retired when it was deleted. For a calendar, each restored meeting this mailbox organizes is re-sent to its attendees as a REQUEST with SEQUENCE advanced by one, off the response path, unless notify=false. Owner only, write scope.","operationId":"post_AddressbookTrashRestore","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"The trashed collection's ULID (the id it had while live)","in":"path","name":"trashedAddressbookId","required":true,"schema":{"description":"The trashed collection's ULID (the id it had while live)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimCollectionRestored"}}},"description":"Restored; the live collection and what came back with it"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such deleted collection of this kind, or mailbox not accessible"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"name_taken: a live collection of this kind now holds the deleted one's name; rename it first"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_unavailable: preparation could not complete; nothing restored. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"507":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"scheduling_backlog_full, too_many_collections, or too_many_objects: the restore would exceed the admission budget"}},"summary":"Restore deleted addressbook","tags":["PIM"]}},"/api/v1/identities/{identityId}/addressbooks/trash/{trashedAddressbookId}":{"delete":{"description":"Removes a deleted addressbook from the trash for good, with every trashed object that belonged to it. Irreversible. Owner only, full scope.","operationId":"delete_AddressbookTrashPurge","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"The trashed collection's ULID (the id it had while live)","in":"path","name":"trashedAddressbookId","required":true,"schema":{"description":"The trashed collection's ULID (the id it had while live)","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimTrashPurged"}}},"description":"Purged"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: no such deleted collection of this kind, or mailbox not accessible"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Purge deleted addressbook","tags":["PIM"]}},"/api/v1/identities/{identityId}/contacts/suggest":{"get":{"description":"Compose-screen autocomplete: matches what the user typed (case-insensitive substring) against each card's formatted name, email and structured name, across every addressbook the identity owns plus those shared with it, in one call. Results are deduplicated by address, prefix matches rank first, and the caller's own books rank ahead of shared ones. Cards with no email are excluded (a suggestion a composer cannot address is noise), and only a card's FIRST `EMAIL` is indexed, so a match on a secondary address is not found. Each row carries enough identity (ownerIdentityId + addressbookId + uid) to fetch the full card via the owning addressbook's objects listing with `?uid=`.","operationId":"get_ContactSuggest","parameters":[{"description":"Mailbox identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Mailbox identity ULID","type":"string"}},{"description":"What the user typed so far (bounded like every contact search: 48 bytes)","in":"query","name":"q","required":true,"schema":{"description":"What the user typed so far (bounded like every contact search: 48 bytes)","minLength":1,"type":"string"}},{"description":"Maximum suggestions (default 10)","in":"query","name":"limit","required":false,"schema":{"description":"Maximum suggestions (default 10)","maximum":50,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"suggestions":[{"address":"ada@example.com","addressbookId":"01J9ABOK2D5F8H1K4M00000000","name":"Ada Lovelace","ownerIdentityId":"01J9MBX7F4Q2K9T3W600000000","uid":"a1b2c3d4-ada0-4c3d-9f2e-000000000001"},{"address":"adalyn@sales.acme.example","addressbookId":"01J9ABOK9E2G5J8L1N00000000","name":"Adalyn Reyes","ownerIdentityId":"01J9MBX2B5D8F1H4K600000000","uid":"a1b2c3d4-ada0-4c3d-9f2e-000000000002"}]},"schema":{"$ref":"#/components/schemas/ContactSuggestions"}}},"description":"Deduplicated suggestions, best matches first"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"search_term_too_long: q exceeds the 48-byte search bound"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Identity not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Suggest contacts","tags":["PIM"]}},"/api/v1/identities/{identityId}/pim/shared-with-me":{"get":{"description":"Returns calendar and addressbook collections shared with the mailbox by other users.","operationId":"get_PimSharedWithMeList","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"shared":{"items":{"$ref":"#/components/schemas/PimSharedWithMe"},"type":"array"}},"required":["shared"],"type":"object"}}},"description":"List of shared collections"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List collections shared with mailbox","tags":["PIM"]}},"/api/v1/identities/{identityId}/pim/public-directory":{"get":{"description":"Returns discoverable public calendars and addressbooks shared across the account tenant.","operationId":"get_PimPublicDirectory","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"public":{"items":{"$ref":"#/components/schemas/PimPublicCollection"},"type":"array"}},"required":["public"],"type":"object"}}},"description":"Public collection listings"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Browse account public directory","tags":["PIM"]}},"/api/v1/identities/{identityId}/pim/subscriptions/{publicId}":{"post":{"description":"Subscribes the mailbox to a public collection and creates a read grant.","operationId":"post_PimSubscribe","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Public directory listing ULID identifier","in":"path","name":"publicId","required":true,"schema":{"description":"Public directory listing ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PimPublicCollection"}}},"description":"Subscribed successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"No such public collection, or it is no longer public"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Subscribe to public collection","tags":["PIM"]},"delete":{"description":"Unsubscribes the mailbox from a public collection and removes its read grant.","operationId":"delete_PimUnsubscribe","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}},{"description":"Public directory listing ULID identifier","in":"path","name":"publicId","required":true,"schema":{"description":"Public directory listing ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"type":"object"}}},"description":"Unsubscribed successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Not subscribed"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Unsubscribe from public collection","tags":["PIM"]}},"/api/v1/identities/{identityId}/pim/subscriptions":{"get":{"description":"Returns all public collections the mailbox is currently subscribed to.","operationId":"get_PimSubscriptionList","parameters":[{"description":"Identity ULID identifier","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID identifier","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"subscriptions":{"items":{"$ref":"#/components/schemas/PimPublicCollection"},"type":"array"}},"required":["subscriptions"],"type":"object"}}},"description":"List of subscriptions"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"Mailbox not found or not accessible to this principal"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List public collection subscriptions","tags":["PIM"]}},"/api/v1/pim/feeds/{token}":{"get":{"description":"Returns a full iCalendar or vCard feed for calendar and addressbook sync. No bearer credential: the secret token in the path IS the credential, made to be pasted into a third-party calendar or contacts app.","operationId":"get_PimFeed","parameters":[{"description":"Secret feed token","in":"path","name":"token","required":true,"schema":{"description":"Secret feed token","maxLength":256,"minLength":8,"type":"string"}}],"responses":{"200":{"content":{"text/calendar":{"schema":{"type":"string"}},"text/vcard":{"schema":{"type":"string"}}},"description":"Full collection exported as an iCalendar or vCard stream"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found: unknown, expired, or revoked token. credential_reissue_required (with a message): a token in the format feed URLs had before the platform's directory cutover, which no longer serves (recognized by its shape, so a token of that format is refused this way whether or not it was ever issued); the collection's owner creates a new feed token and the subscriber adds its URL in place of the old one. Both are permanent: do not retry."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"security":[],"summary":"Export collection via feed token","tags":["PIM"]}},"/api/v1/identities/{identityId}/pim/events":{"get":{"description":"Upgrades to a WebSocket that streams `pim.changed` frames for this identity's calendars, tasks and contacts: `{ v, type, ts, data }` where `data` is the current state token per type (`{ Calendar, CalendarEvent, Task, AddressBook, ContactCard }`), the same tokens the per-collection `/changes` feeds and JMAP accept. A `ready` frame with the session deadline is sent on connect. Signals are not a journal: there is no replay, so on every (re)connect re-sync, and treat each frame as 'this changed, re-fetch it'. The vocabulary is additive: treat an unrecognized `type` as a generic nudge.\n\nOwner-only: a calendar or address book shared with you is not streamed here. Before the first calendar or contact use, the connection waits without creating a store. Its first authorized PIM use creates the default collections and sends one `pim.changed` frame. The session is closed with 4401 (session_expired: reconnect with a fresh bearer) after 12h, 4403 (credential_revoked: the credential was revoked or its owner suspended; do not reconnect with it) or 4410 (mailbox_gone: the identity is being deleted; stop reconnecting). Keepalive: send a `ping` text frame, receive `pong`.","operationId":"get_PimEvents","parameters":[{"description":"Identity ULID","in":"path","name":"identityId","required":true,"schema":{"description":"Identity ULID","type":"string"}}],"responses":{"101":{"description":"Switching Protocols: the WebSocket is established"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"forbidden: the identity's owner is suspended and this connection would act for them (an account or system key acting for nobody may still connect)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found (the identity does not exist or is not this principal's to stream)"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_gone: the identity is being deleted; stop reconnecting"},"426":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"upgrade_required: the request was not a WebSocket upgrade"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_many_subscribers: the store's subscriber cap is reached","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Subscribe to live calendar and contacts change events over WebSocket","tags":["PIM"]}},"/api/v1/accounts/{accountId}/templates":{"get":{"description":"Every stored template this account owns, with the languages each one has copy for. Needs an unscoped account key: a domain-scoped one is refused on the whole account surface.","operationId":"get_TemplateIndex","parameters":[{"description":"Account ULID identifier.","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailTemplateList"}}},"description":"The account's templates"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"List this account's mail templates","tags":["Templates"]},"post":{"description":"Registers a template. The From address must be one this account may already send as; the copy is added per language afterwards.","operationId":"post_TemplateCreate","parameters":[{"description":"Account ULID identifier.","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier.","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"defaultLang":{"description":"Language tag, e.g. `en` or `de-AT`. Stored lowercased.","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$","type":"string"},"from":{"format":"email","maxLength":320,"type":"string"},"name":{"maxLength":200,"minLength":1,"type":"string"},"replyTo":{"format":"email","maxLength":320,"type":["string","null"]},"slug":{"description":"The template's name within this account.","maxLength":64,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","type":"string"},"variables":{"additionalProperties":{"additionalProperties":false,"properties":{"description":{"maxLength":500,"type":"string"},"sample":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Dummy data for the preview. A flag's sample is a boolean: the string \"false\" is truthy"}},"type":"object"},"description":"Documentation and dummy data per variable. Never a schema: a body may use what this omits.","type":"object"}},"required":["slug","name","from"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailTemplate"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"reserved_slug, from_not_sendable or an invalid variable declaration"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"slug_taken, or template_limit_reached carrying the effective ceiling"},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"length_required: Content-Length is required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: the JSON body exceeds 2 MiB"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Create a mail template","tags":["Templates"],"x-max-json-body-bytes":2097152}},"/api/v1/accounts/{accountId}/templates/{slug}":{"get":{"description":"The template's metadata, its variable declarations, and the stored copy for every language it has.","operationId":"get_TemplateGet","parameters":[{"description":"Account ULID identifier.","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier.","type":"string"}},{"description":"The template's name within this account.","in":"path","name":"slug","required":true,"schema":{"description":"The template's name within this account.","maxLength":64,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailTemplateDetail"}}},"description":"The template"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Get one mail template","tags":["Templates"]},"patch":{"description":"Changes the name, From, Reply-To, default language or variable declarations. Only fields that differ are written: a PATCH that changes nothing is a no-op. The version moves only when From, Reply-To or the default language changes, since those are what a send reads; a name or a declaration moves `updatedAt` alone.","operationId":"patch_TemplatePatch","parameters":[{"description":"Account ULID identifier.","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier.","type":"string"}},{"description":"The template's name within this account.","in":"path","name":"slug","required":true,"schema":{"description":"The template's name within this account.","maxLength":64,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"defaultLang":{"description":"Language tag, e.g. `en` or `de-AT`. Stored lowercased.","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$","type":"string"},"from":{"format":"email","maxLength":320,"type":"string"},"name":{"maxLength":200,"minLength":1,"type":"string"},"replyTo":{"format":"email","maxLength":320,"type":["string","null"]},"variables":{"additionalProperties":{"additionalProperties":false,"properties":{"description":{"maxLength":500,"type":"string"},"sample":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Dummy data for the preview. A flag's sample is a boolean: the string \"false\" is truthy"}},"type":"object"},"description":"Documentation and dummy data per variable. Never a schema: a body may use what this omits.","type":"object"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailTemplate"}}},"description":"Updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"from_not_sendable or an invalid variable declaration"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found"},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"length_required: Content-Length is required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: the JSON body exceeds 2 MiB"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Update a template's metadata","tags":["Templates"],"x-max-json-body-bytes":2097152},"delete":{"description":"Removes the template and every language's copy. Messages already sent are unaffected; a send naming this slug afterwards answers not_found.","operationId":"delete_TemplateDelete","parameters":[{"description":"Account ULID identifier.","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier.","type":"string"}},{"description":"The template's name within this account.","in":"path","name":"slug","required":true,"schema":{"description":"The template's name within this account.","maxLength":64,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"enum":[true],"type":"boolean"},"slug":{"type":"string"}},"required":["slug","deleted"],"type":"object"}}},"description":"Deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Delete a mail template","tags":["Templates"]}},"/api/v1/accounts/{accountId}/templates/{slug}/variants/{lang}":{"put":{"description":"Stores the subject and bodies for one language. A plain-text body is required; HTML is optional and builds a multipart/alternative message beside it.","operationId":"put_TemplateVariantPut","parameters":[{"description":"Account ULID identifier.","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier.","type":"string"}},{"description":"The template's name within this account.","in":"path","name":"slug","required":true,"schema":{"description":"The template's name within this account.","maxLength":64,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","type":"string"}},{"description":"Language tag, e.g. `en` or `de-AT`. Stored lowercased.","in":"path","name":"lang","required":true,"schema":{"description":"Language tag, e.g. `en` or `de-AT`. Stored lowercased.","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"html":{"type":["string","null"]},"subject":{"maxLength":500,"minLength":1,"type":"string"},"text":{"minLength":1,"type":"string"}},"required":["subject","text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"changed":{"description":"False when this language already held exactly this copy: nothing was written","type":"boolean"},"lang":{"type":"string"},"slug":{"type":"string"},"stored":{"enum":[true],"type":"boolean"}},"required":["slug","lang","stored","changed"],"type":"object"}}},"description":"Stored"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"template_invalid, text_required, subject_too_long or body_too_large"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"variant_limit_reached"},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"length_required: Content-Length is required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: the JSON body exceeds 2 MiB"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Write one language's copy","tags":["Templates"],"x-max-json-body-bytes":2097152},"delete":{"description":"Drops a language. The template keeps its other languages; a send asking for this one falls to the template's default language, or is refused when there is none.","operationId":"delete_TemplateVariantDelete","parameters":[{"description":"Account ULID identifier.","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier.","type":"string"}},{"description":"The template's name within this account.","in":"path","name":"slug","required":true,"schema":{"description":"The template's name within this account.","maxLength":64,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","type":"string"}},{"description":"Language tag, e.g. `en` or `de-AT`. Stored lowercased.","in":"path","name":"lang","required":true,"schema":{"description":"Language tag, e.g. `en` or `de-AT`. Stored lowercased.","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"lang":{"type":"string"},"removed":{"type":"boolean"},"slug":{"type":"string"}},"required":["slug","lang","removed"],"type":"object"}}},"description":"Removed, or already absent"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Remove one language's copy","tags":["Templates"]}},"/api/v1/accounts/{accountId}/templates/{slug}/render":{"post":{"description":"Returns the subject and bodies a send would produce, and a report on every variable: what the declaration says, which body uses it, and whether a sample filled it. With `preview`, any variable the caller omits is filled from its declared sample. With `draft`, it renders that copy instead of the stored one, under the checks a save makes, and stores nothing: saving a variant publishes it, so this is how copy is seen before it is live.","operationId":"post_TemplateRender","parameters":[{"description":"Account ULID identifier.","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier.","type":"string"}},{"description":"The template's name within this account.","in":"path","name":"slug","required":true,"schema":{"description":"The template's name within this account.","maxLength":64,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"draft":{"additionalProperties":false,"description":"Copy not stored yet, rendered in the language asked for (else the template's default) with no fallback, since it IS that language's copy. Held to the checks a save makes, so a broken draft gets the refusal saving it would; nothing is written.","properties":{"html":{"type":["string","null"]},"subject":{"maxLength":500,"minLength":1,"type":"string"},"text":{"minLength":1,"type":"string"}},"required":["subject","text"],"type":["object","null"]},"lang":{"description":"Language tag, e.g. `en` or `de-AT`. Stored lowercased.","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$","type":["string","null"]},"preview":{"type":"boolean"},"recipient":{"additionalProperties":false,"properties":{"email":{"format":"email","type":"string"},"name":{"maxLength":200,"type":["string","null"]}},"required":["email"],"type":["object","null"]},"vars":{"additionalProperties":{"anyOf":[{"maxLength":16384,"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"type":"object"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailTemplateRender"}}},"description":"The rendered message"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"missing_variable, rendered_too_large, rendered_subject_too_long, template_invalid, no_variant_for_language, a draft's own refusal (text_required, subject_too_long, body_too_large, as a save answers it), or validation_failed for an unknown key"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found"},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"length_required: Content-Length is required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: the JSON body exceeds 2 MiB"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Render a template without sending it","tags":["Templates"],"x-max-json-body-bytes":2097152}},"/api/v1/accounts/{accountId}/templates/{slug}/send":{"post":{"description":"Renders the template once per recipient, with that recipient's own variables layered over the shared ones, and sends each as its own message, now. There is no `sendAt`: scheduling belongs to the mailbox product, and an unknown key is refused.","operationId":"post_TemplateSend","parameters":[{"description":"Account ULID identifier.","in":"path","name":"accountId","required":true,"schema":{"description":"Account ULID identifier.","type":"string"}},{"description":"The template's name within this account.","in":"path","name":"slug","required":true,"schema":{"description":"The template's name within this account.","maxLength":64,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_-]*$","type":"string"}},{"description":"Idempotency key. Each recipient's message derives its own from this, the template and the recipient's address, so a retry converges per recipient whatever the order or subset of the list it carries, and the same key used for a different template is a different message. At most 200 characters; `#` is reserved. A retry does not get around a sending hold: while the sender is paused or disabled it is refused like any submission, and once the hold lifts it continues without a second charge.","in":"header","name":"x-delivery-id","required":false,"schema":{"description":"Idempotency key. Each recipient's message derives its own from this, the template and the recipient's address, so a retry converges per recipient whatever the order or subset of the list it carries, and the same key used for a different template is a different message. At most 200 characters; `#` is reserved. A retry does not get around a sending hold: while the sender is paused or disabled it is refused like any submission, and once the hold lifts it continues without a second charge.","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"bounce":{"type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"description":"Extra headers for every message. Auto-Submitted, X-Auto-Response-Suppress and Content-Language are the route's own and are refused in any spelling.","type":"object"},"lang":{"description":"Language tag, e.g. `en` or `de-AT`. Stored lowercased.","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$","type":["string","null"]},"replyTo":{"format":"email","maxLength":320,"type":["string","null"]},"save":{"description":"Keep a Sent copy. Default FALSE here, unlike /send.","type":"boolean"},"to":{"description":"One message is built per entry, and an address may appear once. No cc or bcc: personalisation makes shared bytes meaningless.","items":{"additionalProperties":false,"properties":{"email":{"format":"email","type":"string"},"name":{"maxLength":200,"type":["string","null"]},"vars":{"additionalProperties":{"anyOf":[{"maxLength":16384,"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"type":"object"}},"required":["email"],"type":"object"},"maxItems":50,"minItems":1,"type":"array"},"vars":{"additionalProperties":{"anyOf":[{"maxLength":16384,"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"type":"object"}},"required":["to"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailTemplateSend"}}},"description":"Every recipient was accepted"},"207":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailTemplateSend"}}},"description":"Mixed: at least one recipient failed. Retry with the same delivery id to converge only the failures; rows a temporary refusal stopped carry `retryAfterSeconds`, and the response carries `Retry-After`. A hold that lands mid-batch fails the recipient being sent with sending_paused or sending_disabled and refuses the rest"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOrValidation"}}},"description":"missing_variable, rendered_too_large, rendered_subject_too_long or template_invalid (refused before ANY recipient is touched: one template serves the whole batch, so a render fault is one cause and not fifty failures), duplicate_recipient, reserved_header, no_variant_for_language, from_not_sendable, reserved_delivery_id, delivery_id_too_long, validation_failed for an unknown key, or the first message's own refusal as /send answers it"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"sending_disabled: the account's From is frozen"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"not_found, including a sender mailbox torn down before the first message (a later recipient's row says mailbox_gone instead)"},"411":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"length_required: Content-Length is required"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"too_large: the JSON body exceeds 2 MiB"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"sending_paused or rate_limited on the first message, with Retry-After: nothing was sent, retry the whole call","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"mailbox_closing or mailbox_reopening on the first message, with Retry-After: retry the whole call. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"summary":"Send a template to one or more recipients","tags":["Templates"],"x-max-json-body-bytes":2097152}},"/api/v1/health":{"get":{"description":"Answers `{ ok: true }` when the worker is serving requests. No credential, no dependencies probed: this is liveness, not readiness.","operationId":"get_Health","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"enum":[true],"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Service is up"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}},"description":"temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)","headers":{"Retry-After":{"description":"Seconds to wait before retrying, when the wait is known","schema":{"type":"string"}}}}},"security":[],"summary":"Liveness check","tags":["System"]}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://api.open.email"}],"tags":[{"description":"The tenant: lifecycle (delete/restore), usage and traffic statistics, allowance meters, the audit trail, and its verified recipients with their public confirmation link.","name":"Accounts"},{"description":"Who may call: account API keys (oek_), per-mailbox app passwords (oemp_), WebAuthn security keys, password and recovery flows, and whoami (which credential am I holding?).","name":"Credentials"},{"description":"A customer domain and everything hanging off it: registration and DNS checks, white-label branding and logo, vanity hostnames, DMARC report views, the domain-scoped event webhook, and per-domain statistics.","name":"Domains"},{"description":"The mailbox resources themselves: create/list/delete identities, settings and preferences, sharing grants, send-rate meters, and the mailbox-scoped event webhook.","name":"Mailboxes"},{"description":"What an address DOES when mail arrives: routes to a mailbox, webhook, remote forward, or group (with members), pattern (wildcard) routes, allow/block address lists, and the signed fetch capability webhook payloads link back to.","name":"Routing"},{"description":"What happens to mail as it arrives: filter rules and Sieve scripts, the out-of-office auto-reply, verified forwarding, and the recipient's public disable link.","name":"Filtering"},{"description":"Folders and labels: CRUD, per-label statistics, and the IMAP-shaped UID/vanished feeds a mail client syncs from.","name":"Labels"},{"description":"POP3 pickup: fetch mail from external POP3 accounts into a mailbox.","name":"Pickups"},{"description":"The store: list/read (parsed content, raw MIME, individual parts), flags/labels/keywords updates, batch operations, trash and restore, incremental sync (/changes), spam-filter training, and the live WebSocket event feed.","name":"Messages"},{"description":"Conversation views: one row per reply chain, Gmail-style label filtering.","name":"Threads"},{"description":"Stage attachment bytes once, then reference the blobId from /send, /compose, or /reply.","name":"Uploads"},{"description":"Sending: /send and thread replies, scheduled sends, per-recipient delivery status, deliverability pre-flight, and the raw-MIME submission and inbound doors the MTAs use.","name":"Delivery"},{"description":"The deployment-wide do-not-send list; accounts may lift their own hard-bounce entries.","name":"Suppressions"},{"description":"Web Push (RFC 8030) device registrations: register an endpoint, complete the verification handshake, and receive content-free StateChange wakes whose tokens feed the changes endpoints. The info section's Push heading maps the full realtime story.","name":"Push"},{"description":"Calendars and addressbooks: collections and their objects (iCalendar/vCard), sync tokens, import/export, sharing, feed tokens, public-directory subscriptions, and invitation RSVP.","name":"PIM"},{"description":"Stored, per-language messages this account sends by name with variables: create, write the copy, preview, send.","name":"Templates"},{"description":"Operator-only: the deployment panel (queues, dead letters, fleet traffic, purges) plus the public liveness check.","name":"System"}],"webhooks":{"event-batch":{"post":{"description":"POSTed to the URL configured by `PUT /api/v1/mailboxes/{mailboxId}/event-webhook` or `PUT /api/v1/domains/{domain}/event-webhook` (all events, no filters; the mailbox and domain hooks each get their own copy, signed with their own secret). Answer a 2xx within 30 seconds; acknowledge first, work after. Redirects are never followed: a 3xx counts as a failed attempt at the registered URL. A non-2xx answer or a timeout is a failed attempt, retried on a backoff ladder with the SAME batch `id` (dedupe on it); 24 hours of consecutive failures auto-disables the hook (`disabledReason: \"failing\"` on the resource) and any PUT re-enables it. Events are best-effort signals, not a journal: after re-enabling (or any suspected gap), re-sync through `GET /mailboxes/{mailboxId}/messages/changes` using the `states.Email` token. Requests carry `User-Agent: openemail-events/1`.","parameters":[{"description":"`sha256=<hex HMAC-SHA256 of the exact raw request body>`, keyed with the hook's secret. Present only when the hook has one. Verify against the received bytes before parsing; never re-serialize","in":"header","name":"x-openemail-signature","required":false,"schema":{"description":"`sha256=<hex HMAC-SHA256 of the exact raw request body>`, keyed with the hook's secret. Present only when the hook has one. Verify against the received bytes before parsing; never re-serialize","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"accountId":"01J9ACCT8B1D4F7H2K00000000","events":[{"actor":null,"data":{"id":"01J9MSGA8C2E5H1K4M00000000","threadId":"01J9THRD5E8G1J4M7P00000000"},"seq":214,"ts":1788263998,"type":"message.new"},{"actor":{"id":"01J9MBX7F4Q2K9T3W600000000","mailbox":"01J9MBX7F4Q2K9T3W600000000","type":"mailbox"},"data":{"id":"01J9MSGB3D7F9H2J5N00000000"},"seq":215,"ts":1788263999,"type":"message.updated"},{"actor":null,"data":{"Email":"MjgtOTE4NzA","EmailDelivery":"3","Mailbox":"5","Thread":"17"},"seq":216,"ts":1788264000,"type":"state.changed"}],"id":"01J9BATCH3E6G9J2M500000000","mailboxId":"01J9MBX7F4Q2K9T3W600000000","scope":"mailbox","sentAt":1788264000,"sequence":{"from":214,"to":216},"states":{"Email":"MjgtOTE4NzA","EmailDelivery":"3","Mailbox":"5","Thread":"17"}},"schema":{"$ref":"#/components/schemas/EventWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledged. ANY 2xx counts as delivered; anything else (or more than 30 seconds of silence) is retried"}},"summary":"Event webhook: one batch of change events"}},"message-delivery":{"post":{"description":"POSTed when mail arrives for an address routed to a webhook URL (`POST /api/v1/routes` with a webhook target), or as a TAP beside an ordinary mailbox delivery. The POST *is* the delivery: answer a 2xx within 30 seconds (acknowledge first, work after) or the attempt is retried with the same `deliveryId`. Redirects are never followed: a 3xx counts as a failed attempt at the registered URL. Bodies and attachments are inlined up to fixed ceilings (1 MiB per body, 256 KiB per attachment, 1 MiB total attachment budget); anything larger arrives as a signed, expiring `url` / `rawUrl` capability redeemed at `GET /api/v1/deliveries/fetch/{token}` with no credential. The parse is the SAME machinery as `GET /messages/{id}/content`, so a webhook receiver and a REST reader can never disagree about what the body is. A route or tap set to `webhookFormat: \"reference\"` opts out of the parse entirely: the same envelope and the same `message` with every header, `auth` and `rawUrl`, but `text`/`html` null, `attachments` empty and `bodiesOmitted: \"not_requested\"` — for a receiver that carries its own MIME parser.","parameters":[{"description":"`sha256=<hex HMAC-SHA256 of the exact raw request body>`, keyed with the hook's secret. Present only when the hook has one. Verify against the received bytes before parsing; never re-serialize","in":"header","name":"x-openemail-signature","required":false,"schema":{"description":"`sha256=<hex HMAC-SHA256 of the exact raw request body>`, keyed with the hook's secret. Present only when the hook has one. Verify against the received bytes before parsing; never re-serialize","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"blobHash":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","deliveryId":"01J9DVRY2C5E8G1J4M00000002","from":"ada@example.com","message":{"attachments":[{"content":null,"contentId":null,"contentOmitted":"too_large","contentType":"application/pdf","filename":"q3-report-draft.pdf","inline":false,"section":"3","size":44032,"url":"https://api.open.email/api/v1/deliveries/fetch/eyJrIjoic3RhZ2luZy8wMUo5IiwicyI6IjMifQ.c2ln"}],"auth":{"arc":null,"dkim":"pass","dmarc":"pass","junk":false,"spf":"pass"},"cc":[],"date":1788081272,"from":[{"email":"ada@example.com","name":"Ada Lovelace"}],"headers":{"from":["Ada Lovelace <ada@example.com>"],"message-id":["<7f2a1c9e4b8d@mail.example.com>"],"subject":["Q3 report draft"],"to":["orders@acme.example"]},"html":"<div>Hi, attached is the Q3 report draft we discussed on Friday.</div>","inReplyTo":null,"messageId":"<7f2a1c9e4b8d@mail.example.com>","references":[],"replyTo":[],"subject":"Q3 report draft","text":"Hi, attached is the Q3 report draft we discussed on Friday.","to":[{"email":"orders@acme.example","name":null}]},"rawUrl":"https://api.open.email/api/v1/deliveries/fetch/eyJrIjoic3RhZ2luZy8wMUo5In0.c2lnbmF0dXJl","receivedAt":1788081300,"size":48213,"to":"orders@acme.example"},"schema":{"$ref":"#/components/schemas/WebhookDeliveryPayload"}}}},"responses":{"200":{"description":"Acknowledged and delivered. ANY 2xx counts; anything else (or more than 30 seconds of silence) is retried"}},"summary":"Message webhook: one delivered email, parsed"}}}}