{ "openapi": "3.1.0", "info": { "title": "MailHQ API", "version": "1.8.0", "description": "## Domain onboarding guide\n\nSend and receive mail with your own domain. The domain can stay at its current registrar. An admin requests onboarding and verifies domain ownership; once DNS is configured with the records shown in the admin, you can use your own email addresses.\n\n[Start domain onboarding](/settings#domain-connection) · [Admin](/settings) · [Webmail](/webmail)\n\n### 01 · Request onboarding\n\nPrepare a domain whose DNS you control. In **Settings → External domain onboarding**, an admin selects a Stalwart mail service subscription, enters the domain (for example `example.com`) and clicks **Generate verification record**.\n\nOnly admins can request, verify and view onboarding settings. Domains and mailboxes are currently managed centrally by admins; domain owners never need to hand over registrar accounts or DNS keys to this service.\n\nAdmin tip: once provisioned, the domain joins the existing mailbox management and redemption rules. Generic redemption codes or products without a domain restriction will include the new domain; before hosting an external domain, review and restrict the allowed domains.\n\n### 02 · Add a TXT record to verify ownership\n\n1. In the admin, open the domain's onboarding details and copy the name and value of the **Domain ownership** TXT record.\n2. At the DNS provider the domain currently uses, add that TXT record. Whether the host field needs the full domain depends on your provider; avoid appending the domain suffix twice.\n3. Wait for DNS to propagate, then click **Verify ownership and connect** in the admin. Once verified, the domain is provisioned on the mail server and added to the managed list.\n\nPending verification records are valid for 7 days; after that, click **Refresh verification record**, update the value in DNS and verify again. Ownership of an already provisioned domain does not expire because of this. You can keep the verification TXT for auditing; removing it does not disable a provisioned domain. No MX change is needed at this stage, so existing mailboxes keep receiving mail.\n\nIf the page shows **Confirming provisioning**, use **Check again** to read the result; if it shows **Needs manual review**, an admin should check the domain on the server first to avoid creating it twice.\n\n### 03 · Prepare mailboxes, then migrate mail\n\nProvisioning status and mail DNS checks are shown separately. Once ownership verification and server provisioning are done, you can create mailboxes on the domain, such as `you@example.com`, without switching mail routing first.\n\nIf the domain already has mailboxes, create the matching accounts and confirm passwords and forwarding rules before migrating any old mail you want to keep. Creating a mailbox does not copy historical mail from the old provider.\n\nMove on only once the new mailboxes are ready. For a while after switching MX, some senders may still use the old records, so keep the old service and check mail on both sides.\n\n### 04 · Configure mail DNS from the admin, switch MX last\n\nIn **Settings → Domains**, click the domain's **DNS settings / check**, or open its details from the onboarding request list. The admin shows the exact names, values, MX priorities and check results this domain needs. Use those records; the table below explains what each kind is for.\n\n| Record | Purpose | Notes |\n| --- | --- | --- |\n| MX | Delivers new mail to this service | Use the target and priority shown in the admin; switch it last, once mailboxes and migration are ready. |\n| TXT · SPF | Authorizes servers to send for the domain | A domain can have only one SPF record. If one exists, merge the authorizations and keep other sending services still in use. |\n| TXT · DKIM | Verifies mail signatures | Copy each selector and public key exactly as shown in the admin. Do not use signing records from other domains or servers. |\n| TXT · DMARC | Declares the mail authentication policy | Optional and recommended; start with `p=none`. If a policy exists, review it first and do not overwrite existing quarantine or reject policies. |\n\nSet mail-related records to **DNS only**; do not enable web proxying. Unless an admin says otherwise, there is no need to create `mail.your-domain` or get a certificate for it; mail clients use the server name shown in the admin.\n\nBefore switching MX, review the domain settings at the old provider. Some providers may still deliver mail sent within their own platform to their old mailboxes, so the old provider's delivery mode may also need adjusting.\n\n### 05 · Check again and start using it\n\nAfter saving DNS, click **Check again** in the domain details. The page shows the records currently found and why any are missing, conflicting or failed to resolve. DNS caches take time to update; if records don't match yet, confirm the names and values, then wait for the old records' caches to expire.\n\n| Item | Setting |\n| --- | --- |\n| Incoming mail | IMAP · 993 · SSL/TLS |\n| Outgoing mail | SMTP · 465 · SSL/TLS |\n| Server | The server name shown on the admin page |\n| Sign-in | Full email address + mailbox password |\n\nUse [Webmail](/webmail) or your own mail client. Whether webmail is available depends on the domain being provisioned and the settings an admin has enabled.\n\nTest receiving and sending separately from an independent external mailbox, and check the spam folder. Passing DNS checks and SPF / DKIM / DMARC does not guarantee delivery to the inbox at Gmail or other services.\n\nThe live settings on the admin page are authoritative for each domain's records. [Manage domain onboarding](/settings#domain-connection).\n\n## API access\n\n### Creating keys and authenticating\n\nFirst generate an API key in [Settings → API keys](/settings/api-keys), choosing the permissions and expiry you need (it can be set to never expire), then enter the full key under Authorize.\n\nAll `/api/v1` endpoints accept only `Authorization: Bearer `. A browser sign-in cookie cannot replace a Bearer key, and each operation also requires the matching scope. Granting only a write scope does not grant read access. After a key is revoked, further requests with it are rejected.\n\n### Scope\n\nThis API manages the Stalwart mail service connected to MailHQ.\n\nIt currently covers the server list, domain verification and provisioning, importing existing domains, enabling/disabling domains, mailboxes, passwords, status, storage quota, daily sending limits, notes, regular aliases, distribution lists, forwarding, a per-domain catch-all, alias domains and domain connection details, with batch operations. It does not offer reading/searching/deleting mail content, sending mail, autoresponders, spam policies or reseller management.\n\nBelow, each operation's scope, parameters, responses and examples are listed by group. The API base URL is `/api/v1` on this site.\n\n### Regular aliases and domain management\n\nRegular aliases use the `aliases:read` / `aliases:write` scopes. The target must be an existing managed user mailbox on the same domain; aliases can be created, renamed, enabled/disabled, re-described and deleted, but the target mailbox cannot be changed. Special or read-only aliases must be managed in Stalwart. Aliases are neither external forwarding nor catch-all.\n\n`GET /domains/{id}/catch-all` reads and `PUT /domains/{id}/catch-all` sets the mailbox that receives mail for addresses of the domain nobody holds: `{ \"destination\": \"postmaster@example.com\" }` (an existing managed mailbox of the same domain), or `{ \"destination\": null }` to reject such mail, the default. A catch-all accepts every guessed or mistyped address, so it attracts spam.\n\n`PUT /domains/{id}/status` accepts `{ \"enabled\": true }` or `false` and enables or disables the domain on Stalwart. `DELETE /domains/{id}` still only removes the local record and cannot delete the remote domain. Writes to domains and aliases require the admin role and the matching write scope.\n\n### Alias domains\n\nAn alias domain is an additional domain name whose addresses deliver to the mailboxes of a primary domain: mail for `user@alias.example` goes to the mailbox of `user@primary.example`, and the primary domain's aliases, lists and catch-all apply too. `POST /domains/{id}/domain-aliases` with `{ \"domain\": \"alias.example\" }` records the request and returns the ownership TXT record; after publishing it, `POST /domains/{id}/domain-aliases/{aliasId}/verify` adds the name on the mail server, and `GET` on the alias lists the MX record it needs to receive mail. An alias domain is for receiving: mail sent from its addresses is signed with the primary domain's DKIM key. Onboard a domain of its own when it has to send under its own name.\n\n### Distribution lists\n\nDistribution lists use the `lists:read` / `lists:write` scopes. A list is an address of a domain that delivers a copy of every message to all of its members; it has no mailbox, cannot sign in and does not count towards the workspace's mailbox limit. `GET /lists?domainId=…` lists a domain's lists with their members, `POST /lists` creates one, and `PATCH /lists/{listId}` renames it, changes its description and adds or removes members. Members that are not mailboxes managed by the workspace are refused unless the request sets `allowExternal: true`: the mail server then forwards everything sent to the list, spam included, to those outside addresses. The list's address must be free among mailboxes (pending and deleted ones included), aliases, forwarding addresses and other lists.\n\n### Legal holds\n\nLegal holds use the `holds:read` / `holds:write` scopes (admin keys only). `POST /holds` places a hold on one mailbox (`mailboxId`) or on every mailbox of a domain (`domain`) with a `name`, a `reason` and an optional `endsAt`; `POST /holds/{id}/release` releases it with a `reason`. While a hold is active the mailbox cannot be deleted permanently or purged from the recycle bin (`409 legal_hold`); deleting it into the recycle bin still works. A hold preserves the mailbox, not individual messages: the mailbox's user can still delete their own mail, and this is not a certified archive.\n\n### Reports\n\n`GET /reports/inactive-mailboxes`, `GET /reports/storage` and `GET /reports/top-senders` are read-only reports under `mailboxes:read`: mailboxes with no WebMail sign-in and no mail for 30, 60 or 90 days, mailbox usage per domain from daily samples, and today's top senders by daily sending-limit usage. They are computed from records MailHQ keeps, not from the mail server's own counters: sign-ins and sends of mail apps over IMAP / SMTP are not seen.\n\n### Batch requests and verifying results\n\n`POST /batch` accepts `{ \"operations\": [...] }` with 1–25 operations and a body of at most 16 KiB, and requires an `Idempotency-Key` of 8–128 letters, digits, hyphens or underscores. Each operation has a unique `id`, an `operation` and an `input`. The whole request's format, base fields and required scopes are validated before the first write, then operations run in order; resource existence, domain ownership and remote state are checked as each one runs.\n\nReturns 200 when everything succeeds and 207 when any operation failed, is uncertain or was not executed. Each `outcome` is `succeeded`, `failed`, `uncertain` or `skipped`. Execution continues after ordinary failures and stops when a result is unclear; completed operations are not rolled back or retried automatically, and responses never include passwords.\n\nThe same API key, idempotency key and normalized operations replay the saved result; different content returns 409. After a timeout, first query `GET /batch/{requestId}` with the original key: it returns only the `running` / `completed` / `uncertain` state and timestamps, not the operations or results. `running` and `uncertain` never expire or re-run automatically. Even when it reports `completed`, still check every outcome in the original batch result; it does not mean every operation succeeded.\n\n### Interactive requests and documentation security\n\nAll examples use fictional data. The documentation never reads instance configuration, connected domains, mailbox passwords or API keys.\n\nInteractive requests go directly from your browser to this site, without a public request proxy. Keys are not kept after a page refresh; do not enter API keys on shared devices, and never put keys in URLs, code repositories or logs." }, "servers": [ { "url": "https://console.abnormalhq.com/api/v1", "description": "Abnormal management API" } ], "x-error-codes": [ { "code": "body_too_large", "statuses": [ 413 ], "area": "request", "meaning": "The request body is over 16 KiB (8 MiB for POST /emails and /emails/batch).", "action": "Send less per request; use several requests or a batch.", "retry": "no", "reserved": false }, { "code": "endpoint_retired", "statuses": [ 410 ], "area": "request", "meaning": "The operation was retired after its announced sunset date.", "action": "Use the replacement in `details.replacement`; see the API changelog.", "retry": "no", "reserved": true }, { "code": "field_retired", "statuses": [ 422 ], "area": "request", "meaning": "The request sent a field, query parameter or enum value retired after its sunset date.", "action": "Drop it or use `details.replacement`; `details.field` names it.", "retry": "no", "reserved": true }, { "code": "forbidden", "statuses": [ 403 ], "area": "request", "meaning": "The key lacks a scope the operation needs, or its owner's current role no longer allows it.", "action": "Create a key with the scope listed for the operation in the reference, owned by an account whose role allows it.", "retry": "no", "reserved": false }, { "code": "invalid_arguments", "statuses": [ 400 ], "area": "request", "meaning": "An MCP tool was called with arguments that are not a JSON object of the tool's own fields.", "action": "Pass exactly the fields in the tool's input schema.", "retry": "no", "reserved": false }, { "code": "invalid_id", "statuses": [ 400 ], "area": "request", "meaning": "An ID in the path or body is not in the format of a record ID.", "action": "Use the IDs the API returns.", "retry": "no", "reserved": false }, { "code": "invalid_json", "statuses": [ 400 ], "area": "request", "meaning": "The body is not valid JSON, or not a JSON object.", "action": "Send a JSON object.", "retry": "no", "reserved": false }, { "code": "invalid_query", "statuses": [ 400, 422 ], "area": "request", "meaning": "A query parameter is unknown, malformed or out of range.", "action": "Fix the parameter `details` names; the reference lists each operation's parameters and their ranges.", "retry": "no", "reserved": false }, { "code": "method_not_allowed", "statuses": [ 405 ], "area": "request", "meaning": "The path exists but not with this HTTP method.", "action": "Use one of the methods in the `Allow` header.", "retry": "no", "reserved": false }, { "code": "not_found", "statuses": [ 404 ], "area": "request", "meaning": "The record in the path does not exist in this workspace (or is in the recycle bin, for mailboxes).", "action": "Check the ID: paths take the record IDs the API returns, not addresses or domain names.", "retry": "no", "reserved": false }, { "code": "rate_limited", "statuses": [ 429 ], "area": "request", "meaning": "The key's (or the address's) rate limit is used up for this window; nothing was done.", "action": "Wait `Retry-After` seconds, then send the same request again. Use batches for bulk changes.", "retry": "after_wait", "reserved": false }, { "code": "unauthorized", "statuses": [ 401 ], "area": "request", "meaning": "No Bearer key was sent, or the key is unknown, expired, revoked or no longer valid for its owner.", "action": "Send a working key in `Authorization: Bearer`. Repeated invalid keys get the sending address rate-limited.", "retry": "no", "reserved": false }, { "code": "unknown_field", "statuses": [ 400 ], "area": "request", "meaning": "The body has a field the operation does not take.", "action": "Remove it; `details` names it.", "retry": "no", "reserved": false }, { "code": "unsupported_media_type", "statuses": [ 415 ], "area": "request", "meaning": "A request body was sent without `Content-Type: application/json`.", "action": "Send JSON with that content type.", "retry": "no", "reserved": false }, { "code": "alias_changed", "statuses": [ 409 ], "area": "domains", "meaning": "The alias domain changed while the request ran.", "action": "Read it again, then decide whether to repeat the request.", "retry": "after_checking", "reserved": false }, { "code": "alias_limit", "statuses": [ 409 ], "area": "domains", "meaning": "The domain already has the most alias domains allowed.", "action": "Remove one before adding another.", "retry": "no", "reserved": false }, { "code": "already_exists", "statuses": [ 409 ], "area": "domains", "meaning": "The domain, alias domain or address already exists (here, or claimed by another workspace).", "action": "Use the existing record, or choose another name.", "retry": "no", "reserved": false }, { "code": "dns_lookup_failed", "statuses": [ 502 ], "area": "domains", "meaning": "The DNS lookup for the ownership check failed; nothing was changed.", "action": "Try again later.", "retry": "after_wait", "reserved": false }, { "code": "domain_binding_conflict", "statuses": [ 409 ], "area": "domains", "meaning": "The domain's server binding is ambiguous or changed while the request ran.", "action": "Have an admin review the domain's binding, then try again.", "retry": "after_checking", "reserved": false }, { "code": "domain_changed", "statuses": [ 409 ], "area": "domains", "meaning": "The domain's binding changed while the request ran.", "action": "Read the domain again, then decide whether to repeat the request.", "retry": "after_checking", "reserved": false }, { "code": "domain_has_aliases", "statuses": [ 409 ], "area": "domains", "meaning": "The domain still has alias domains.", "action": "Remove its alias domains first.", "retry": "no", "reserved": false }, { "code": "domain_not_empty", "statuses": [ 409 ], "area": "domains", "meaning": "The domain still has local mailboxes, so its record cannot be removed.", "action": "Delete or move its mailboxes first.", "retry": "no", "reserved": false }, { "code": "domain_not_provisioned", "statuses": [ 409 ], "area": "domains", "meaning": "The domain to import is not on the chosen server.", "action": "Create it on that server first, or onboard it with `/domain-onboardings`.", "retry": "no", "reserved": false }, { "code": "domain_onboarding_conflict", "statuses": [ 409 ], "area": "domains", "meaning": "The domain's onboarding has not finished, or its state does not allow this step.", "action": "Read the onboarding's state and DNS status; never submit the remote provisioning twice.", "retry": "after_checking", "reserved": false }, { "code": "domain_ownership_required", "statuses": [ 403 ], "area": "domains", "meaning": "The domain cannot be imported without a verified ownership onboarding in this workspace.", "action": "Onboard it with `/domain-onboardings` instead.", "retry": "no", "reserved": false }, { "code": "domain_unbound", "statuses": [ 409 ], "area": "domains", "meaning": "The domain is not bound to a valid mail server, so nothing on it can be changed remotely.", "action": "Bind the domain to a server in the admin console.", "retry": "no", "reserved": false }, { "code": "invalid_domain", "statuses": [ 400 ], "area": "domains", "meaning": "The domain name is missing or not a valid name.", "action": "Send a lowercase domain name such as example.com.", "retry": "no", "reserved": false }, { "code": "invalid_domain_update", "statuses": [ 400 ], "area": "domains", "meaning": "The status change does not say whether to enable or disable the domain.", "action": "Send `{ \"enabled\": true }` or `{ \"enabled\": false }`.", "retry": "no", "reserved": false }, { "code": "ownership_unverified", "statuses": [ 409 ], "area": "domains", "meaning": "The ownership TXT record was not found with the expected value.", "action": "Publish the record the connection details show, wait for DNS, then verify again.", "retry": "after_wait", "reserved": false }, { "code": "remote_domain_delete_unavailable", "statuses": [ 422 ], "area": "domains", "meaning": "Deleting a domain on the mail server is not offered.", "action": "Disable the domain, then remove only the local record; the server keeps the domain and its data.", "retry": "no", "reserved": false }, { "code": "subscription_not_found", "statuses": [ 404 ], "area": "domains", "meaning": "The mail server in `subscriptionId` does not exist or is not available to this workspace.", "action": "Use an ID from `GET /servers`.", "retry": "no", "reserved": false }, { "code": "subscription_required", "statuses": [ 400 ], "area": "domains", "meaning": "Several mail servers are configured and the request does not say which one to use.", "action": "Send `subscriptionId` (one of `GET /servers`).", "retry": "no", "reserved": false }, { "code": "verification_expired", "statuses": [ 409 ], "area": "domains", "meaning": "The alias domain's ownership value expired before it was verified.", "action": "Remove the alias domain, add it again and publish the new value.", "retry": "no", "reserved": false }, { "code": "invalid_daily_limit", "statuses": [ 400 ], "area": "mailboxes", "meaning": "The daily sending limit is not an integer in range.", "action": "Send an integer from 0 to 1000000.", "retry": "no", "reserved": false }, { "code": "invalid_mailbox", "statuses": [ 422 ], "area": "mailboxes", "meaning": "The mailbox fields failed validation.", "action": "Fix the fields listed in `details.fields`.", "retry": "no", "reserved": false }, { "code": "invalid_mailbox_ids", "statuses": [ 400 ], "area": "mailboxes", "meaning": "The bulk sending-limit request does not name 1–100 distinct mailbox IDs.", "action": "Send between 1 and 100 distinct mailbox record IDs.", "retry": "no", "reserved": false }, { "code": "invalid_note", "statuses": [ 400, 422 ], "area": "mailboxes", "meaning": "The note (of a mailbox or a suppression) is too long or not text.", "action": "Send at most the documented number of characters.", "retry": "no", "reserved": false }, { "code": "invalid_password", "statuses": [ 400 ], "area": "mailboxes", "meaning": "The password is not 8–128 characters without whitespace.", "action": "Send a password that meets the rule.", "retry": "no", "reserved": false }, { "code": "invalid_quota", "statuses": [ 400 ], "area": "mailboxes", "meaning": "The quota is not a whole number of MB in range.", "action": "Send an integer from 0 (no limit) to the documented maximum.", "retry": "no", "reserved": false }, { "code": "invalid_status", "statuses": [ 400 ], "area": "mailboxes", "meaning": "The status is not one of `active`, `disabled` or `pending`.", "action": "Send one of those values.", "retry": "no", "reserved": false }, { "code": "invalid_username", "statuses": [ 400 ], "area": "mailboxes", "meaning": "The username (the part before @) is not valid.", "action": "Use 1–64 lowercase letters, digits, `.`, `_` or `-`, starting and ending with a letter or digit.", "retry": "no", "reserved": false }, { "code": "provisioning_uncertain", "statuses": [ 409 ], "area": "mailboxes", "meaning": "The mailbox write was sent to the server but its result is not confirmed; a pending record was kept.", "action": "Look the mailbox up with `details.mailboxId` and verify it; do not create it again.", "retry": "after_checking", "reserved": false }, { "code": "sending_limit_unavailable", "statuses": [ 422 ], "area": "mailboxes", "meaning": "A sending limit cannot be set for this mailbox (not created on the server yet, or not supported).", "action": "Create the mailbox first, or leave the limit to the server's default.", "retry": "no", "reserved": false }, { "code": "sending_limit_uncertain", "statuses": [ 409 ], "area": "mailboxes", "meaning": "The sending-limit write may or may not have been applied.", "action": "Read the limit back (GET); repeat only the same target value, never a different one, if it is not set.", "retry": "after_checking", "reserved": false }, { "code": "address_taken", "statuses": [ 409 ], "area": "addresses", "meaning": "The address is already used by a mailbox, service mailbox, alias, list, forwarder or a mailbox in the recycle bin.", "action": "Choose another address.", "retry": "no", "reserved": false }, { "code": "external_member", "statuses": [ 422 ], "area": "addresses", "meaning": "The list has members outside the workspace's domains, which this workspace does not allow.", "action": "Remove the outside addresses, or ask an admin to allow external members.", "retry": "no", "reserved": false }, { "code": "forwarding_loop", "statuses": [ 409 ], "area": "addresses", "meaning": "The rule forwards to itself or would close a loop with existing forwarding.", "action": "Choose a different destination.", "retry": "no", "reserved": false }, { "code": "invalid_alias", "statuses": [ 400 ], "area": "addresses", "meaning": "The alias fields are invalid.", "action": "Fix the username, target or description.", "retry": "no", "reserved": false }, { "code": "invalid_alias_target", "statuses": [ 409 ], "area": "addresses", "meaning": "The alias target is not an existing managed mailbox of the same domain.", "action": "Point the alias at a mailbox of its own domain.", "retry": "no", "reserved": false }, { "code": "invalid_catch_all", "statuses": [ 400 ], "area": "addresses", "meaning": "The catch-all setting is invalid.", "action": "Send a mailbox address of the domain, or null to reject mail to unknown addresses.", "retry": "no", "reserved": false }, { "code": "invalid_catch_all_destination", "statuses": [ 409 ], "area": "addresses", "meaning": "The catch-all destination is not an existing managed mailbox of this domain.", "action": "Use one of the domain's own mailboxes.", "retry": "no", "reserved": false }, { "code": "invalid_forwarder", "statuses": [ 400 ], "area": "addresses", "meaning": "The forwarding rule's source or destination is invalid.", "action": "Send one source address of the domain and one destination address.", "retry": "no", "reserved": false }, { "code": "invalid_list", "statuses": [ 400 ], "area": "addresses", "meaning": "The distribution list fields are invalid.", "action": "Fix the username, description or members.", "retry": "no", "reserved": false }, { "code": "list_limit", "statuses": [ 409 ], "area": "addresses", "meaning": "The domain already has the most distribution lists allowed.", "action": "Delete a list before creating another.", "retry": "no", "reserved": false }, { "code": "readonly_alias", "statuses": [ 409 ], "area": "addresses", "meaning": "This alias is a special one managed on the mail server (or a user's masked address) and cannot be changed here.", "action": "Leave it as it is.", "retry": "no", "reserved": false }, { "code": "readonly_forwarder", "statuses": [ 409 ], "area": "addresses", "meaning": "This rule is not managed here (a list, alias, catch-all or custom Sieve rule).", "action": "Change it where it is managed.", "retry": "no", "reserved": false }, { "code": "readonly_list", "statuses": [ 409 ], "area": "addresses", "meaning": "This list is managed on the mail server and cannot be changed here.", "action": "Leave it as it is.", "retry": "no", "reserved": false }, { "code": "unsupported", "statuses": [ 422 ], "area": "addresses", "meaning": "The domain's mail server does not support this kind of address management.", "action": "Use a Stalwart 1.0 or later server for the domain.", "retry": "no", "reserved": false }, { "code": "batch_stopped", "statuses": [ 424 ], "area": "batch", "meaning": "An item of a batch that was not run because an earlier item's outcome is unconfirmed (item `error.code`).", "action": "Verify the earlier item, then send this one again in a new batch.", "retry": "after_checking", "reserved": false }, { "code": "idempotency_conflict", "statuses": [ 409 ], "area": "batch", "meaning": "This idempotency key was already used, with this key, for a different batch (or follow-up task, or messages sent through /emails).", "action": "Use a new idempotency key for different content.", "retry": "no", "reserved": false }, { "code": "idempotency_running", "statuses": [ 409 ], "area": "batch", "meaning": "A batch with this idempotency key is still running.", "action": "Read its state with `GET /batch/{requestId}`; do not resend under another key.", "retry": "after_checking", "reserved": false }, { "code": "idempotency_uncertain", "statuses": [ 409 ], "area": "batch", "meaning": "A batch with this idempotency key stopped with an unconfirmed write.", "action": "Verify the affected records, then send only what is confirmed missing, in a new batch with a new key.", "retry": "after_checking", "reserved": false }, { "code": "invalid_batch", "statuses": [ 400 ], "area": "batch", "meaning": "The batch body is invalid: not 1–25 operations, duplicate item IDs, an unknown operation or bad input; for `POST /emails/batch`, `emails` is not a list of 1 to 50 messages.", "action": "Fix the batch; nothing in it was run or sent.", "retry": "no", "reserved": false }, { "code": "invalid_idempotency_key", "statuses": [ 400 ], "area": "batch", "meaning": "The `Idempotency-Key` header is missing or not 8–128 letters, digits, `-` or `_`.", "action": "Send a valid key, unique per batch.", "retry": "no", "reserved": false }, { "code": "request_budget_exceeded", "statuses": [ 422 ], "area": "batch", "meaning": "The batch reached its request budget on the mail server and the remaining operations were stopped.", "action": "Check the results, then send the rest in smaller batches.", "retry": "after_checking", "reserved": false }, { "code": "delivery_in_progress", "statuses": [ 409 ], "area": "webhooks", "meaning": "The delivery is still waiting for its own retry.", "action": "Only a delivered or dead-lettered delivery can be sent again; wait for it to settle.", "retry": "after_wait", "reserved": false }, { "code": "invalid_description", "statuses": [ 400 ], "area": "webhooks", "meaning": "The description is longer than 200 characters.", "action": "Shorten it.", "retry": "no", "reserved": false }, { "code": "invalid_enabled", "statuses": [ 400 ], "area": "webhooks", "meaning": "`enabled` is not a boolean.", "action": "Send true or false.", "retry": "no", "reserved": false }, { "code": "invalid_events", "statuses": [ 400 ], "area": "webhooks", "meaning": "The events list names an unknown event type.", "action": "Use the event types in the reference, or `[\"*\"]`.", "retry": "no", "reserved": false }, { "code": "invalid_webhook", "statuses": [ 400 ], "area": "webhooks", "meaning": "A webhook update changes nothing.", "action": "Send at least one of `url`, `description`, `events` and `enabled`.", "retry": "no", "reserved": false }, { "code": "invalid_webhook_format", "statuses": [ 400 ], "area": "webhooks", "meaning": "`format` is not standard, feishu or dingtalk, `botSecret` came without a bot format or is not one, or a PATCH tried to change either (they are set when the webhook is made).", "action": "Send one of the formats, and a bot's signing secret only with a bot format; to change the format, make a new webhook.", "retry": "no", "reserved": false }, { "code": "invalid_webhook_url", "statuses": [ 400 ], "area": "webhooks", "meaning": "The address is not https on the default port with a public host name, or, for a bot format, not that bot platform's webhook address.", "action": "Use a public https address without credentials, IP literal or internal name.", "retry": "no", "reserved": false }, { "code": "webhook_limit", "statuses": [ 409 ], "area": "webhooks", "meaning": "The workspace already has the most webhooks allowed (10).", "action": "Delete one before creating another.", "retry": "no", "reserved": false }, { "code": "hold_not_active", "statuses": [ 409 ], "area": "compliance", "meaning": "The legal hold was already released or has ended.", "action": "Nothing to release; place a new hold if needed.", "retry": "no", "reserved": false }, { "code": "invalid_address", "statuses": [ 422 ], "area": "compliance", "meaning": "The suppression list address is not a valid email address.", "action": "Send one valid address.", "retry": "no", "reserved": false }, { "code": "invalid_ends_at", "statuses": [ 400 ], "area": "compliance", "meaning": "The hold's end date is not a future ISO 8601 time.", "action": "Send a future date, or none.", "retry": "no", "reserved": false }, { "code": "invalid_reason", "statuses": [ 400 ], "area": "compliance", "meaning": "The required reason is missing or too long.", "action": "Send a reason.", "retry": "no", "reserved": false }, { "code": "missing_criteria", "statuses": [ 400 ], "area": "trace", "meaning": "A trace search names none of sender, recipient, Message-ID or queue ID.", "action": "Give at least one of them.", "retry": "no", "reserved": false }, { "code": "trace_unavailable", "statuses": [ 409 ], "area": "trace", "meaning": "No mail server whose logs can be read is configured.", "action": "Ask an admin to connect a mail server.", "retry": "no", "reserved": false }, { "code": "already_decided", "statuses": [ 409 ], "area": "agent_tasks", "meaning": "This email awaiting approval was already approved or rejected.", "action": "Read the task's approvals again.", "retry": "no", "reserved": false }, { "code": "auto_send_disabled", "statuses": [ 409 ], "area": "agent_tasks", "meaning": "An admin switched automatic sending off, so every email of a task needs approval.", "action": "Create the task with approval required, or ask an admin.", "retry": "no", "reserved": false }, { "code": "invalid_agent_task", "statuses": [ 400, 422 ], "area": "agent_tasks", "meaning": "The follow-up task's fields are invalid.", "action": "Fix what the message describes.", "retry": "no", "reserved": false }, { "code": "invalid_state", "statuses": [ 409 ], "area": "agent_tasks", "meaning": "The task is not in a state that allows this (only a running task can be paused, a paused one resumed).", "action": "Read the task's state first.", "retry": "after_checking", "reserved": false }, { "code": "mailbox_unavailable", "statuses": [ 409 ], "area": "agent_tasks", "meaning": "The task's mailbox cannot be used (disabled, no stored password, or its domain has no mail server).", "action": "Fix the mailbox, or use another one.", "retry": "no", "reserved": false }, { "code": "task_finished", "statuses": [ 409 ], "area": "agent_tasks", "meaning": "The task has already ended.", "action": "Create a new task if more follow-up is needed.", "retry": "no", "reserved": false }, { "code": "attachments_too_large", "statuses": [ 413 ], "area": "emails", "meaning": "The attachments are over 5 MiB in all, decoded.", "action": "Send smaller files, or a link to them.", "retry": "no", "reserved": false }, { "code": "billing_required", "statuses": [ 402 ], "area": "emails", "meaning": "The workspace's plan bills sending through the API, and the workspace has no subscription that may send (none, canceled, unpaid).", "action": "An admin subscribes, or fixes the payment, under Settings → Developers → Billing. `details.status` is the subscription's Stripe status.", "retry": "no", "reserved": false }, { "code": "domain_not_sending", "statuses": [ 409 ], "area": "emails", "meaning": "The domain does not send through the API, so it has no sending account to make SMTP relay credentials for.", "action": "Turn sending on for the domain (`PUT /domains/{id}/sending`) first.", "retry": "no", "reserved": false }, { "code": "email_api_not_approved", "statuses": [ 403 ], "area": "emails", "meaning": "Sending through the API is not turned on for this workspace: a platform admin has not approved it.", "action": "Ask the platform's operator to approve it (with a daily limit). Test keys can send to the sandbox meanwhile.", "retry": "no", "reserved": false }, { "code": "email_api_paused", "statuses": [ 403 ], "area": "emails", "meaning": "Live sending is paused for the workspace: in the last 7 days (or since it was last resumed) too many recipients bounced or complained. `details.reason` says which, `details.pausedAt` since when.", "action": "Find out why (a stale list, a missing unsubscribe, a stolen key) and fix it, then ask the platform's operator to resume sending. Test keys still send to the sandbox.", "retry": "no", "reserved": false }, { "code": "email_daily_limit", "statuses": [ 429 ], "area": "emails", "meaning": "The workspace's daily allowance of messages is used up (a batch counts all of its messages).", "action": "Send again after `details.resetAt` (midnight UTC), or ask for a higher limit. Nothing of the request was sent.", "retry": "after_wait", "reserved": false }, { "code": "from_domain_not_sending", "statuses": [ 422 ], "area": "emails", "meaning": "The From address is not on a domain of this workspace that sends through the API.", "action": "Turn sending on for the domain (`PUT /domains/{id}/sending`), or send from a domain that has it. `details.index` names the message in a batch.", "retry": "no", "reserved": false }, { "code": "invalid_agent_name", "statuses": [ 400 ], "area": "emails", "meaning": "An agent mailbox's `name` is not a single line of at most 200 characters without quotes or angle brackets.", "action": "Fix it.", "retry": "no", "reserved": false }, { "code": "invalid_attachments", "statuses": [ 400 ], "area": "emails", "meaning": "An attachment is malformed: no filename, content that is not base64, a bad content type, or more than 10 attachments.", "action": "Fix the attachments.", "retry": "no", "reserved": false }, { "code": "invalid_body", "statuses": [ 400 ], "area": "emails", "meaning": "The message has neither `text` nor `html`, or one of them is too long.", "action": "Send `text`, `html` or both, within the documented sizes.", "retry": "no", "reserved": false }, { "code": "invalid_from", "statuses": [ 400 ], "area": "emails", "meaning": "`from` is not an address or `Name
`.", "action": "Fix it.", "retry": "no", "reserved": false }, { "code": "invalid_headers", "statuses": [ 400 ], "area": "emails", "meaning": "`headers` holds a header that is not allowed (only X- headers, List-Unsubscribe and List-Unsubscribe-Post), repeats one, or has a multi-line value.", "action": "Fix the headers.", "retry": "no", "reserved": false }, { "code": "invalid_mail_app", "statuses": [ 400 ], "area": "emails", "meaning": "A mail app needs a name, 1 to 5 redirect URIs (https on a public host, or http on the loopback) and scopes from mail.read, mail.send and mail.modify.", "action": "Fix the app.", "retry": "no", "reserved": false }, { "code": "invalid_message_change", "statuses": [ 400 ], "area": "emails", "meaning": "A change to an agent mailbox's message needs `read` and/or `flagged`, each true or false, and nothing else.", "action": "Send `{ \"read\": true }`, `{ \"flagged\": false }` or both.", "retry": "no", "reserved": false }, { "code": "invalid_recipients", "statuses": [ 400 ], "area": "emails", "meaning": "`to`, `cc`, `bcc` or `replyTo` holds something that is not an address, or the message has no recipient or more than 50.", "action": "Fix the lists; send to more people in several messages or a batch.", "retry": "no", "reserved": false }, { "code": "invalid_smtp_credential", "statuses": [ 400 ], "area": "emails", "meaning": "An SMTP relay credential needs a name: one line of at most 100 characters.", "action": "Name what the credential is for (the application that will use it).", "retry": "no", "reserved": false }, { "code": "invalid_subject", "statuses": [ 400 ], "area": "emails", "meaning": "`subject` is missing, empty, over 500 characters or not a single line.", "action": "Fix it.", "retry": "no", "reserved": false }, { "code": "invalid_tags", "statuses": [ 400 ], "area": "emails", "meaning": "`tags` is not an object of up to 10 names with string values.", "action": "Fix the tags.", "retry": "no", "reserved": false }, { "code": "key_mailbox_restricted", "statuses": [ 403 ], "area": "emails", "meaning": "A key restricted to one agent mailbox called something other than that mailbox's own paths.", "action": "Use the key only for `/agent-mailboxes/{its id}` and the paths under it (not `/keys`, not DELETE); use another key for the rest.", "retry": "no", "reserved": false }, { "code": "mail_app_limit", "statuses": [ 409 ], "area": "emails", "meaning": "The workspace already has 20 mail apps that are not revoked.", "action": "Revoke one first (DELETE /mail-apps/{id}).", "retry": "no", "reserved": false }, { "code": "mailbox_unreadable", "statuses": [ 409 ], "area": "emails", "meaning": "The mailbox cannot be read for inbound routing: it is not active, or has no stored password.", "action": "Use an active mailbox with a stored password (created through the console or the API).", "retry": "no", "reserved": false }, { "code": "nothing_to_reply_to", "statuses": [ 422 ], "area": "emails", "meaning": "The message has no Reply-To or From address other than the agent's own.", "action": "Send a new message with POST /agent-mailboxes/{id}/send instead.", "retry": "no", "reserved": false }, { "code": "smtp_credential_limit", "statuses": [ 409 ], "area": "emails", "meaning": "The domain already has 10 SMTP relay credentials in use.", "action": "Revoke one you no longer need (`DELETE /domains/{id}/smtp-credentials/{credentialId}`).", "retry": "no", "reserved": false }, { "code": "sandbox_domain_zone", "statuses": [ 422 ], "area": "test_mode", "meaning": "A test key asked for a domain outside its sandbox's zone (.test).", "action": "Use a name under the zone `GET /capabilities` reports in `sandbox.domainZone`.", "retry": "no", "reserved": false }, { "code": "test_mode_unsupported", "statuses": [ 403 ], "area": "test_mode", "meaning": "A test key called an endpoint that needs real mail (message trace, follow-up tasks, transport security).", "action": "Use a live key for it. `GET /capabilities` lists these paths under `sandbox.unsupportedPaths`.", "retry": "no", "reserved": false }, { "code": "service_unavailable", "statuses": [ 503 ], "area": "upstream", "meaning": "The service or its mail server configuration is unavailable.", "action": "Try again later; read the current state before repeating a write.", "retry": "after_checking", "reserved": false }, { "code": "upstream_error", "statuses": [ 502 ], "area": "upstream", "meaning": "The mail server refused or failed the request.", "action": "Read the current state before repeating a write; try reads again later.", "retry": "after_checking", "reserved": false } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Capabilities", "description": "Boundaries of the current API." }, { "name": "Domain onboarding", "description": "Provision a domain after verifying ownership, or look up / cancel pending requests." }, { "name": "Domains", "description": "Import existing Stalwart domains and manage local records." }, { "name": "Mailboxes", "description": "Manage mailboxes; passwords and redemption-code links are never returned." }, { "name": "Forwarders", "description": "Forwarding rules between single regular email addresses." }, { "name": "Aliases", "description": "Regular aliases delivering to managed mailboxes on the same domain." }, { "name": "Lists", "description": "Distribution lists: an address of a domain that delivers to all of its members." }, { "name": "Legal holds", "description": "Legal holds: a held mailbox cannot be deleted permanently or purged. A hold preserves the mailbox, not individual messages." }, { "name": "Reports", "description": "Usage reports: inactive mailboxes, storage per domain, top senders. Computed from this app's own records." }, { "name": "Batch", "description": "Manage domains, mailboxes and aliases in ordered batches with persisted idempotent results." }, { "name": "Agent tasks", "description": "An agent follows up email as a given mailbox: it starts from a prompt, sends fully autonomously by default, and continues when replies arrive." }, { "name": "Webhooks", "description": "Signed event webhooks: mailbox, domain, order, bulk job and security events POSTed to your https address, with retries and a delivery log." }, { "name": "Trace", "description": "Message trace: the delivery timeline of messages sent or received by the workspace's domains, read from the mail server's logs and queue. Every call is recorded in the activity log." }, { "name": "Emails", "description": "Send mail from the workspace's domains through their own mail server, and follow each message's delivery. Off until a platform admin approves the workspace; test keys send to the sandbox." }, { "name": "Inbound", "description": "Inbound routing: mail that chosen mailboxes receive is POSTed to webhooks as message.received, and can be read through the API." }, { "name": "Agent mailboxes", "description": "A mailbox an AI agent reads and sends from, made in one call, and a key restricted to just that mailbox for the agent itself." }, { "name": "Mail apps", "description": "Third-party apps a workspace registers so its mailbox users can authorize them, with OAuth on WebMail, to read their mail or send as them through WebMail's Mail API." }, { "name": "Suppressions", "description": "The workspace's suppression list: recipients that hard-bounced repeatedly or were added by hand. Advisory: nothing is refused at submission; check an address before sending to it." } ], "paths": { "/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Get API capabilities", "description": "Requires `domains:read` scope.", "tags": [ "Capabilities" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Capabilities" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/servers": { "get": { "operationId": "listServers", "summary": "List available mail servers", "description": "Requires `domains:read` scope.", "tags": [ "Domain onboarding" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:read" ], "parameters": [ { "name": "domains", "in": "query", "description": "false leaves each server's domain names out (domainCount stays); list them a page at a time with listDomains, whose items carry subscriptionId.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Server" } } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domain-onboardings": { "get": { "operationId": "listDomainOnboardings", "summary": "List domain onboarding requests", "description": "Requires `domains:read` scope.\n\nRequests newest first. Bulk onboarding leaves thousands: pass page and/or perPage to read them a page at a time, with pagination in the response. Without either the response holds every request and no pagination.", "tags": [ "Domain onboarding" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:read" ], "parameters": [ { "name": "page", "in": "query", "description": "Page through the requests, newest first. Without page and perPage every request is returned at once.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainOnboardingListResponse" } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createDomainOnboarding", "summary": "Request verification and provisioning of a domain", "description": "Requires `domains:write` scope.\n\nCreates a domain ownership verification request and returns the DNS TXT record to publish; nothing is provisioned upstream yet.", "tags": [ "Domain onboarding" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainOnboardingInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainConnection" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domain-onboardings/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Domain onboarding request ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getDomainOnboarding", "summary": "Get a domain onboarding request", "description": "Requires `domains:read` scope.", "tags": [ "Domain onboarding" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainConnection" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "cancelDomainOnboarding", "summary": "Cancel an unsubmitted domain request", "description": "Requires `domains:write` scope.\n\nOnly pending requests not yet submitted upstream can be cancelled. Cannot be used to delete a provisioned domain.", "tags": [ "Domain onboarding" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletedResource" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domain-onboardings/{id}/verify": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Domain onboarding request ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "verifyDomainOnboarding", "summary": "Verify TXT and provision the domain", "description": "Requires `domains:write` scope.\n\nNo request body. Publish the DNS TXT record required by the request first, then call this endpoint. If provisioning is unconfirmed it returns 409 domain_onboarding_conflict; check the request state first instead of retrying blindly.", "tags": [ "Domain onboarding" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainConnection" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domain-onboardings/{id}/refresh": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Domain onboarding request ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "refreshDomainOnboarding", "summary": "Regenerate the ownership verification record", "description": "Requires `domains:write` scope.\n\nNo request body. Returns a new ownership verification record; update DNS with the new value, then verify. Only applies to requests not yet submitted upstream.", "tags": [ "Domain onboarding" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainConnection" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains": { "get": { "operationId": "listDomains", "summary": "List domains", "description": "Requires `domains:read` scope.\n\nDomains by name. A workspace can have thousands: pass page and/or perPage to read them a page at a time, with pagination in the response (as for the mailbox list). Without either the response holds every domain and no pagination.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:read" ], "parameters": [ { "name": "page", "in": "query", "description": "Page through the domains by name. Without page and perPage every domain is returned at once.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainListResponse" }, "example": { "data": [ { "id": "domainexample01", "name": "example.com", "created": "2026-01-01 00:00:00.000Z", "subscriptionId": null } ], "pagination": { "page": 1, "perPage": 50, "total": 1, "totalPages": 1 } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "importDomain", "summary": "Import an existing domain", "description": "Requires `domains:write` scope.\n\nImports a domain that already exists on a configured Stalwart server into MailHQ. This does not register the domain or create it upstream.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportDomainInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Domain" } }, "required": [ "data" ] }, "example": { "data": { "id": "domainexample01", "name": "example.com", "created": "2026-01-01 00:00:00.000Z", "subscriptionId": null } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getDomain", "summary": "Get a domain", "description": "Requires `domains:read` scope.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Domain" } }, "required": [ "data" ] }, "example": { "data": { "id": "domainexample01", "name": "example.com", "created": "2026-01-01 00:00:00.000Z", "subscriptionId": null } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "removeDomain", "summary": "Remove the local domain record", "description": "Requires `domains:write` scope.\n\nOnly removes the MailHQ local record; the upstream Stalwart domain is not deleted. Domains with local mailboxes cannot be removed and return 409.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletedResource" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/connection": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getDomainConnection", "summary": "Get domain connection and DNS status", "description": "Requires `domains:read` scope.\n\nReturns the domain's connection, DNS and recorded ownership status. DNS results do not guarantee mail delivery.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainConnection" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/status": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "put": { "operationId": "setDomainStatus", "summary": "Enable or disable a domain", "description": "Requires `domains:write` scope.\n\nEnables or disables a bound domain on Stalwart. Does not delete the domain, mailboxes or mail data; requires the admin role.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainStatus" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/catch-all": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getDomainCatchAll", "summary": "Get a domain's catch-all", "description": "Requires `domains:read` scope.\n\nThe mailbox that receives mail for addresses of the domain nobody holds; destination null means such mail is rejected, the default.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainCatchAll" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "setDomainCatchAll", "summary": "Set or clear a domain's catch-all", "description": "Requires `domains:write` scope.\n\nA catch-all accepts every guessed or mistyped address of the domain: expect noticeably more spam in the destination mailbox, counted against its quota, and senders no longer get a bounce for an address that does not exist. Any other destination (another domain, an external address, a list) answers 409 invalid_catch_all_destination. Requires the admin role.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "destination": { "type": [ "string", "null" ], "format": "email", "maxLength": 254, "description": "An existing mailbox managed by MailHQ on the same domain (not pending), or null to reject mail to unknown addresses.", "example": "postmaster@example.com" } }, "required": [ "destination" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainCatchAll" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/domain-aliases": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "listDomainAliases", "summary": "List a domain's alias domains", "description": "Requires `domains:read` scope.\n\nAlias domains of this (primary) domain: every address of an alias domain delivers to the same local part of the primary domain. Read from MailHQ's records, without contacting the mail server.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DomainAlias" } } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "requestDomainAlias", "summary": "Request an alias domain", "description": "Requires `domains:write` scope.\n\nRecords the request and returns the TXT record that proves ownership of the alias domain; nothing is changed on the mail server until verifyDomainAlias passes. The name must not be a domain, an onboarding request or an alias in any workspace (409 already_exists). Repeating the request for the same primary domain returns the existing one. A domain has at most 20 alias domains; they do not count towards the workspace's domain limit. Requires the admin role.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "domain": { "type": "string", "maxLength": 253, "example": "example.net" } }, "required": [ "domain" ] } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainAliasDetails" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/domain-aliases/{aliasId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "aliasId", "in": "path", "required": true, "description": "MailHQ record ID of the domain alias, as returned by listDomainAliases.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getDomainAlias", "summary": "Get an alias domain and its DNS status", "description": "Requires `domains:read` scope.\n\nThe alias with the records it needs and what public DNS answers: the ownership TXT (required until verified), the MX that lets the alias domain receive mail (required) and the primary domain's SPF (optional). There is no DKIM record: mail sent from an alias-domain address is signed with the primary domain's key.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainAliasDetails" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "removeDomainAlias", "summary": "Remove an alias domain", "description": "Requires `domains:write` scope.\n\nA pending request is deleted. An alias that reached the mail server is first removed from the primary domain there, then its record is deleted and the name is free again. The primary domain, its mailboxes and their mail are not touched.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletedResource" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/domain-aliases/{aliasId}/verify": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "aliasId", "in": "path", "required": true, "description": "MailHQ record ID of the domain alias, as returned by listDomainAliases.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "verifyDomainAlias", "summary": "Verify ownership and add the alias domain", "description": "Requires `domains:write` scope.\n\nLooks up the ownership TXT in public DNS (409 ownership_unverified while it is missing, 409 verification_expired after 7 days), then adds the name to the primary domain's aliases on its mail server; no request body. Safe to repeat: an active alias is only re-read. state uncertain means a server write could not be confirmed: call this again, which reads the server first, rather than changing the domain in Stalwart.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainAliasDetails" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/transport-security": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "prepareDomainTransportSecurity", "summary": "Verify and enable domain transport security", "description": "Requires `domains:write` scope.\n\nVerifies and prepares MTA-STS and TLS-RPT for a bound domain using the server preset; no request body. Publish the DNS records returned by connection first, then call this endpoint; no certificate is requested while the host DNS does not match. A 200 response means the check has finished; only transportSecurity.state=ready means DNS, the HTTPS policy and the certificate are all ready. A call made before the host DNS matches does nothing: after dns_pending, wait until DNS matches (connection then shows needs_setup) and call this endpoint again; on certificate_pending, query connection again. The top-level ready field only means mail DNS is ready. Requires the admin role and the domains:write scope.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "domains:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainConnection" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes": { "get": { "operationId": "listMailboxes", "summary": "List mailboxes", "description": "Requires `mailboxes:read` scope.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:read" ], "parameters": [ { "name": "domain", "in": "query", "description": "Filter by domain.", "schema": { "type": "string" }, "example": "example.com" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/MailboxStatus" } }, { "name": "q", "in": "query", "description": "Mailbox search term.", "schema": { "type": "string", "maxLength": 100 }, "example": "support" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxListResponse" }, "example": { "data": [ { "id": "mailboxexample1", "domain": "example.com", "username": "support", "email": "support@example.com", "status": "active", "note": "Support mailbox", "quotaMb": 1024, "usageMb": null, "usageSyncedAt": null, "mailTotal": null, "mailUnseen": null, "mailSyncedAt": null, "created": "2026-01-01 00:00:00.000Z", "updated": "2026-01-01 00:00:00.000Z" } ], "pagination": { "page": 1, "perPage": 50, "total": 1, "totalPages": 1 } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createMailbox", "summary": "Create a mailbox", "description": "Requires `mailboxes:write` scope.\n\nIf the upstream creation result is unclear it returns 409 with error.code provisioning_uncertain, and details.mailboxId points to the reserved pending mailbox. Look up and manually verify that mailbox; do not recreate it or retry blindly.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMailboxInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Mailbox" } }, "required": [ "data" ] }, "example": { "data": { "id": "mailboxexample1", "domain": "example.com", "username": "support", "email": "support@example.com", "status": "active", "note": "Support mailbox", "quotaMb": 1024, "usageMb": null, "usageSyncedAt": null, "mailTotal": null, "mailUnseen": null, "mailSyncedAt": null, "created": "2026-01-01 00:00:00.000Z", "updated": "2026-01-01 00:00:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ mailbox record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getMailbox", "summary": "Get a mailbox", "description": "Requires `mailboxes:read` scope.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Mailbox" } }, "required": [ "data" ] }, "example": { "data": { "id": "mailboxexample1", "domain": "example.com", "username": "support", "email": "support@example.com", "status": "active", "note": "Support mailbox", "quotaMb": 1024, "usageMb": null, "usageSyncedAt": null, "mailTotal": null, "mailUnseen": null, "mailSyncedAt": null, "created": "2026-01-01 00:00:00.000Z", "updated": "2026-01-01 00:00:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteMailbox", "summary": "Delete a mailbox", "description": "Requires `mailboxes:write` scope.\n\nBy default the mailbox moves to the recycle bin (see listDeletedMailboxes): it can no longer sign in, mail sent to it is rejected, its address stays reserved, and it can be restored with restoreMailbox until purgeAfter, when it and its mail are deleted for good. To every other operation it no longer exists (404). The delete is permanent at once, with permanent: true and purgeAfter: null in the response, when permanent=true is passed, when the workspace's retention is 0 days, and for a pending mailbox, which has nothing on the server to keep. A permanent delete is destructive: confirm the target mailbox before calling, and back up any mail you need to keep. The response keeps the earlier id and deleted: true fields.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:write" ], "parameters": [ { "name": "permanent", "in": "query", "description": "true deletes the mailbox and its mail for good at once, and is the only delete that acts on a mailbox already in the recycle bin. Absent or false moves it to the recycle bin for the workspace's retention period.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletedMailboxResult" } }, "required": [ "data" ] }, "example": { "data": { "id": "mailboxexample1", "deleted": true, "permanent": false, "purgeAfter": "2026-12-10T08:00:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/deleted": { "get": { "operationId": "listDeletedMailboxes", "summary": "List deleted mailboxes", "description": "Requires `mailboxes:read` scope.\n\nThe recycle bin: mailboxes that were deleted and are kept until purgeAfter, most recently deleted first, with who deleted each one. They are not part of listMailboxes.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:read" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedMailboxListResponse" } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/{id}/restore": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ mailbox record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "restoreMailbox", "summary": "Restore a deleted mailbox", "description": "Requires `mailboxes:write` scope.\n\nBrings a mailbox back from the recycle bin with its mail, in the status it had when it was deleted. Takes no request body. 404 when the id is not in the recycle bin. 422 when the mailbox was deleted from the shop account and its redeem code has no use left. 409 with error.code provisioning_uncertain when the mailbox was restored but could not be re-enabled: it exists again as disabled; check it with getMailbox and enable it with setMailboxStatus rather than calling restore again.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Mailbox" } }, "required": [ "data" ] }, "example": { "data": { "id": "mailboxexample1", "domain": "example.com", "username": "support", "email": "support@example.com", "status": "active", "note": "Support mailbox", "quotaMb": 1024, "usageMb": null, "usageSyncedAt": null, "mailTotal": null, "mailUnseen": null, "mailSyncedAt": null, "created": "2026-01-01 00:00:00.000Z", "updated": "2026-01-01 00:00:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/{id}/password": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ mailbox record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "put": { "operationId": "changeMailboxPassword", "summary": "Change mailbox password", "description": "Requires `mailboxes:write` scope.\n\nUse the new password in mail clients after updating. The response still does not include the password.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordInput" } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Mailbox" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/{id}/status": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ mailbox record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "put": { "operationId": "setMailboxStatus", "summary": "Change mailbox status", "description": "Requires `mailboxes:write` scope.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "status": { "$ref": "#/components/schemas/MailboxStatus" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Mailbox" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/{id}/quota": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ mailbox record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "put": { "operationId": "setMailboxQuota", "summary": "Change mailbox quota", "description": "Requires `mailboxes:write` scope.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "quotaMb": { "type": "integer", "minimum": 0, "maximum": 10485760, "description": "Quota in MB; 0 means no per-mailbox quota." } }, "required": [ "quotaMb" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Mailbox" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/sending-limits": { "post": { "operationId": "setMailboxSendingLimits", "summary": "Set daily sending limits for multiple mailboxes", "description": "Requires `mailboxes:write` scope.\n\nProvide 1–100 distinct mailbox IDs. After validating the complete request, apply the same limit to each mailbox independently. A failed or uncertain item does not stop the others. Returns 200 when all succeed, or 207 otherwise. Successful changes are not rolled back and requests are not automatically retried. When uncertain is true, verify that mailbox before submitting again; do not repeat the whole list.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "minItems": 1, "maxItems": 100, "uniqueItems": true }, "dailyLimit": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, "required": [ "ids", "dailyLimit" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SendingLimitsResult" } }, "required": [ "data" ] } } } }, "207": { "description": "Some mailbox changes did not succeed; see the per-mailbox results.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SendingLimitsResult" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/{id}/sending-limit": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ mailbox record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getMailboxSendingLimit", "summary": "Get a mailbox's daily sending limit", "description": "Requires `mailboxes:read` scope.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SendingLimit" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "setMailboxSendingLimit", "summary": "Set a mailbox's daily sending limit", "description": "Requires `mailboxes:write` scope.\n\nLimits how many messages the authenticated mailbox can submit through WebMail, the admin and external SMTP combined; the count resets daily at 00:00 UTC. 0 removes this system's limit and keeps other policies. Changing the limit restarts the count; external clients need to reconnect. An unknown result returns 409: GET to verify first and do not resend automatically.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "dailyLimit": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, "required": [ "dailyLimit" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SendingLimit" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/{id}/note": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ mailbox record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "put": { "operationId": "setMailboxNote", "summary": "Change mailbox note", "description": "Requires `mailboxes:write` scope.", "tags": [ "Mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "note": { "type": "string", "maxLength": 500, "description": "Mailbox note; surrounding whitespace is removed before saving, and the rest can be at most 500 characters." } }, "required": [ "note" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Mailbox" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/forwarders": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "listForwarders", "summary": "List forwarding rules", "description": "Requires `forwarders:read` scope.", "tags": [ "Forwarders" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "forwarders:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Forwarder" } } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createForwarder", "summary": "Create a forwarding rule", "description": "Requires `forwarders:write` scope.\n\nOnly one regular destination address is supported. Wildcards, file paths, pipes, multiple destinations and catch-all are not supported. A successful response returns source and destinations; to get the rule ID, query the GET list.", "tags": [ "Forwarders" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "forwarders:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateForwarderInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreatedForwarder" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/forwarders/{forwarderId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "forwarderId", "in": "path", "required": true, "description": "Forwarding rule ID.", "schema": { "type": "string", "minLength": 1 } } ], "delete": { "operationId": "deleteForwarder", "summary": "Delete a forwarding rule", "description": "Requires `forwarders:write` scope.", "tags": [ "Forwarders" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "forwarders:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletedResource" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/aliases": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "listAliases", "summary": "List regular aliases", "description": "Requires `aliases:read` scope.", "tags": [ "Aliases" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "aliases:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Alias" } } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createAlias", "summary": "Create a regular alias", "description": "Requires `aliases:write` scope.\n\nThe target must be an existing managed user mailbox on the same domain. Admins only; does not create external forwarding or catch-all.", "tags": [ "Aliases" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "aliases:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAliasInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Alias" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/aliases/{aliasId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "aliasId", "in": "path", "required": true, "description": "Opaque ID returned by the alias list; URL-encode it in the path.", "schema": { "type": "string", "pattern": "^alias:[A-Za-z0-9_-]{1,1024}$", "description": "Opaque alias ID; use the value returned by the list as-is and URL-encode it in paths." } } ], "get": { "operationId": "getAlias", "summary": "Get a regular alias", "description": "Requires `aliases:read` scope.", "tags": [ "Aliases" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "aliases:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Alias" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateAlias", "summary": "Update a regular alias", "description": "Requires `aliases:write` scope.\n\nProvide at least one of username, enabled or description. The target mailbox cannot be changed; special or read-only aliases cannot be modified.", "tags": [ "Aliases" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "aliases:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAliasInput" } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Alias" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteAlias", "summary": "Delete a regular alias", "description": "Requires `aliases:write` scope.\n\nDeletes the alias, not the target mailbox or its mail. Special or read-only aliases cannot be deleted.", "tags": [ "Aliases" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "aliases:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletedAlias" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lists": { "get": { "operationId": "listLists", "summary": "List distribution lists", "description": "Requires `lists:read` scope.\n\nThe distribution lists of one domain, with their members. Forwarding addresses (see listForwarders) are not lists and are not returned.", "tags": [ "Lists" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "lists:read" ], "parameters": [ { "name": "domainId", "in": "query", "required": true, "description": "MailHQ domain record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "q", "in": "query", "description": "Only lists whose address, description or members contain this text.", "schema": { "type": "string", "maxLength": 254 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/List" } } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createList", "summary": "Create a distribution list", "description": "Requires `lists:write` scope.\n\nCreates an address on the domain that delivers a copy of every message to all members. The address must not be held by a mailbox (pending and deleted ones included), a service mailbox, an alias, a forwarding address or another list (409). Members outside the workspace's managed mailboxes are refused with 422 external_member unless allowExternal is true. A member cannot be another list or a forwarding address. Lists do not count towards the workspace's mailbox limit. Admins only.", "tags": [ "Lists" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "lists:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateListInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/List" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lists/{listId}": { "parameters": [ { "name": "listId", "in": "path", "required": true, "description": "Opaque ID returned by listLists or createList.", "schema": { "type": "string", "pattern": "^list_[a-z0-9]{15}_[A-Za-z0-9_-]{1,128}$", "description": "Opaque distribution list ID; use the value returned by the list as-is." } } ], "get": { "operationId": "getList", "summary": "Get a distribution list", "description": "Requires `lists:read` scope.", "tags": [ "Lists" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "lists:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/List" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateList", "summary": "Update a distribution list", "description": "Requires `lists:write` scope.\n\nRenames the list (username), changes its description, and adds or removes members; provide at least one of them. Renaming applies the same address checks as creating. A list keeps at least one member: delete the list instead of removing the last one. Removing an address that is not a member fails with 502 and changes nothing. Read-only lists (409 readonly_list) are managed in Stalwart.", "tags": [ "Lists" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "lists:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateListInput" } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/List" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteList", "summary": "Delete a distribution list", "description": "Requires `lists:write` scope.\n\nDeletes the list address. The members' mailboxes and mail are not touched.", "tags": [ "Lists" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "lists:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletedList" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/holds": { "get": { "operationId": "listHolds", "summary": "List legal holds", "description": "Requires `holds:read` scope.\n\nActive holds first, then the most recently placed. Holds are never deleted. Admins only.", "tags": [ "Legal holds" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "holds:read" ], "parameters": [ { "name": "status", "in": "query", "description": "active: only holds that apply now. all (default): released and ended holds too.", "schema": { "type": "string", "enum": [ "active", "all" ], "default": "all" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoldListResponse" } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "placeHold", "summary": "Place a legal hold", "description": "Requires `holds:write` scope.\n\nPlaces a hold on one mailbox (mailboxId; a mailbox in the recycle bin can be held too) or on every mailbox of a domain (domain; mailboxes created later are covered as well). Give exactly one of the two. While a hold is active the mailbox cannot be deleted permanently or purged from the recycle bin by anyone or any job (409 legal_hold); deleting it into the recycle bin is still allowed and keeps the hold. A hold preserves the mailbox, not individual messages: the mailbox's user can still delete their own mail, and the mail server still empties Deleted Items and Junk Mail on its own schedule. This is not a certified archive. Recorded in the activity log with the name and the reason. Admins only.", "tags": [ "Legal holds" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "holds:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceHoldInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Hold" } }, "required": [ "data" ] }, "example": { "data": { "id": "holdexample0001", "name": "2026 employment dispute", "reason": "Case 2026-114; requested by legal", "scope": "mailbox", "mailboxId": "mailboxexample1", "target": "support@example.com", "endsAt": null, "placedBy": "admin@example.com", "placedAt": "2026-11-11T08:00:00.000Z", "releasedAt": null, "releasedBy": "", "releaseReason": "", "status": "active" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/holds/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Hold ID returned by listHolds or placeHold.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getHold", "summary": "Get a legal hold", "description": "Requires `holds:read` scope.", "tags": [ "Legal holds" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "holds:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Hold" } }, "required": [ "data" ] }, "example": { "data": { "id": "holdexample0001", "name": "2026 employment dispute", "reason": "Case 2026-114; requested by legal", "scope": "mailbox", "mailboxId": "mailboxexample1", "target": "support@example.com", "endsAt": null, "placedBy": "admin@example.com", "placedAt": "2026-11-11T08:00:00.000Z", "releasedAt": null, "releasedBy": "", "releaseReason": "", "status": "active" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/holds/{id}/release": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Hold ID returned by listHolds or placeHold.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "releaseHold", "summary": "Release a legal hold", "description": "Requires `holds:write` scope.\n\nReleases an active hold, with a reason that goes to the activity log. 409 hold_not_active when it was already released or has ended. Once released, a covered mailbox that sits in the recycle bin past its retention is purged by the next hourly round, unless another hold still covers it. Admins only.", "tags": [ "Legal holds" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "holds:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseHoldInput" } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Hold" } }, "required": [ "data" ] }, "example": { "data": { "id": "holdexample0001", "name": "2026 employment dispute", "reason": "Case 2026-114; requested by legal", "scope": "mailbox", "mailboxId": "mailboxexample1", "target": "support@example.com", "endsAt": null, "placedBy": "admin@example.com", "placedAt": "2026-11-11T08:00:00.000Z", "releasedAt": "2026-12-01T08:00:00.000Z", "releasedBy": "admin@example.com", "releaseReason": "Case closed", "status": "released" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reports/inactive-mailboxes": { "get": { "operationId": "listInactiveMailboxes", "summary": "Inactive mailboxes", "description": "Requires `mailboxes:read` scope.\n\nActive mailboxes, older than the period, with no WebMail sign-in and no mail received or sent in it, longest inactive first. Two signals decide it: WebMail's sign-in history and session activity, and the newest message in the mailbox's local mail index (mail received, and mail sent when a copy was saved). Sign-ins of mail apps over IMAP / SMTP are not seen. A mailbox that is not in the mail index cannot be judged and is not listed; meta.unknown counts those. Computed from records this app keeps, not from the mail server's own counters; the description of each field says what it sees.", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:read" ], "parameters": [ { "name": "days", "in": "query", "description": "The period without activity. The WebMail sign-in history is kept 90 days, so that is the longest.", "schema": { "type": "integer", "enum": [ 30, 60, 90 ], "default": 30 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InactiveMailboxListResponse" } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reports/storage": { "get": { "operationId": "getStorageReport", "summary": "Storage per domain", "description": "Requires `mailboxes:read` scope.\n\nMailbox usage per domain from one sample a day (UTC), largest first, with the change since the earliest sample in the period and the samples themselves. Usage is the reading the mailbox list shows, so it is only as fresh as the last usage refresh. A domain appears once it has a sample; the hourly job writes them. Without page or perPage the response holds at most the 1000 largest domains; pagination.total says how many there are, and page / perPage read the rest. Computed from records this app keeps, not from the mail server's own counters; the description of each field says what it sees.", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:read" ], "parameters": [ { "name": "days", "in": "query", "description": "The period the change is measured over.", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 } }, { "name": "page", "in": "query", "description": "Pages the domains, like the other lists. Without page and perPage, the first 1000 domains are returned.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "perPage", "in": "query", "description": "Domains per page when paged (50 by default).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StorageReport" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reports/top-senders": { "get": { "operationId": "getTopSenders", "summary": "Top senders by daily sending-limit usage", "description": "Requires `mailboxes:read` scope.\n\nToday's (UTC; the daily limit resets at 00:00 UTC) twenty heaviest senders: submissions made through WebMail, the console and follow-up tasks, refused ones included, divided by the daily limit set for the mailbox through this app. Mail a mail app submits over SMTP counts against the server's limit too but is not in these numbers. available is false where the send events cannot be read. Computed from records this app keeps, not from the mail server's own counters; the description of each field says what it sees.", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mailboxes:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TopSendersReport" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch": { "post": { "operationId": "executeBatch", "summary": "Batch-manage domains, mailboxes and aliases", "description": "Requires a valid Bearer API key.\n\n1–25 operations per request with a body of at most 16 KiB. The whole request's format, base fields and each operation's scope are validated first, then writes run in order; resource existence, ownership and remote state are checked as each operation runs. Ordinary failures are recorded and execution continues; an unclear result stops the batch and later operations are marked skipped. No transactional rollback or automatic retry. Returns 200 when all succeed and 207 when any are failed, uncertain or skipped. The same key with the same normalized request replays the completed result; different content returns idempotency_conflict, and running/uncertain batches are not re-executed. Responses never include passwords.", "tags": [ "Batch" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "description": "Identifies this batch for the API key; replays must use the same key and the same normalized operations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchInput" } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "true means the saved result was replayed; false means this is the first execution.", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BatchResult" } }, "required": [ "data" ] } } } }, "207": { "description": "Per-operation results include failed, uncertain or skipped operations.", "headers": { "Idempotency-Replayed": { "description": "true means the saved result was replayed; false means this is the first execution.", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BatchResult" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-operation-required-scopes": { "mailbox.create": "mailboxes:write", "mailbox.set_password": "mailboxes:write", "mailbox.set_status": "mailboxes:write", "mailbox.set_quota": "mailboxes:write", "mailbox.set_note": "mailboxes:write", "mailbox.delete": "mailboxes:write", "domain.import": "domains:write", "domain.request": "domains:write", "domain.verify": "domains:write", "domain.refresh": "domains:write", "domain.set_enabled": "domains:write", "domain.remove": "domains:write", "alias.create": "aliases:write", "alias.update": "aliases:write", "alias.delete": "aliases:write" } } }, "/batch/{requestId}": { "parameters": [ { "name": "requestId", "in": "path", "required": true, "description": "The Idempotency-Key used when submitting.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{8,128}$" } } ], "get": { "operationId": "getBatchStatus", "summary": "Get batch execution status", "description": "Requires a valid Bearer API key.\n\nOnly the original API key can query it. Returns requestId, state, created and updated — never the operations, fingerprint or results. Neither running nor uncertain batches are ever re-executed automatically.", "tags": [ "Batch" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BatchStatus" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-key": "original" } }, "/agent-tasks": { "get": { "operationId": "listAgentTasks", "summary": "List follow-up tasks", "description": "Requires `agent_tasks:read` scope.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:read" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "running", "paused", "completed", "abandoned", "failed", "cancelled" ] } }, { "name": "mailboxId", "in": "query", "description": "Filter by mailbox.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "q", "in": "query", "description": "Search by mailbox address or task title.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTaskSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createAgentTask", "summary": "Create a follow-up task", "description": "Requires `agent_tasks:write` scope.\n\nA task is bound to one mailbox: the agent only reads that mailbox and only sends as the mailbox address itself. sendMode defaults to auto (fully autonomous, no email needs approval); with approve_first the first email of each conversation and emails to new addresses need approval; with approve every email does.\n\nWith a callbackUrl, the response includes callbackSecret once; it is never returned again. Callback requests carry X-Mailhq-Signature: t=,v1=.\")> and contain only the event name, task ID and timeline sequence number, never mail content.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "description": "Optional. Replaying with the same key from the same API key returns the original task (200); a different prompt or mailbox returns idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentTaskInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "true means the saved result was replayed; false means this is the first execution.", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreatedAgentTask" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-tasks/batch": { "post": { "operationId": "createAgentTasksBatch", "summary": "Create a follow-up task for each of several mailboxes", "description": "Requires `agent_tasks:write` scope.\n\nCreates one task with the same prompt for every mailbox in mailboxIds and mailboxes, 1–50 in total (duplicates as written are removed). Fields mean the same as when creating a single follow-up task; threadEmailId is not supported.\n\nThe input is validated as a whole first, and an invalid input rejects the entire batch. Each mailbox is then created on its own, so one failing (missing, unusable, over its task limit and so on) does not affect the others. items returns each mailbox's result in the submitted order; the response is 200 when all succeed and 207 when any failed. With a callbackUrl, each new task carries its own callbackSecret once.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "description": "Optional. Each mailbox keeps its own idempotency record: replaying the whole batch with the same key from the same API key returns the original task for mailboxes already done (replayed) and retries the ones that failed; a different prompt returns idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentTasksBatchInput" } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentTaskBatchResult" } }, "required": [ "data" ] } } } }, "207": { "description": "Some mailboxes failed; see each item's error.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentTaskBatchResult" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-tasks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Follow-up task ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getAgentTask", "summary": "Get a follow-up task", "description": "Requires `agent_tasks:read` scope.\n\nIncludes the prompt, contacts, conversations and outbox (with bodies).", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentTask" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateAgentTaskLimits", "summary": "Change a follow-up task's limits", "description": "Requires `agent_tasks:write` scope.\n\nSend only the fields to change, at least one. Any unfinished task can be changed; a limit may go below what is already used (meaning no more emails / model calls). A limits event is added to the timeline and the agent follows the new limits from its next run; a task paused because it ran out of model calls resumes automatically when the limit is raised.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "maxEmails": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Maximum emails (reminders included); 0 means no limit." }, "maxSteps": { "type": "integer", "minimum": 1, "maximum": 1000 }, "deadline": { "type": [ "string", "null" ], "description": "ISO deadline within 180 days; an empty string or null removes the deadline." } }, "required": [] } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentTask" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-tasks/{id}/events": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Follow-up task ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "listAgentTaskEvents", "summary": "Fetch the task timeline", "description": "Requires `agent_tasks:read` scope.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:read" ], "parameters": [ { "name": "after", "in": "query", "description": "Only events with a greater sequence number are returned; pass the previous page's nextAfter.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTaskEvent" } }, "nextAfter": { "type": "integer", "minimum": 0 } }, "required": [ "data", "nextAfter" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-tasks/{id}/threads": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Follow-up task ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "listAgentTaskThreads", "summary": "List the conversations a task follows", "description": "Requires `agent_tasks:read` scope.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTaskThread" } } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "addAgentTaskThread", "summary": "Hand a conversation to a task", "description": "Requires `agent_tasks:write` scope.\n\nThe conversation's participants (other than the mailbox's own addresses) become contacts; a running task is woken right away.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "emailId": { "type": "string", "description": "The JMAP Email ID of any message in the conversation." } }, "required": [ "emailId" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentTask" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-tasks/{id}/messages": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Follow-up task ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "messageAgentTask", "summary": "Message the agent", "description": "Requires `agent_tasks:write` scope.\n\nCounts as the answer when the task is waiting for its owner, otherwise as an additional instruction. The task is woken right away.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentTask" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-tasks/{id}/pause": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Follow-up task ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "pauseAgentTask", "summary": "Pause a follow-up task", "description": "Requires `agent_tasks:write` scope.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentTask" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-tasks/{id}/resume": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Follow-up task ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "resumeAgentTask", "summary": "Resume a follow-up task", "description": "Requires `agent_tasks:write` scope.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentTask" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-tasks/{id}/cancel": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Follow-up task ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "cancelAgentTask", "summary": "Cancel a follow-up task", "description": "Requires `agent_tasks:write` scope.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentTask" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-tasks/{id}/approvals": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Follow-up task ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "listAgentTaskApprovals", "summary": "List emails awaiting approval", "description": "Requires `agent_tasks:read` scope.", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:read" ], "parameters": [ { "name": "status", "in": "query", "description": "all returns every email in the outbox (including sent and rejected ones).", "schema": { "type": "string", "enum": [ "pending", "all" ], "default": "pending" } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTaskOutboxItem" } } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-tasks/{id}/approvals/{approvalId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Follow-up task ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "approvalId", "in": "path", "required": true, "description": "Outbox item ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "decideAgentTaskApproval", "summary": "Approve or reject an email", "description": "Requires `agent_tasks:write` scope.\n\nApproving sends it right away as the mailbox; the response holds the status afterwards: sent, failed, or uncertain (sending was interrupted: check Sent first, do not approve the same email again).", "tags": [ "Agent tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_tasks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTaskDecisionInput" } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentTaskOutboxItem" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhooks", "description": "Requires `webhooks:read` scope.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "webhookexample1", "url": "https://hooks.example.com/mailhq", "format": "standard", "description": "Provisioning sync", "events": [ "mailbox.created", "mailbox.deleted" ], "enabled": true, "disabledReason": null, "consecutiveFailures": 0, "failingSince": null, "lastDeliveryAt": "2026-01-01T00:00:00.000Z", "lastStatusCode": 200, "lastError": null, "created": "2026-01-01T00:00:00.000Z", "updated": "2026-01-01T00:00:00.000Z" } ] } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createWebhook", "summary": "Create a webhook", "description": "Requires `webhooks:write` scope.\n\nRegisters an https address for events. The response carries the signing `secret` this once; it is never returned again. Each delivery is a JSON POST `{ id, type, created, data }` with the headers `X-Mailhq-Event` (the event type), `X-Mailhq-Delivery` (the event id) and `X-Mailhq-Signature: t=,v1=.\")>`. Verify the signature over the raw body and refuse timestamps more than five minutes from your clock. A workspace can have at most 10 webhooks (409 `webhook_limit`).", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreatedWebhook" } }, "required": [ "data" ] }, "example": { "data": { "id": "webhookexample1", "url": "https://hooks.example.com/mailhq", "format": "standard", "description": "Provisioning sync", "events": [ "mailbox.created", "mailbox.deleted" ], "enabled": true, "disabledReason": null, "consecutiveFailures": 0, "failingSince": null, "lastDeliveryAt": "2026-01-01T00:00:00.000Z", "lastStatusCode": 200, "lastError": null, "created": "2026-01-01T00:00:00.000Z", "updated": "2026-01-01T00:00:00.000Z", "secret": "whsec_REPLACE_WITH_THE_RETURNED_SECRET" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ webhook record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getWebhook", "summary": "Get a webhook", "description": "Requires `webhooks:read` scope.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] }, "example": { "data": { "id": "webhookexample1", "url": "https://hooks.example.com/mailhq", "format": "standard", "description": "Provisioning sync", "events": [ "mailbox.created", "mailbox.deleted" ], "enabled": true, "disabledReason": null, "consecutiveFailures": 0, "failingSince": null, "lastDeliveryAt": "2026-01-01T00:00:00.000Z", "lastStatusCode": 200, "lastError": null, "created": "2026-01-01T00:00:00.000Z", "updated": "2026-01-01T00:00:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateWebhook", "summary": "Update a webhook", "description": "Requires `webhooks:write` scope.\n\nChanges the address, description, subscribed events or the switch; at least one field is required. `enabled: true` switches a disabled webhook back on and clears its failure count; `enabled: false` switches it off and dead-letters what was waiting for it. The signing secret cannot be read or changed through the API: rotate it in the admin console (Settings → API keys → Webhooks), or delete the webhook and create it again.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookInput" } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] }, "example": { "data": { "id": "webhookexample1", "url": "https://hooks.example.com/mailhq", "format": "standard", "description": "Provisioning sync", "events": [ "mailbox.created", "mailbox.deleted" ], "enabled": true, "disabledReason": null, "consecutiveFailures": 0, "failingSince": null, "lastDeliveryAt": "2026-01-01T00:00:00.000Z", "lastStatusCode": 200, "lastError": null, "created": "2026-01-01T00:00:00.000Z", "updated": "2026-01-01T00:00:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook", "description": "Requires `webhooks:write` scope.\n\nDeletes the webhook with its pending deliveries and its delivery log.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletedResource" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{id}/deliveries": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ webhook record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "listWebhookDeliveries", "summary": "List a webhook's recent delivery attempts", "description": "Requires `webhooks:read` scope.\n\nThe delivery log: the latest 100 attempts with their status code and duration, each with the state of its delivery (`deliveryStatus`) and, on the latest attempt of a delivery waiting for a retry, when that retry is due (`nextRetry`). Payloads and response bodies are never recorded or returned. A failed delivery is retried with exponential backoff, up to 11 attempts, then dead-lettered.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:read" ], "parameters": [ { "name": "limit", "in": "query", "description": "How many attempts to return, newest first.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAttempt" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "attemptexample1", "deliveryId": "deliveryexampl1", "eventId": "eventexample001", "eventType": "mailbox.created", "attempt": 1, "ok": true, "statusCode": 200, "durationMs": 184, "error": "", "created": "2026-01-01T00:00:00.000Z", "deliveryStatus": "delivered", "nextRetry": null } ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{id}/deliveries/{deliveryId}/redeliver": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ webhook record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "deliveryId", "in": "path", "required": true, "description": "The `deliveryId` of an attempt in the webhook's delivery log.", "schema": { "type": "string", "minLength": 1 } } ], "post": { "operationId": "redeliverWebhookDelivery", "summary": "Send a delivery's event again", "description": "Requires `webhooks:write` scope.\n\nSends the event of a settled delivery (`deliveryStatus` `delivered` or `dead`) again now: the same payload under the same event id, so a receiver that already processed it can drop the repeat, signed with the current secret and a fresh timestamp. It takes no request body and returns the new attempt, which belongs to a delivery of its own. Like a test it is a single attempt: never retried, not counted toward disabling the webhook, and it also works for a disabled webhook; a receiver that does not answer 2xx is reported in the attempt (`ok: false`). A delivery still waiting for its own retry is refused with 409 `delivery_in_progress`; one whose payload is no longer kept (7 days after it was delivered, 30 days after it was dead-lettered) answers 404.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookAttempt" } }, "required": [ "data" ] }, "example": { "data": { "id": "attemptexample1", "deliveryId": "deliveryexampl1", "eventId": "eventexample001", "eventType": "mailbox.created", "attempt": 1, "ok": true, "statusCode": 200, "durationMs": 184, "error": "", "created": "2026-01-01T00:00:00.000Z", "deliveryStatus": "delivered", "nextRetry": null } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{id}/test": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MailHQ webhook record ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "testWebhook", "summary": "Send a test event", "description": "Requires `webhooks:write` scope.\n\nSends one `webhook.test` event now, signed like any other, and returns the attempt. It takes no request body, is never retried, does not count toward disabling the webhook, and also works for a disabled webhook. A receiver that does not answer 2xx is reported in the attempt (`ok: false`), not as an HTTP error of this call.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookAttempt" } }, "required": [ "data" ] }, "example": { "data": { "id": "attemptexample1", "deliveryId": "deliveryexampl1", "eventId": "eventexample001", "eventType": "webhook.test", "attempt": 1, "ok": true, "statusCode": 200, "durationMs": 184, "error": "", "created": "2026-01-01T00:00:00.000Z", "deliveryStatus": "delivered", "nextRetry": null } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/suppressions": { "get": { "operationId": "listSuppressions", "summary": "List suppressed recipients", "description": "Requires `suppressions:read` scope.\n\nRecipients that hard-bounced repeatedly (added by the bounce reader) or were added by hand or from a CSV, newest first. The list is advisory: the mail server refuses nothing because of it (Stalwart 1.x has no per-recipient block list the management API can set). WebMail warns its user before sending to a suppressed address; a program that sends mail should check the address here first.", "tags": [ "Suppressions" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "suppressions:read" ], "parameters": [ { "name": "q", "in": "query", "description": "Only addresses that contain this text.", "schema": { "type": "string", "maxLength": 320 } }, { "name": "reason", "in": "query", "description": "Only entries added for this reason.", "schema": { "type": "string", "enum": [ "hard_bounce", "complaint", "manual", "import" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionListResponse" }, "example": { "data": [ { "address": "nobody@example.net", "reason": "hard_bounce", "note": "", "bounces": 2, "lastBounce": "2026-01-02T03:04:05Z", "lastStatus": "5.1.1", "addedBy": null, "created": "2026-01-02T04:17:00.000Z" } ], "pagination": { "page": 1, "perPage": 50, "total": 1, "totalPages": 1 } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "addSuppression", "summary": "Suppress a recipient", "description": "Requires `suppressions:write` scope.\n\nAdds an address by hand (`reason` is `manual`). An address already on the list is returned unchanged with 200; one that was removed earlier is put back.", "tags": [ "Suppressions" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "suppressions:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSuppressionInput" } } } }, "responses": { "200": { "description": "The address was already on the list; the stored entry is returned unchanged.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Suppression" } }, "required": [ "data" ] }, "example": { "data": { "address": "nobody@example.net", "reason": "hard_bounce", "note": "", "bounces": 2, "lastBounce": "2026-01-02T03:04:05Z", "lastStatus": "5.1.1", "addedBy": null, "created": "2026-01-02T04:17:00.000Z" } } } } }, "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Suppression" } }, "required": [ "data" ] }, "example": { "data": { "address": "nobody@example.net", "reason": "manual", "note": "", "bounces": 0, "lastBounce": null, "lastStatus": null, "addedBy": null, "created": "2026-01-02T04:17:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/suppressions/{address}": { "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The recipient address (URL-encoded). Case is ignored.", "schema": { "type": "string", "maxLength": 320 } } ], "get": { "operationId": "getSuppression", "summary": "Check whether a recipient is suppressed", "description": "Requires `suppressions:read` scope.\n\nReturns the entry, or 404 when the address is not suppressed. The list is advisory: the mail server refuses nothing because of it (Stalwart 1.x has no per-recipient block list the management API can set). WebMail warns its user before sending to a suppressed address; a program that sends mail should check the address here first.", "tags": [ "Suppressions" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "suppressions:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Suppression" } }, "required": [ "data" ] }, "example": { "data": { "address": "nobody@example.net", "reason": "hard_bounce", "note": "", "bounces": 2, "lastBounce": "2026-01-02T03:04:05Z", "lastStatus": "5.1.1", "addedBy": null, "created": "2026-01-02T04:17:00.000Z" } } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "removeSuppression", "summary": "Remove a recipient from the suppression list", "description": "Requires `suppressions:write` scope.\n\nTakes the address off the list. Its earlier hard bounces stop counting: the bounce reader adds it again only after new hard bounces reach the workspace's threshold.", "tags": [ "Suppressions" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "suppressions:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RemovedSuppression" } }, "required": [ "data" ] }, "example": { "data": { "address": "nobody@example.net", "deleted": true } } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/trace": { "get": { "operationId": "traceMessages", "summary": "Trace messages", "description": "Requires `trace:read` scope.\n\nWhat happened to a message: when it was accepted and queued, every delivery attempt with the remote host and its SMTP answer, and whether it ended delivered, deferred (with the next retry) or bounced. At least one of `sender`, `recipient`, `messageId` and `queueId` is required (400 `missing_criteria`); all given criteria must match.\n\nThe data comes from the mail server's file logs (Stalwart's own per-message history is Enterprise-only), so only messages still in the logs are found, and steps such as TLS are present only when the server logs them; `tls` and `dkimSigned` are `null` when the log does not say. `queued` lists matching messages still waiting in the outbound queue, read from the queue itself. Each call reads a bounded part of the logs and returns at most 10 messages; while `cursor` is not null, call again with it for older ones. `servers[].exhausted` says nothing more of the workspace's messages was found on that server.\n\n**Off until the platform operator turns it on**: while the platform setting \"Workspace admins can use message trace\" is off (the default), only a platform admin's key of the default workspace may call this; every other key gets `403 forbidden`, also with the `trace:read` scope.\n\nA key sees only messages whose envelope sender or a recipient is in one of its workspace's domains, and of a message from outside only the recipients in those domains. Nothing else in the answer comes from other workspaces' mail either: `searchedBack`, `servers[].oldest`, `servers[].exhausted` and `cursor` are worked out from the key's own messages, so a search that only other workspaces' mail matches answers exactly like one that nothing matches. To page reliably through mail from a sender who also writes to other workspaces, add one of the workspace's own addresses or domains as `recipient`. **Every call is recorded in the activity log** with the key's id and the search terms, because a trace reveals who wrote to whom. 409 `trace_unavailable`: none of the workspace's domains is bound to a mail server whose management API is configured.", "tags": [ "Trace" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "trace:read" ], "parameters": [ { "name": "sender", "in": "query", "schema": { "type": "string", "maxLength": 320, "description": "The envelope sender: an address, or a domain (`example.net` or `@example.net`). Matched as a substring, case ignored." } }, { "name": "recipient", "in": "query", "schema": { "type": "string", "maxLength": 320, "description": "The envelope recipient: an address, or a domain (`example.net` or `@example.net`). Matched as a substring, case ignored." } }, { "name": "messageId", "in": "query", "description": "The Message-ID header, with or without the angle brackets.", "schema": { "type": "string", "maxLength": 320 } }, { "name": "queueId", "in": "query", "description": "The mail server's queue id of the message.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Start of the time range (ISO 8601); omitted means open." } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "End of the time range (ISO 8601); omitted means open." } }, { "name": "server", "in": "query", "description": "Only this mail server (an `id` of listServers); omitted searches every server the workspace's domains use (at most 3).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "The `cursor` of the previous answer, to continue with older log entries (same other parameters).", "schema": { "type": "string", "maxLength": 2000 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceResponse" }, "example": { "data": { "messages": [ { "queueId": "9001", "serverId": "serverexample01", "server": "mail.example.com", "from": "alice@example.com", "to": [ "bob@example.net" ], "messageId": "", "size": 2048, "at": "2026-01-02T03:04:05Z", "remoteIp": "198.51.100.7", "authenticatedAs": "alice@example.com", "origin": "authenticated", "status": "delivered", "tls": true, "dkimSigned": null, "partialTimeline": false, "steps": [ { "at": "2026-01-02T03:04:05Z", "kind": "queued", "event": "queue.authenticated-message-queued", "recipient": null, "host": null, "code": null, "response": null, "nextRetry": null }, { "at": "2026-01-02T03:04:07Z", "kind": "delivered", "event": "delivery.delivered", "recipient": "bob@example.net", "host": "mx.example.net", "code": 250, "response": "2.0.0 Ok: queued as 4F2A1", "nextRetry": null } ] } ], "queued": [], "searchedBack": "2026-01-02T03:04:05Z", "servers": [ { "id": "serverexample01", "server": "mail.example.com", "exhausted": true, "error": null, "oldest": "2026-01-02T03:04:05Z" } ] }, "cursor": null } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/emails": { "get": { "operationId": "listEmails", "summary": "List sent messages", "description": "Requires `emails:read` scope.\n\nMessages sent through the API, newest first. They are kept 30 days.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:read" ], "parameters": [ { "name": "status", "in": "query", "description": "Only messages with this status.", "schema": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "delivery_delayed", "bounced", "partially_delivered", "failed" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailListResponse" }, "example": { "data": [ { "id": "em9x2k4p7q1w3zd", "from": "billing@example.com", "envelopeFrom": "api-sender-k3x9qa@example.com", "subject": "Your invoice for November", "messageId": "", "status": "delivered", "recipients": [ { "address": "ada@example.net", "kind": "to", "status": "delivered", "code": 250, "detail": "250 2.0.0 OK", "at": "2026-11-13T09:00:04.000Z", "complainedAt": null } ], "tags": { "invoice": "INV-1042" }, "attempts": 1, "lastError": null, "created": "2026-11-13T09:00:00.000Z", "sent": "2026-11-13T09:00:01.000Z" } ], "pagination": { "page": 1, "perPage": 50, "total": 1, "totalPages": 1 } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "sendEmail", "summary": "Send a message", "description": "Requires `emails:write` scope.\n\nAccepts one message from an address on a domain with sending turned on (PUT /domains/{id}/sending) and hands it to the domain's server right after the response; follow it with GET /emails/{id} or the email.* webhook events. Mail goes out from the domain's own mail server, signed with the domain's DKIM key: the envelope sender is the domain's sending account (so bounces return to it), the From header the address you give. Recipients on the suppression list are not sent to (status `suppressed`). Each message counts once against the workspace's daily allowance (GET /sending). The body may be up to 8 MiB. With a test key the message goes to the sandbox: nothing leaves, every recipient is delivered except a local part starting with `bounce`, which bounces.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes the request safe to repeat for 24 hours: the same key with the same body returns what the first request accepted (200) instead of sending again; with another body it is refused (409 idempotency_conflict).", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailInput" } } } }, "responses": { "200": { "description": "Replayed: this Idempotency-Key already sent this body; the message is returned as it is now.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Email" } }, "required": [ "data" ] }, "example": { "data": { "id": "em9x2k4p7q1w3zd", "from": "billing@example.com", "envelopeFrom": "api-sender-k3x9qa@example.com", "subject": "Your invoice for November", "messageId": "", "status": "delivered", "recipients": [ { "address": "ada@example.net", "kind": "to", "status": "delivered", "code": 250, "detail": "250 2.0.0 OK", "at": "2026-11-13T09:00:04.000Z", "complainedAt": null } ], "tags": { "invoice": "INV-1042" }, "attempts": 1, "lastError": null, "created": "2026-11-13T09:00:00.000Z", "sent": "2026-11-13T09:00:01.000Z" } } } } }, "202": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Email" } }, "required": [ "data" ] }, "example": { "data": { "id": "em9x2k4p7q1w3zd", "from": "billing@example.com", "envelopeFrom": "api-sender-k3x9qa@example.com", "subject": "Your invoice for November", "messageId": "", "status": "queued", "recipients": [ { "address": "ada@example.net", "kind": "to", "status": "queued", "code": null, "detail": null, "at": null, "complainedAt": null } ], "tags": { "invoice": "INV-1042" }, "attempts": 0, "lastError": null, "created": "2026-11-13T09:00:00.000Z", "sent": null } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The workspace's plan bills sending through the API, and it has no subscription that may send (error.code billing_required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/emails/batch": { "post": { "operationId": "sendEmailBatch", "summary": "Send several messages", "description": "Requires `emails:write` scope.\n\nUp to 50 messages, each checked like POST /emails, accepted together or not at all: the first refused message's error carries its position in `details.index`. They take that many messages of the daily allowance.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes the request safe to repeat for 24 hours: the same key with the same body returns what the first request accepted (200) instead of sending again; with another body it is refused (409 idempotency_conflict).", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailBatchInput" } } } }, "responses": { "202": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "em9x2k4p7q1w3zd", "from": "billing@example.com", "envelopeFrom": "api-sender-k3x9qa@example.com", "subject": "Your invoice for November", "messageId": "", "status": "queued", "recipients": [ { "address": "ada@example.net", "kind": "to", "status": "delivered", "code": 250, "detail": "250 2.0.0 OK", "at": "2026-11-13T09:00:04.000Z", "complainedAt": null } ], "tags": { "invoice": "INV-1042" }, "attempts": 0, "lastError": null, "created": "2026-11-13T09:00:00.000Z", "sent": null } ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The workspace's plan bills sending through the API, and it has no subscription that may send (error.code billing_required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/emails/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Message ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getEmail", "summary": "Get a message's delivery status", "description": "Requires `emails:read` scope.\n\nThe message, each recipient's outcome, and its events in order. Delivery status is read from the domain's mail server logs 1, 5 and 15 minutes, then 1, 3, 8, 24, 48 and 72 hours after sending, until every recipient has a final outcome.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/EmailDetail" } }, "required": [ "data" ] }, "example": { "data": { "id": "em9x2k4p7q1w3zd", "from": "billing@example.com", "envelopeFrom": "api-sender-k3x9qa@example.com", "subject": "Your invoice for November", "messageId": "", "status": "delivered", "recipients": [ { "address": "ada@example.net", "kind": "to", "status": "delivered", "code": 250, "detail": "250 2.0.0 OK", "at": "2026-11-13T09:00:04.000Z", "complainedAt": null } ], "tags": { "invoice": "INV-1042" }, "attempts": 1, "lastError": null, "created": "2026-11-13T09:00:00.000Z", "sent": "2026-11-13T09:00:01.000Z", "events": [ { "type": "email.sent", "recipient": null, "detail": null, "at": "2026-11-13T09:00:01.000Z" }, { "type": "email.delivered", "recipient": "ada@example.net", "detail": "250 2.0.0 OK", "at": "2026-11-13T09:01:02.000Z" } ] } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sending": { "get": { "operationId": "getSending", "summary": "Get the workspace's sending state", "description": "Requires `emails:read` scope.\n\nWhether the workspace may send through the API (a platform admin approves it with a daily limit; a test key's sandbox may always send, to itself), today's use of the allowance, and each domain's sending state.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SendingState" } }, "required": [ "data" ] }, "example": { "data": { "approved": true, "dailyLimit": 1000, "approvedLimit": 1000, "planCap": null, "warmupUntil": null, "paused": null, "sentToday": 12, "day": "2026-11-13", "domains": [ { "domainId": "dom4k2p9x7q1w3z", "domain": "example.com", "enabled": true, "envelopeFrom": "api-sender-k3x9qa@example.com", "created": "2026-11-13T08:00:00.000Z", "simulated": false } ] } } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/sending": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Domain ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getDomainSending", "summary": "Get a domain's sending state", "description": "Requires `emails:read` scope.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainSending" } }, "required": [ "data" ] }, "example": { "data": { "domainId": "dom4k2p9x7q1w3z", "domain": "example.com", "enabled": true, "envelopeFrom": "api-sender-k3x9qa@example.com", "created": "2026-11-13T08:00:00.000Z", "simulated": false } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "enableDomainSending", "summary": "Turn sending on for a domain", "description": "Requires `emails:write` scope.\n\nCreates the domain's sending account on its own mail server (api-sender-@; its password is generated and never shown). Mail goes out from the domain's own mail server, signed with the domain's DKIM key: the envelope sender is the domain's sending account (so bounces return to it), the From header the address you give. Idempotent: 200 when the domain already sends. A live key needs the workspace's approval (403 email_api_not_approved). The domain cannot be removed while it sends.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:write" ], "responses": { "200": { "description": "The domain already sends through the API; its state is returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainSending" } }, "required": [ "data" ] }, "example": { "data": { "domainId": "dom4k2p9x7q1w3z", "domain": "example.com", "enabled": true, "envelopeFrom": "api-sender-k3x9qa@example.com", "created": "2026-11-13T08:00:00.000Z", "simulated": false } } } } }, "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainSending" } }, "required": [ "data" ] }, "example": { "data": { "domainId": "dom4k2p9x7q1w3z", "domain": "example.com", "enabled": true, "envelopeFrom": "api-sender-k3x9qa@example.com", "created": "2026-11-13T08:00:00.000Z", "simulated": false } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "disableDomainSending", "summary": "Turn sending off for a domain", "description": "Requires `emails:write` scope.\n\nDeletes the domain's sending account. Messages not yet handed to the server fail (email.failed).", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainSending" } }, "required": [ "data" ] }, "example": { "data": { "domainId": "dom4k2p9x7q1w3z", "domain": "example.com", "enabled": false, "envelopeFrom": null, "created": null, "simulated": false } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/smtp-credentials": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Domain ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "listSmtpCredentials", "summary": "List a domain's SMTP relay credentials", "description": "Requires `emails:read` scope.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SmtpCredential" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "smtp1a2b3c4d5e6", "domainId": "dom1a2b3c4d5e6f", "name": "Billing system", "username": "api-sender-k3x9qa@example.com", "created": "2026-11-13T09:00:00.000Z" } ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createSmtpCredential", "summary": "Make an SMTP relay credential", "description": "Requires `emails:write` scope.\n\nFor software that can only send over SMTP: a password to sign in to the domain's own submission service (host, port and security in the answer) as the domain's sending account (username). It may only sign in and send. The password is in this answer only. What is sent this way is not an API message: no GET /emails record and no delivery events, and it counts against the sending account's own limit on the server, not the workspace's allowance. Needs the workspace's approval, unpaused; a pause or a withdrawn approval revokes every relay credential. At most 10 per domain. Not available to test keys.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "What the credential is for, at most 100 characters." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/NewSmtpCredential" } }, "required": [ "data" ] }, "example": { "data": { "id": "smtp1a2b3c4d5e6", "domainId": "dom1a2b3c4d5e6f", "name": "Billing system", "username": "api-sender-k3x9qa@example.com", "created": "2026-11-13T09:00:00.000Z", "password": "app_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "host": "mail.example.com", "port": 465, "security": "tls" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domains/{id}/smtp-credentials/{credentialId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Domain ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "credentialId", "in": "path", "required": true, "description": "SMTP relay credential ID.", "schema": { "type": "string", "minLength": 1 } } ], "delete": { "operationId": "revokeSmtpCredential", "summary": "Revoke an SMTP relay credential", "description": "Requires `emails:write` scope.\n\nRevokes the password on the mail server at once.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "emails:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "revoked": { "type": "boolean" } }, "required": [ "id", "revoked" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "smtp1a2b3c4d5e6", "revoked": true } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/inbound-routes": { "get": { "operationId": "listInboundRoutes", "summary": "List inbound routes", "description": "Requires `inbound:read` scope.\n\nThe mailboxes whose received mail is told to the workspace's webhooks as message.received.", "tags": [ "Inbound" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "inbound:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboundRoute" } } }, "required": [ "data" ] }, "example": { "data": [ { "mailboxId": "mbx4k2p9x7q1w3z", "mailbox": "inbox@app.example.com", "lastReceived": "2026-11-13T09:12:00.000Z", "lastError": null, "created": "2026-11-13T08:00:00.000Z" } ] } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/{id}/inbound": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mailbox ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getInboundRoute", "summary": "Get a mailbox's inbound route", "description": "Requires `inbound:read` scope.", "tags": [ "Inbound" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "inbound:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InboundRoute" } }, "required": [ "data" ] }, "example": { "data": { "mailboxId": "mbx4k2p9x7q1w3z", "mailbox": "inbox@app.example.com", "lastReceived": "2026-11-13T09:12:00.000Z", "lastError": null, "created": "2026-11-13T08:00:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "enableInboundRoute", "summary": "Turn inbound routing on for a mailbox", "description": "Requires `inbound:write` scope.\n\nFrom now on, every message the mailbox receives (outside its sent, drafts and trash folders) is POSTed to the workspace's webhooks subscribed to message.received, with its addresses, subject and plain text (up to 16 KiB); read the whole message with GET /mailboxes/{id}/messages/{emailId}. Mail to many addresses can reach one routed mailbox through aliases or the domain's catch-all. The mailbox must be active with a stored password (409 mailbox_unreadable). Idempotent: 200 when it is already routed. In test mode, mail the API sends to a routed sandbox mailbox is told at once.", "tags": [ "Inbound" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "inbound:write" ], "responses": { "200": { "description": "The mailbox is already routed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InboundRoute" } }, "required": [ "data" ] }, "example": { "data": { "mailboxId": "mbx4k2p9x7q1w3z", "mailbox": "inbox@app.example.com", "lastReceived": "2026-11-13T09:12:00.000Z", "lastError": null, "created": "2026-11-13T08:00:00.000Z" } } } } }, "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InboundRoute" } }, "required": [ "data" ] }, "example": { "data": { "mailboxId": "mbx4k2p9x7q1w3z", "mailbox": "inbox@app.example.com", "lastReceived": null, "lastError": null, "created": "2026-11-13T08:00:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "disableInboundRoute", "summary": "Turn inbound routing off for a mailbox", "description": "Requires `inbound:write` scope.", "tags": [ "Inbound" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "inbound:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "mailboxId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "deleted": { "type": "boolean", "const": true } }, "required": [ "mailboxId", "deleted" ] } }, "required": [ "data" ] }, "example": { "data": { "mailboxId": "mbx4k2p9x7q1w3z", "deleted": true } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/{id}/messages/{emailId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mailbox ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "emailId", "in": "path", "required": true, "description": "The message's id in the mailbox: the `emailId` of its message.received event.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "get": { "operationId": "getReceivedMessage", "summary": "Read a received message", "description": "Requires `inbound:read` scope.\n\nA message a routed mailbox received: addresses, subject, date, plain text, sanitized HTML (remote images blocked) and attachment metadata. Only routed mailboxes can be read this way. Not available to test keys.", "tags": [ "Inbound" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "inbound:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReceivedMessage" } }, "required": [ "data" ] }, "example": { "data": { "id": "Mabc123", "mailboxId": "mbx4k2p9x7q1w3z", "subject": "Re: order 1042", "from": [ { "name": "Ada", "email": "ada@example.net" } ], "to": [ { "name": "", "email": "inbox@app.example.com" } ], "cc": [], "replyTo": [], "date": "2026-11-13T09:12:00.000Z", "size": 5120, "text": "Thanks, received.", "html": null, "tooLarge": false, "attachments": [ { "index": 0, "filename": "receipt.pdf", "contentType": "application/pdf", "size": 3100, "inline": false } ] } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mailboxes/{id}/messages/{emailId}/attachments/{index}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mailbox ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "emailId", "in": "path", "required": true, "description": "The message's id in the mailbox: the `emailId` of its message.received event.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "index", "in": "path", "required": true, "description": "The attachment's `index` from the message.", "schema": { "type": "integer", "minimum": 0, "maximum": 9999 } } ], "get": { "operationId": "getReceivedAttachment", "summary": "Download an attachment of a received message", "description": "Requires `inbound:read` scope.\n\nThe attachment's bytes as application/octet-stream (the sender's content type is not trusted), with its filename in Content-Disposition. Not available to test keys.", "tags": [ "Inbound" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "inbound:read" ], "responses": { "200": { "description": "The attachment's bytes.", "headers": { "Content-Disposition": { "description": "attachment; filename=…", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-mailboxes": { "get": { "operationId": "listAgentMailboxes", "summary": "List agent mailboxes", "description": "Requires `agent_mailboxes:read` scope.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentMailbox" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "mbx4k2p9x7q1w3z", "address": "agent-k3x9qa7m@app.example.com", "name": "Support agent", "status": "active", "inbound": { "enabled": true, "lastReceived": null, "lastError": null }, "sending": true, "created": "2026-11-13T09:00:00.000Z" } ] } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createAgentMailbox", "summary": "Create an agent mailbox", "description": "Requires `agent_mailboxes:write` scope.\n\nMakes a mailbox for an AI agent in one call: a generated password the console keeps (never returned), inbound routing on (what it receives is POSTed as message.received), and its domain's sending turned on when the workspace may send through the API. A username is made up (`agent-…`) when none is given. When routing or sending could not be turned on now, the mailbox is still made and says so (`inbound.enabled`, `sending`).", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentMailboxInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentMailbox" } }, "required": [ "data" ] }, "example": { "data": { "id": "mbx4k2p9x7q1w3z", "address": "agent-k3x9qa7m@app.example.com", "name": "Support agent", "status": "active", "inbound": { "enabled": true, "lastReceived": null, "lastError": null }, "sending": true, "created": "2026-11-13T09:00:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-mailboxes/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent mailbox (mailbox) ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getAgentMailbox", "summary": "Get an agent mailbox", "description": "Requires `agent_mailboxes:read` scope.\n\nA key restricted to this agent mailbox (POST /agent-mailboxes/{id}/keys) may call it; such a key gets `403 key_mailbox_restricted` anywhere else.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentMailbox" } }, "required": [ "data" ] }, "example": { "data": { "id": "mbx4k2p9x7q1w3z", "address": "agent-k3x9qa7m@app.example.com", "name": "Support agent", "status": "active", "inbound": { "enabled": true, "lastReceived": null, "lastError": null }, "sending": true, "created": "2026-11-13T09:00:00.000Z" } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteAgentMailbox", "summary": "Delete an agent mailbox", "description": "Requires `agent_mailboxes:write` scope.\n\nDeletes the mailbox for good (a legal hold refuses it) and revokes the keys restricted to it. Not available to a restricted key.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "mbx4k2p9x7q1w3z", "deleted": true } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-mailboxes/{id}/messages": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent mailbox ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "listAgentMessages", "summary": "List an agent's inbox", "description": "Requires `agent_mailboxes:read` scope.\n\nThe inbox, newest first. A key restricted to this agent mailbox (POST /agent-mailboxes/{id}/keys) may call it; such a key gets `403 key_mailbox_restricted` anywhere else. Not available to test keys.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:read" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "before", "in": "query", "description": "Only messages received before this time: the oldest `receivedAt` of a page asks for the next.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentMessage" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "Mabc123", "messageId": "", "threadId": "Tabc", "from": { "name": "Ada", "email": "ada@example.net" }, "to": [ "agent-k3x9qa7m@app.example.com" ], "subject": "Where is my order?", "preview": "Hi, I ordered on Monday and…", "receivedAt": "2026-11-13T09:12:00Z", "unread": true, "hasAttachment": false } ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-mailboxes/{id}/messages/{emailId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent mailbox ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "emailId", "in": "path", "required": true, "description": "The message's id in the mailbox, from the inbox list or a message.received event.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "get": { "operationId": "getAgentMessage", "summary": "Read a message an agent received", "description": "Requires `agent_mailboxes:read` scope.\n\nThe whole message: addresses, subject, date, text, sanitized HTML and attachment metadata. A key restricted to this agent mailbox (POST /agent-mailboxes/{id}/keys) may call it; such a key gets `403 key_mailbox_restricted` anywhere else. Not available to test keys.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReceivedMessage" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateAgentMessage", "summary": "Mark a message an agent received read or flagged", "description": "Requires `agent_mailboxes:write` scope.\n\n`read` and/or `flagged`, each true or false. A key restricted to this agent mailbox (POST /agent-mailboxes/{id}/keys) may call it; such a key gets `403 key_mailbox_restricted` anywhere else. Not available to test keys.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "read": { "type": "boolean" }, "flagged": { "type": "boolean" } }, "required": [], "minProperties": 1 } } } }, "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "read": { "type": "boolean" }, "flagged": { "type": "boolean" } }, "required": [ "id" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteAgentMessage", "summary": "Delete a message an agent received", "description": "Requires `agent_mailboxes:write` scope.\n\nMoves it to the agent's Trash; a message already in Trash is deleted for good (`deleted` says which). A key restricted to this agent mailbox (POST /agent-mailboxes/{id}/keys) may call it; such a key gets `403 key_mailbox_restricted` anywhere else. Not available to test keys.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "deleted": { "type": "string", "enum": [ "trash", "permanently" ] } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-mailboxes/{id}/messages/{emailId}/attachments/{index}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent mailbox ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "emailId", "in": "path", "required": true, "description": "The message's id in the mailbox, from the inbox list or a message.received event.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "index", "in": "path", "required": true, "description": "The attachment's `index` from the message.", "schema": { "type": "integer", "minimum": 0, "maximum": 9999 } } ], "get": { "operationId": "getAgentAttachment", "summary": "Download an attachment of a received message", "description": "Requires `agent_mailboxes:read` scope.\n\nThe attachment's bytes as application/octet-stream (the sender's content type is not trusted), with its filename in Content-Disposition. Not available to test keys.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:read" ], "responses": { "200": { "description": "The attachment's bytes.", "headers": { "Content-Disposition": { "description": "attachment; filename=…", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-mailboxes/{id}/messages/{emailId}/reply": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent mailbox ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, { "name": "emailId", "in": "path", "required": true, "description": "The message's id in the mailbox, from the inbox list or a message.received event.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "post": { "operationId": "replyAsAgent", "summary": "Reply to a message as the agent", "description": "Requires `agent_mailboxes:write` scope.\n\nAnswers the message in its thread: to its Reply-To (or From), \"Re: \" before the subject, In-Reply-To and References set; `replyAll` adds its other recipients as cc. Sent like POST /emails (approval, allowance, delivery status, events). A key restricted to this agent mailbox (POST /agent-mailboxes/{id}/keys) may call it; such a key gets `403 key_mailbox_restricted` anywhere else. Not available to test keys.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "As for POST /emails: the same key with the same body returns the message it sent (200).", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentReplyInput" } } } }, "responses": { "202": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Email" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The workspace's plan bills sending through the API, and it has no subscription that may send (error.code billing_required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream mail server call failed. If the write result is unclear, check the state first instead of repeating the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-mailboxes/{id}/send": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent mailbox ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "sendAsAgent", "summary": "Send a message as the agent", "description": "Requires `agent_mailboxes:write` scope.\n\nA new message from the agent's own address and name: POST /emails' body without `from`. A key restricted to this agent mailbox (POST /agent-mailboxes/{id}/keys) may call it; such a key gets `403 key_mailbox_restricted` anywhere else.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "As for POST /emails: the same key with the same body returns the message it sent (200).", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSendInput" } } } }, "responses": { "202": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Email" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The workspace's plan bills sending through the API, and it has no subscription that may send (error.code billing_required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent-mailboxes/{id}/keys": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent mailbox ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "post": { "operationId": "createAgentKey", "summary": "Create a key for one agent mailbox", "description": "Requires `agent_mailboxes:write` scope.\n\nA key for the agent itself, restricted to this mailbox: it reads the mailbox's mail and sends from it, and nothing else. The token is in this response only. Made by the calling key's owner (an admin), counted against their 20 keys and listed under Settings → API keys. Not available to a restricted key.", "tags": [ "Agent mailboxes" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agent_mailboxes:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "expiresInDays": { "type": [ "integer", "null" ] } }, "required": [] } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentKey" } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Field validation failed or the operation does not apply to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mail-apps": { "get": { "operationId": "listMailApps", "summary": "List mail apps", "description": "Requires `mail_apps:read` scope.\n\nThe apps mailbox users of this workspace can authorize, newest first, with how many mailboxes have.", "tags": [ "Mail apps" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mail_apps:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MailApp" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "app4k2p9x7q1w3z", "clientId": "mhq_mapp_app4k2p9x7q1w3z", "name": "Acme CRM", "redirectUris": [ "https://crm.example.com/oauth/callback" ], "scopes": [ "mail.read", "mail.send" ], "grants": 3, "created": "2026-11-13T09:00:00.000Z", "revoked": null } ] } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createMailApp", "summary": "Register a mail app", "description": "Requires `mail_apps:write` scope.\n\nRegisters an app mailbox users can authorize on WebMail's consent page (`/oauth/authorize`) to read their mail (`mail.read`), send as them (`mail.send`) and/or organize it (`mail.modify`). The answer's `clientId` is what the app sends; it is a public client (no secret), with PKCE (S256) required. Its tokens are used with WebMail's Mail API (`/api/mail/v1`). At most 20 per workspace. Not available to test keys.", "tags": [ "Mail apps" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mail_apps:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMailAppInput" } } } }, "responses": { "201": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailApp" } }, "required": [ "data" ] }, "example": { "data": { "id": "app4k2p9x7q1w3z", "clientId": "mhq_mapp_app4k2p9x7q1w3z", "name": "Acme CRM", "redirectUris": [ "https://crm.example.com/oauth/callback" ], "scopes": [ "mail.read", "mail.send" ], "grants": 0, "created": "2026-11-13T09:00:00.000Z", "revoked": null } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Resource conflict, or the target's state does not allow this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The request body must use Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mail-apps/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mail app ID.", "schema": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } } ], "get": { "operationId": "getMailApp", "summary": "Get a mail app", "description": "Requires `mail_apps:read` scope.", "tags": [ "Mail apps" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mail_apps:read" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailApp" } }, "required": [ "data" ] }, "example": { "data": { "id": "app4k2p9x7q1w3z", "clientId": "mhq_mapp_app4k2p9x7q1w3z", "name": "Acme CRM", "redirectUris": [ "https://crm.example.com/oauth/callback" ], "scopes": [ "mail.read", "mail.send" ], "grants": 3, "created": "2026-11-13T09:00:00.000Z", "revoked": null } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "revokeMailApp", "summary": "Revoke a mail app", "description": "Requires `mail_apps:write` scope.\n\nRevokes the app and every mailbox's authorization of it: its tokens stop working at once.", "tags": [ "Mail apps" ], "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "mail_apps:write" ], "responses": { "200": { "description": "Success.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "revoked": { "type": "boolean", "const": true } }, "required": [ "id", "revoked" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "app4k2p9x7q1w3z", "revoked": true } } } } }, "400": { "description": "Malformed request or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or revoked Bearer API key. A browser sign-in cookie cannot replace an API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key lacks the scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The target resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A count or rate limit was exceeded; try again later. A rate-limited request has error.code rate_limited and a Retry-After header.", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window for this API key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The limit and its window in seconds, as `;w=`.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or the upstream mail server configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Create a key in the admin settings. Enter the raw key; the client sends Authorization: Bearer . See each operation for the required scope." } }, "schemas": { "SendingLimit": { "type": "object", "additionalProperties": false, "properties": { "dailyLimit": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "Submissions per day; 0 means this system sets no limit." }, "resetTimeZone": { "type": "string", "const": "UTC" } }, "required": [ "dailyLimit", "resetTimeZone" ] }, "SendingLimitsResult": { "type": "object", "additionalProperties": false, "properties": { "results": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "email": { "type": [ "string", "null" ], "format": "email" }, "limit": { "anyOf": [ { "$ref": "#/components/schemas/SendingLimit" }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "The reason this mailbox change failed; null on success." }, "uncertain": { "type": "boolean", "description": "The remote write is unconfirmed. Verify its state before retrying." } }, "required": [ "id", "email", "limit", "error", "uncertain" ] } } }, "required": [ "results" ] }, "Server": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Mail server subscription ID." }, "server": { "type": "string", "description": "Public hostname of the mail server." }, "provider": { "type": "string", "const": "stalwart" }, "quotaMb": { "type": "integer", "minimum": 0, "description": "Default quota for new mailboxes on this server, in MB; 0 means no per-mailbox quota." }, "defaultDailySendLimit": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "Default daily sending limit for new mailboxes on this server. Zero adds no limit and preserves any existing rule for the same address." }, "domains": { "type": "array", "items": { "type": "string", "description": "Domains configured on the server; left out with domains=false." } }, "domainCount": { "type": "integer", "minimum": 0, "description": "How many of the workspace's domains the server serves." } }, "required": [ "id", "server", "provider", "quotaMb", "defaultDailySendLimit", "domainCount" ] }, "Domain": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "name": { "type": "string", "description": "Domain name." }, "created": { "type": "string", "description": "UTC timestamp string." }, "subscriptionId": { "type": [ "string", "null" ], "description": "Bound server subscription ID." } }, "required": [ "id", "name", "created", "subscriptionId" ], "example": { "id": "domainexample01", "name": "example.com", "created": "2026-01-01 00:00:00.000Z", "subscriptionId": null } }, "DomainStatus": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "name": { "type": "string", "description": "Domain name." }, "enabled": { "type": "boolean" } }, "required": [ "id", "name", "enabled" ] }, "MailboxStatus": { "type": "string", "enum": [ "pending", "active", "disabled" ] }, "Mailbox": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "domain": { "type": "string", "description": "Domain name." }, "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:(?:[a-z0-9_-]|\\.(?!\\.)){0,62}[a-z0-9])?$", "allOf": [ { "not": { "pattern": "\\.\\." } } ], "description": "The part of the address before @: lowercase letters, digits, dots, underscores or hyphens, starting and ending with a letter or digit, with no consecutive dots." }, "email": { "type": "string", "format": "email" }, "status": { "$ref": "#/components/schemas/MailboxStatus" }, "note": { "type": "string" }, "quotaMb": { "type": [ "integer", "null" ], "description": "Quota (MB); 0 means no per-mailbox quota, null means not yet synced." }, "usageMb": { "type": [ "number", "null" ], "description": "Most recently synced usage (MB); null means not yet synced." }, "usageSyncedAt": { "type": [ "string", "null" ], "description": "Time usage was last synced; null means not yet synced." }, "mailTotal": { "type": [ "integer", "null" ], "description": "Most recently synced inbox message count; null means not yet synced." }, "mailUnseen": { "type": [ "integer", "null" ], "description": "Most recently synced inbox unread count; null means not yet synced." }, "mailSyncedAt": { "type": [ "string", "null" ], "description": "Time mail counts were last synced; null means not yet synced." }, "created": { "type": "string", "description": "UTC timestamp string." }, "updated": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "id", "domain", "username", "email", "status", "note", "quotaMb", "usageMb", "usageSyncedAt", "mailTotal", "mailUnseen", "mailSyncedAt", "created", "updated" ], "description": "Explicit list of public fields; never includes password or cdkId. Usage and mail counts are snapshots from the last sync.", "example": { "id": "mailboxexample1", "domain": "example.com", "username": "support", "email": "support@example.com", "status": "active", "note": "Support mailbox", "quotaMb": 1024, "usageMb": null, "usageSyncedAt": null, "mailTotal": null, "mailUnseen": null, "mailSyncedAt": null, "created": "2026-01-01 00:00:00.000Z", "updated": "2026-01-01 00:00:00.000Z" } }, "DeletedMailboxResult": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "deleted": { "type": "boolean", "const": true }, "permanent": { "type": "boolean", "description": "true when the mailbox and its mail are gone for good; false when it is in the recycle bin." }, "purgeAfter": { "type": [ "string", "null" ], "description": "When a mailbox in the recycle bin is deleted for good (UTC); null when permanent." } }, "required": [ "id", "deleted", "permanent", "purgeAfter" ], "example": { "id": "mailboxexample1", "deleted": true, "permanent": false, "purgeAfter": "2026-12-10T08:00:00.000Z" } }, "DeletedMailbox": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "domain": { "type": "string", "description": "Domain name." }, "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:(?:[a-z0-9_-]|\\.(?!\\.)){0,62}[a-z0-9])?$", "allOf": [ { "not": { "pattern": "\\.\\." } } ], "description": "The part of the address before @: lowercase letters, digits, dots, underscores or hyphens, starting and ending with a letter or digit, with no consecutive dots." }, "email": { "type": "string", "format": "email" }, "note": { "type": "string", "maxLength": 500, "description": "Mailbox note; surrounding whitespace is removed before saving, and the rest can be at most 500 characters." }, "deletedAt": { "type": "string", "description": "UTC timestamp string." }, "deletedBy": { "type": "string", "description": "Who deleted it: the account's email, or the name the activity log gives a non-account actor. May be empty." }, "purgeAfter": { "type": "string", "description": "UTC timestamp string." }, "statusBefore": { "type": "string", "enum": [ "active", "disabled" ], "description": "The status it had when deleted, which restoreMailbox brings it back to." } }, "required": [ "id", "domain", "username", "email", "note", "deletedAt", "deletedBy", "purgeAfter", "statusBefore" ] }, "DeletedMailboxListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeletedMailbox" } }, "pagination": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } }, "required": [ "page", "perPage", "total", "totalPages" ] } }, "required": [ "data", "pagination" ] }, "DomainListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "pagination": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } }, "required": [ "page", "perPage", "total", "totalPages" ] } }, "required": [ "data" ] }, "DomainOnboardingListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DomainOnboarding" } }, "pagination": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } }, "required": [ "page", "perPage", "total", "totalPages" ] } }, "required": [ "data" ] }, "MailboxListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } }, "pagination": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } }, "required": [ "page", "perPage", "total", "totalPages" ] } }, "required": [ "data", "pagination" ] }, "ImportDomainInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "example": "example.com" }, "subscriptionId": { "type": "string", "description": "Optional server subscription ID." } }, "required": [ "name" ] }, "CreateDomainOnboardingInput": { "type": "object", "additionalProperties": false, "properties": { "domain": { "type": "string", "example": "example.com" }, "subscriptionId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, "required": [ "domain", "subscriptionId" ] }, "CreateMailboxInput": { "type": "object", "additionalProperties": false, "properties": { "domain": { "type": "string", "example": "example.com" }, "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:(?:[a-z0-9_-]|\\.(?!\\.)){0,62}[a-z0-9])?$", "allOf": [ { "not": { "pattern": "\\.\\." } } ], "description": "The part of the address before @: lowercase letters, digits, dots, underscores or hyphens, starting and ending with a letter or digit, with no consecutive dots.", "example": "support" }, "password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 8, "maxLength": 128, "pattern": "^\\S+$", "description": "The mailbox's new password, 8–128 characters with no whitespace; write-only — responses never include it." }, "quotaMb": { "type": "integer", "minimum": 0, "maximum": 10485760, "description": "Quota in MB; 0 means no per-mailbox quota." }, "note": { "type": "string", "maxLength": 500, "description": "Mailbox note; surrounding whitespace is removed before saving, and the rest can be at most 500 characters." } }, "required": [ "domain", "username", "password" ] }, "PasswordInput": { "type": "object", "additionalProperties": false, "properties": { "password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 8, "maxLength": 128, "pattern": "^\\S+$", "description": "The mailbox's new password, 8–128 characters with no whitespace; write-only — responses never include it." } }, "required": [ "password" ] }, "DomainAlias": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "name": { "type": "string", "description": "The alias domain name." }, "domainId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "Record ID of the primary domain." }, "domain": { "type": "string", "description": "The primary domain name." }, "state": { "type": "string", "enum": [ "pending", "provisioning", "active", "uncertain" ], "description": "pending: waiting for the ownership TXT. provisioning: verified, being added on the mail server. active: the mail server delivers the alias domain's addresses to the primary domain's mailboxes. uncertain: a server write could not be confirmed; verify again." }, "ownershipVerifiedAt": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "description": "UTC timestamp string." }, "created": { "type": "string", "description": "UTC timestamp string." }, "updated": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "id", "name", "domainId", "domain", "state", "ownershipVerifiedAt", "expiresAt", "created", "updated" ] }, "DomainAliasDetails": { "type": "object", "additionalProperties": false, "properties": { "alias": { "$ref": "#/components/schemas/DomainAlias" }, "server": { "type": "string", "description": "The mail server the primary domain is bound to; the MX target." }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/MailDnsCheck" } }, "checkedAt": { "type": "string", "description": "UTC timestamp string." }, "ready": { "type": "boolean", "description": "The alias is active and every required DNS record is published." } }, "required": [ "alias", "server", "records", "checkedAt", "ready" ] }, "DomainCatchAll": { "type": "object", "additionalProperties": false, "properties": { "domainId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "domain": { "type": "string", "description": "Domain name." }, "destination": { "type": [ "string", "null" ], "description": "The catch-all mailbox, or null when mail to unknown addresses is rejected." }, "managed": { "type": "boolean", "description": "false when the destination on the server is not a mailbox of this domain managed by MailHQ (set in Stalwart, or its mailbox was deleted); it can only be replaced or cleared." } }, "required": [ "domainId", "domain", "destination", "managed" ], "example": { "domainId": "domainexample01", "domain": "example.com", "destination": null, "managed": true } }, "CreateForwarderInput": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:(?:[a-z0-9_-]|\\.(?!\\.)){0,62}[a-z0-9])?$", "allOf": [ { "not": { "pattern": "\\.\\." } } ], "description": "The part of the address before @: lowercase letters, digits, dots, underscores or hyphens, starting and ending with a letter or digit, with no consecutive dots.", "example": "help" }, "destination": { "type": "string", "format": "email", "maxLength": 254, "example": "support@example.com" } }, "required": [ "username", "destination" ] }, "CreatedForwarder": { "type": "object", "additionalProperties": false, "properties": { "source": { "type": "string", "format": "email", "example": "help@example.com" }, "destinations": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "support@example.com" ] } }, "required": [ "source", "destinations" ] }, "CreateAliasInput": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:(?:[a-z0-9_-]|\\.(?!\\.)){0,62}[a-z0-9])?$", "allOf": [ { "not": { "pattern": "\\.\\." } } ], "description": "The part of the address before @: lowercase letters, digits, dots, underscores or hyphens, starting and ending with a letter or digit, with no consecutive dots.", "example": "help" }, "target": { "type": "string", "format": "email", "maxLength": 254, "description": "An existing mailbox managed by MailHQ on the same domain; cannot be a pending mailbox.", "example": "support@example.com" }, "enabled": { "type": "boolean", "default": true }, "description": { "type": "string", "maxLength": 500, "default": "" } }, "required": [ "username", "target" ] }, "UpdateAliasInput": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:(?:[a-z0-9_-]|\\.(?!\\.)){0,62}[a-z0-9])?$", "allOf": [ { "not": { "pattern": "\\.\\." } } ], "description": "The part of the address before @: lowercase letters, digits, dots, underscores or hyphens, starting and ending with a letter or digit, with no consecutive dots.", "example": "help" }, "enabled": { "type": "boolean" }, "description": { "type": "string", "maxLength": 500, "default": "" } }, "required": [], "minProperties": 1 }, "Alias": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^alias:[A-Za-z0-9_-]{1,1024}$", "description": "Opaque alias ID; use the value returned by the list as-is and URL-encode it in paths." }, "source": { "type": "string", "format": "email", "example": "help@example.com" }, "target": { "type": "string", "format": "email", "example": "support@example.com" }, "enabled": { "type": "boolean" }, "description": { "type": "string" }, "readonly": { "type": "boolean", "description": "true for special aliases or targets outside this domain's managed mailboxes; these cannot be modified or deleted." }, "note": { "type": "string", "description": "Read-only reason or other notes." } }, "required": [ "id", "source", "target", "enabled", "description" ] }, "DeletedAlias": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^alias:[A-Za-z0-9_-]{1,1024}$", "description": "Opaque alias ID; use the value returned by the list as-is and URL-encode it in paths." }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] }, "CreateListInput": { "type": "object", "additionalProperties": false, "properties": { "domainId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:(?:[a-z0-9_-]|\\.(?!\\.)){0,62}[a-z0-9])?$", "allOf": [ { "not": { "pattern": "\\.\\." } } ], "description": "The part of the address before @: lowercase letters, digits, dots, underscores or hyphens, starting and ending with a letter or digit, with no consecutive dots.", "example": "team" }, "description": { "type": "string", "maxLength": 500, "default": "", "description": "Free text; must not start with mailhq:." }, "members": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 500, "uniqueItems": true, "description": "The list's members, at least one.", "minItems": 1 }, "allowExternal": { "type": "boolean", "default": false, "description": "Must be true to add members that are not mailboxes managed by this workspace. The mail server then forwards every message sent to the list, spam included, to those outside addresses." } }, "required": [ "domainId", "username", "members" ] }, "UpdateListInput": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:(?:[a-z0-9_-]|\\.(?!\\.)){0,62}[a-z0-9])?$", "allOf": [ { "not": { "pattern": "\\.\\." } } ], "description": "The part of the address before @: lowercase letters, digits, dots, underscores or hyphens, starting and ending with a letter or digit, with no consecutive dots.", "example": "team" }, "description": { "type": "string", "maxLength": 500, "default": "", "description": "Free text; must not start with mailhq:." }, "addMembers": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 500, "uniqueItems": true, "description": "Addresses to add; ones that are already members are ignored." }, "removeMembers": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 500, "uniqueItems": true, "description": "Addresses to remove; each must be a member." }, "allowExternal": { "type": "boolean", "default": false, "description": "Must be true to add members that are not mailboxes managed by this workspace. The mail server then forwards every message sent to the list, spam included, to those outside addresses." } }, "required": [], "minProperties": 1 }, "ListMember": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string", "format": "email", "maxLength": 254 }, "external": { "type": "boolean", "description": "false for a mailbox managed by this workspace; true for any other address." } }, "required": [ "address", "external" ] }, "List": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^list_[a-z0-9]{15}_[A-Za-z0-9_-]{1,128}$", "description": "Opaque distribution list ID; use the value returned by the list as-is." }, "address": { "type": "string", "format": "email", "example": "team@example.com" }, "username": { "type": "string", "example": "team" }, "description": { "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/ListMember" } }, "memberCount": { "type": "integer", "minimum": 0 }, "externalCount": { "type": "integer", "minimum": 0, "description": "How many members are external." }, "readonly": { "type": "boolean", "description": "true for lists this API cannot change (a tenant's, or with a non-standard address)." }, "note": { "type": "string", "description": "Read-only reason." } }, "required": [ "id", "address", "username", "description", "members", "memberCount", "externalCount" ] }, "DeletedList": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^list_[a-z0-9]{15}_[A-Za-z0-9_-]{1,128}$", "description": "Opaque distribution list ID; use the value returned by the list as-is." }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] }, "PlaceHoldInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "example": "2026 employment dispute" }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Why the hold is placed; written to the activity log." }, "mailboxId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "The mailbox to hold. Give this or domain, not both." }, "domain": { "type": "string", "example": "example.com", "description": "A domain of this workspace. Give this or mailboxId, not both." }, "endsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the hold stops applying by itself (a future UTC timestamp); omitted or null = until released." } }, "required": [ "name", "reason" ] }, "ReleaseHoldInput": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Why the hold is released." } }, "required": [ "reason" ] }, "Hold": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "name": { "type": "string" }, "reason": { "type": "string" }, "scope": { "type": "string", "enum": [ "mailbox", "domain" ] }, "mailboxId": { "type": [ "string", "null" ], "description": "The held mailbox; null for a domain hold." }, "target": { "type": "string", "description": "The mailbox address or the domain name, as it was when the hold was placed." }, "endsAt": { "type": [ "string", "null" ], "description": "End time; null = until released." }, "placedBy": { "type": "string", "description": "Who placed the hold (the sign-in account)." }, "placedAt": { "type": "string", "description": "UTC timestamp string." }, "releasedAt": { "type": [ "string", "null" ] }, "releasedBy": { "type": "string" }, "releaseReason": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "ended", "released" ], "description": "active: applies now. ended: its end time has passed. released: released by an administrator." } }, "required": [ "id", "name", "reason", "scope", "mailboxId", "target", "endsAt", "placedBy", "placedAt", "releasedAt", "releasedBy", "releaseReason", "status" ] }, "HoldListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Hold" } }, "pagination": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } }, "required": [ "page", "perPage", "total", "totalPages" ] } }, "required": [ "data", "pagination" ] }, "InactiveMailbox": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "email": { "type": "string", "format": "email" }, "domain": { "type": "string" }, "created": { "type": "string", "description": "UTC timestamp string." }, "usageMb": { "type": "number", "minimum": 0 }, "lastSignIn": { "type": [ "string", "null" ], "description": "The newest WebMail sign-in or session activity on record; null when there is none." }, "lastMail": { "type": [ "string", "null" ], "description": "When the newest message in the mailbox's local mail index was received; null when it holds none." } }, "required": [ "id", "email", "domain", "created", "usageMb", "lastSignIn", "lastMail" ] }, "InactiveMailboxListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InactiveMailbox" } }, "meta": { "type": "object", "additionalProperties": false, "properties": { "days": { "type": "integer", "enum": [ 30, 60, 90 ] }, "cutoff": { "type": "string", "description": "Activity before this UTC timestamp does not count." }, "unknown": { "type": "integer", "minimum": 0, "description": "Mailboxes without a WebMail sign-in in the period whose mail activity is unknown (not in the mail index); not listed." } }, "required": [ "days", "cutoff", "unknown" ] }, "pagination": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } }, "required": [ "page", "perPage", "total", "totalPages" ] } }, "required": [ "data", "meta", "pagination" ] }, "StorageReport": { "type": "object", "additionalProperties": false, "properties": { "days": { "type": "integer", "enum": [ 7, 30, 90 ] }, "from": { "type": "string", "description": "The first day (UTC, YYYY-MM-DD) of the period." }, "domains": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "domain": { "type": "string" }, "mailboxes": { "type": "integer", "minimum": 0 }, "measured": { "type": "integer", "minimum": 0, "description": "How many of the mailboxes have a usage reading at all." }, "usageMb": { "type": "number", "minimum": 0 }, "day": { "type": "string", "description": "The day of the latest sample." }, "since": { "type": "string", "description": "The day of the earliest sample in the period: the change is measured from it." }, "changeMb": { "type": "number" }, "mailboxChange": { "type": "integer" }, "samples": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "day": { "type": "string" }, "mailboxes": { "type": "integer", "minimum": 0 }, "usageMb": { "type": "number", "minimum": 0 } }, "required": [ "day", "mailboxes", "usageMb" ] } } }, "required": [ "domain", "mailboxes", "measured", "usageMb", "day", "since", "changeMb", "mailboxChange", "samples" ] } } }, "required": [ "days", "from", "domains" ] }, "TopSendersReport": { "type": "object", "additionalProperties": false, "properties": { "day": { "type": "string", "description": "The UTC day the counts are for." }, "available": { "type": "boolean", "description": "false when the send events cannot be read in this deployment." }, "senders": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "email": { "type": "string", "format": "email" }, "sent": { "type": "integer", "minimum": 0 }, "rejected": { "type": "integer", "minimum": 0, "description": "Submissions the daily limit refused; they count against it too." }, "limit": { "type": [ "integer", "null" ], "description": "The daily limit set through this app; null when none was." }, "usage": { "type": [ "number", "null" ], "description": "(sent + rejected) / limit; null without a limit." } }, "required": [ "id", "email", "sent", "rejected", "limit", "usage" ] } } }, "required": [ "day", "available", "senders" ] }, "BatchInput": { "type": "object", "additionalProperties": false, "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/BatchOperation" }, "minItems": 1, "maxItems": 25, "description": "Executed in submission order. Each id must be unique; operations cannot reference results of other operations in the batch. The whole body is at most 16 KiB." } }, "required": [ "operations" ] }, "BatchOperation": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "mailbox.create" }, "input": { "$ref": "#/components/schemas/CreateMailboxInput" } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "mailbox.set_password" }, "input": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 8, "maxLength": 128, "pattern": "^\\S+$", "description": "The mailbox's new password, 8–128 characters with no whitespace; write-only — responses never include it." } }, "required": [ "id", "password" ] } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "mailbox.set_status" }, "input": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "status": { "$ref": "#/components/schemas/MailboxStatus" } }, "required": [ "id", "status" ] } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "mailbox.set_quota" }, "input": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "quotaMb": { "type": "integer", "minimum": 0, "maximum": 10485760, "description": "Quota in MB; 0 means no per-mailbox quota." } }, "required": [ "id", "quotaMb" ] } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "mailbox.set_note" }, "input": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "note": { "type": "string", "maxLength": 500, "description": "Mailbox note; surrounding whitespace is removed before saving, and the rest can be at most 500 characters." } }, "required": [ "id", "note" ] } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "mailbox.delete" }, "input": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "permanent": { "type": "boolean", "default": false, "description": "true skips the recycle bin and deletes for good; see deleteMailbox." } }, "required": [ "id" ] } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "domain.import" }, "input": { "$ref": "#/components/schemas/ImportDomainInput" } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "domain.request" }, "input": { "$ref": "#/components/schemas/CreateDomainOnboardingInput" } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "domain.verify" }, "input": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, "required": [ "id" ] } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "domain.refresh" }, "input": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, "required": [ "id" ] } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "domain.set_enabled" }, "input": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ] } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "domain.remove" }, "input": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." } }, "required": [ "id" ] } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "alias.create" }, "input": { "type": "object", "additionalProperties": false, "properties": { "domainId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:(?:[a-z0-9_-]|\\.(?!\\.)){0,62}[a-z0-9])?$", "allOf": [ { "not": { "pattern": "\\.\\." } } ], "description": "The part of the address before @: lowercase letters, digits, dots, underscores or hyphens, starting and ending with a letter or digit, with no consecutive dots.", "example": "help" }, "target": { "type": "string", "format": "email", "maxLength": 254, "description": "An existing mailbox managed by MailHQ on the same domain; cannot be a pending mailbox.", "example": "support@example.com" }, "enabled": { "type": "boolean", "default": true }, "description": { "type": "string", "maxLength": 500, "default": "" } }, "required": [ "domainId", "username", "target" ] } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "alias.update" }, "input": { "type": "object", "additionalProperties": false, "properties": { "domainId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "aliasId": { "type": "string", "pattern": "^alias:[A-Za-z0-9_-]{1,1024}$", "description": "Opaque alias ID; use the value returned by the list as-is and URL-encode it in paths." }, "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:(?:[a-z0-9_-]|\\.(?!\\.)){0,62}[a-z0-9])?$", "allOf": [ { "not": { "pattern": "\\.\\." } } ], "description": "The part of the address before @: lowercase letters, digits, dots, underscores or hyphens, starting and ending with a letter or digit, with no consecutive dots.", "example": "help" }, "enabled": { "type": "boolean" }, "description": { "type": "string", "maxLength": 500, "default": "" } }, "required": [ "domainId", "aliasId" ], "minProperties": 3 } }, "required": [ "id", "operation", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operation": { "type": "string", "const": "alias.delete" }, "input": { "type": "object", "additionalProperties": false, "properties": { "domainId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "aliasId": { "type": "string", "pattern": "^alias:[A-Za-z0-9_-]{1,1024}$", "description": "Opaque alias ID; use the value returned by the list as-is and URL-encode it in paths." } }, "required": [ "domainId", "aliasId" ] } }, "required": [ "id", "operation", "input" ] } ], "description": "The operation name determines the input shape and required scope. id correlates items within this batch and is not a resource ID." }, "BatchResult": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "replayed": { "type": "boolean", "description": "true means a saved result was replayed, not re-executed." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItemResult" } }, "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "uncertain": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 } }, "required": [ "requestId", "replayed", "results", "succeeded", "failed", "uncertain", "skipped" ] }, "BatchItemResult": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The correlation id submitted with the operation." }, "operation": { "type": "string", "enum": [ "mailbox.create", "mailbox.set_password", "mailbox.set_status", "mailbox.set_quota", "mailbox.set_note", "mailbox.delete", "domain.import", "domain.request", "domain.verify", "domain.refresh", "domain.set_enabled", "domain.remove", "alias.create", "alias.update", "alias.delete" ] }, "outcome": { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "skipped" ] }, "status": { "type": "integer", "description": "Per-operation status code; 200 on success, 424 when not executed." }, "data": { "description": "Public result of a successful operation, without mailbox passwords. Its shape depends on the operation." }, "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "id", "operation", "outcome", "status" ] }, "BatchStatus": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "state": { "type": "string", "enum": [ "running", "completed", "uncertain" ] }, "created": { "type": "string", "description": "UTC timestamp string." }, "updated": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "requestId", "state", "created", "updated" ] }, "DeletedResource": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "example": { "id": "resourceexample", "deleted": true } }, "ApiError": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Every code, with its statuses, meaning, what to do and whether a retry is safe, is in the document's x-error-codes. New codes may be added: treat an unknown one by its HTTP status." }, "message": { "type": "string", "description": "Error description for people, in the request's language; never branch on it." }, "details": {} }, "required": [ "code", "message" ] }, "Pagination": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } }, "required": [ "page", "perPage", "total", "totalPages" ] }, "AgentTaskStatus": { "type": "string", "enum": [ "running", "paused", "completed", "abandoned", "failed", "cancelled" ] }, "AgentTaskSummary": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "mailboxId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "mailboxEmail": { "type": "string", "format": "email" }, "fromAddress": { "type": "string", "format": "email", "description": "The task's sender address: the mailbox itself." }, "ownerKind": { "type": "string", "enum": [ "account", "mailbox" ] }, "ownerEmail": { "type": "string", "description": "Task owner: a back-office login email or a WebMail mailbox address." }, "createdVia": { "type": "string", "enum": [ "admin", "webmail", "api" ] }, "title": { "type": "string" }, "sendMode": { "type": "string", "enum": [ "auto", "approve_first", "approve" ] }, "status": { "$ref": "#/components/schemas/AgentTaskStatus" }, "waitingOn": { "type": "string", "enum": [ "", "approval", "owner", "reply", "schedule" ], "description": "What a running task is waiting for; an empty string means it is working. `owner` (a question to the owner) stays until the owner answers it, even while the agent goes on handling mail." }, "pauseReason": { "type": "string" }, "summary": { "type": "string", "description": "The agent's latest progress note; once the task ends, its summary." }, "deadline": { "type": "string", "description": "ISO time; an empty string means no deadline." }, "maxEmails": { "type": "integer" }, "emailsSent": { "type": "integer" }, "maxSteps": { "type": "integer" }, "stepsUsed": { "type": "integer" }, "tokensUsed": { "type": "integer" }, "costMicros": { "type": "integer", "description": "Cost as billed by AI Gateway, in millionths of a US dollar; recorded once the gateway has written its log, so it lags slightly." }, "nextWakeAt": { "type": "string" }, "pendingApprovals": { "type": "integer" }, "created": { "type": "string", "description": "UTC timestamp string." }, "updated": { "type": "string", "description": "UTC timestamp string." }, "finished": { "type": "string" } }, "required": [ "id", "mailboxId", "mailboxEmail", "fromAddress", "ownerKind", "ownerEmail", "createdVia", "title", "sendMode", "status", "waitingOn", "pauseReason", "summary", "deadline", "maxEmails", "emailsSent", "maxSteps", "stepsUsed", "tokensUsed", "costMicros", "nextWakeAt", "pendingApprovals", "created", "updated", "finished" ] }, "AgentTaskThread": { "type": "object", "additionalProperties": false, "properties": { "threadId": { "type": "string", "description": "JMAP thread ID in the mailbox." }, "subject": { "type": "string" }, "fromAddress": { "type": "string", "format": "email" }, "source": { "type": "string", "enum": [ "sent", "claimed", "owner" ] }, "lastMessageAt": { "type": "string" } }, "required": [ "threadId", "subject", "fromAddress", "source", "lastMessageAt" ] }, "AgentTaskOutboxItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed", "uncertain", "rejected", "superseded" ] }, "fromAddress": { "type": "string", "format": "email" }, "to": { "type": "array", "items": { "type": "string", "format": "email" } }, "cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "subject": { "type": "string" }, "body": { "type": "string", "description": "Plain-text body." }, "replyToEmailId": { "type": "string" }, "replyToMessageId": { "type": "string" }, "replyToReceivedAt": { "type": "string" }, "threadId": { "type": "string" }, "newRecipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "reason": { "type": "string", "description": "Why the agent wants to send this email." }, "decidedBy": { "type": "string" }, "decidedAt": { "type": "string" }, "note": { "type": "string" }, "error": { "type": "string" }, "created": { "type": "string", "description": "UTC timestamp string." }, "updated": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "id", "status", "fromAddress", "to", "cc", "subject", "body", "replyToEmailId", "replyToMessageId", "replyToReceivedAt", "threadId", "newRecipients", "reason", "decidedBy", "decidedAt", "note", "error", "created", "updated" ] }, "AgentTask": { "allOf": [ { "$ref": "#/components/schemas/AgentTaskSummary" }, { "type": "object", "additionalProperties": false, "properties": { "prompt": { "type": "string" }, "systemPrompt": { "type": "string", "description": "The task's system prompt; an empty string means none." }, "notes": { "type": "string", "description": "The agent's own working notes." }, "metadata": { "type": "object" }, "callbackUrl": { "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" }, "source": { "type": "string", "enum": [ "prompt", "owner" ] } }, "required": [ "email", "source" ] } }, "threads": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTaskThread" } }, "outbox": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTaskOutboxItem" } }, "report": { "anyOf": [ { "$ref": "#/components/schemas/AgentTaskReport" }, { "type": "null" } ] } }, "required": [ "prompt", "systemPrompt", "notes", "metadata", "callbackUrl", "contacts", "threads", "outbox", "report" ] } ] }, "AgentTaskReport": { "type": "object", "additionalProperties": false, "properties": { "outcome": { "type": "string", "enum": [ "completed", "abandoned", "failed", "cancelled" ] }, "summary": { "type": "string" }, "keyFacts": { "type": "array", "items": { "type": "string" } }, "emailsSent": { "type": "integer" }, "emailsReceived": { "type": "integer" }, "threads": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "subject": { "type": "string" }, "lastMessageAt": { "type": "string" } }, "required": [ "subject", "lastMessageAt" ] } }, "costMicros": { "type": "integer" }, "startedAt": { "type": "string", "description": "UTC timestamp string." }, "finishedAt": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "outcome", "summary", "keyFacts", "emailsSent", "emailsReceived", "threads", "costMicros", "startedAt", "finishedAt" ] }, "CreatedAgentTask": { "allOf": [ { "$ref": "#/components/schemas/AgentTask" }, { "type": "object", "additionalProperties": false, "properties": { "callbackSecret": { "type": "string", "description": "Callback signing secret, returned only once at creation." } }, "required": [] } ] }, "AgentTaskEvent": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "seq": { "type": "integer", "minimum": 1 }, "kind": { "type": "string", "enum": [ "created", "message", "question", "answer", "instruction", "mail_in", "mail_out", "approval", "auto_send", "approved", "rejected", "withdrawn", "thread", "limits", "scheduled", "paused", "resumed", "completed", "abandoned", "failed", "cancelled", "error" ] }, "actor": { "type": "string", "enum": [ "agent", "owner", "system", "contact" ] }, "text": { "type": "string" }, "data": { "type": "object" }, "created": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "id", "seq", "kind", "actor", "text", "data", "created" ] }, "CreateAgentTaskInput": { "type": "object", "additionalProperties": false, "properties": { "mailboxId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "mailbox": { "type": "string", "format": "email", "description": "The mailbox may also be given by its address." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8000 }, "systemPrompt": { "type": "string", "maxLength": 4000, "description": "Optional system prompt: the identity, tone, signature, background and rules this task always follows, added after the built-in rules. It cannot relax approvals, recipient rules or the email limit." }, "from": { "type": "string", "format": "email", "description": "Deprecated: tasks always send as the mailbox itself. If given, it must be the mailbox address, otherwise 422." }, "sendMode": { "type": "string", "enum": [ "approve", "approve_first", "auto" ], "default": "auto", "description": "auto: fully autonomous, emails go out without approval; approve_first: the first email of each conversation needs approval; approve: every email needs approval. Defaults to auto, or to approve when automatic sending is switched off in the admin (explicit auto / approve_first then returns 409)." }, "deadline": { "type": "string", "description": "Optional ISO deadline within 180 days." }, "maxEmails": { "type": "integer", "minimum": 0, "maximum": 100, "default": 10, "description": "How many emails (reminders included) this task may send; 0 means no limit." }, "maxSteps": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional public HTTPS callback URL." }, "metadata": { "type": "object", "description": "Caller data returned as-is, at most 4096 characters once serialized." }, "threadEmailId": { "type": "string", "description": "Optional: start from the conversation of this message (JMAP Email ID); its participants become contacts." } }, "required": [ "prompt" ] }, "CreateAgentTasksBatchInput": { "type": "object", "additionalProperties": false, "properties": { "mailboxIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "maxItems": 50, "description": "Mailboxes by ID." }, "mailboxes": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50, "description": "Mailboxes by address; can be combined with mailboxIds, 50 in total at most." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8000 }, "systemPrompt": { "type": "string", "maxLength": 4000, "description": "Optional system prompt: the identity, tone, signature, background and rules this task always follows, added after the built-in rules. It cannot relax approvals, recipient rules or the email limit." }, "from": { "type": "string", "format": "email", "description": "Deprecated: tasks always send as the mailbox itself. If given, it must be the mailbox address, otherwise 422." }, "sendMode": { "type": "string", "enum": [ "approve", "approve_first", "auto" ], "default": "auto", "description": "auto: fully autonomous, emails go out without approval; approve_first: the first email of each conversation needs approval; approve: every email needs approval. Defaults to auto, or to approve when automatic sending is switched off in the admin (explicit auto / approve_first then returns 409)." }, "deadline": { "type": "string", "description": "Optional ISO deadline within 180 days." }, "maxEmails": { "type": "integer", "minimum": 0, "maximum": 100, "default": 10, "description": "How many emails (reminders included) this task may send; 0 means no limit." }, "maxSteps": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional public HTTPS callback URL." }, "metadata": { "type": "object", "description": "Caller data returned as-is, at most 4096 characters once serialized." } }, "required": [ "prompt" ] }, "AgentTaskBatchResult": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTaskBatchItem" } } }, "required": [ "items" ] }, "AgentTaskBatchItem": { "type": "object", "additionalProperties": false, "properties": { "mailbox": { "type": "string", "description": "The mailbox as submitted (ID or address)." }, "status": { "type": "string", "enum": [ "created", "replayed", "failed" ], "description": "replayed means the idempotency key matched and the original task is returned." }, "task": { "$ref": "#/components/schemas/CreatedAgentTask" }, "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "mailbox", "status" ] }, "AgentTaskDecisionInput": { "type": "object", "additionalProperties": false, "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "note": { "type": "string", "maxLength": 2000, "description": "A note for the agent." }, "subject": { "type": "string", "maxLength": 300, "description": "Replacement subject when approving." }, "body": { "type": "string", "maxLength": 20000, "description": "Replacement body when approving." } }, "required": [ "decision" ] }, "Webhook": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "The https address events are POSTed to: default port, a public host name (no IP literal, no internal or single-label name), no user name or password. Redirects are not followed." }, "format": { "type": "string", "enum": [ "standard", "feishu", "dingtalk" ], "description": "standard: the signed JSON. feishu, dingtalk: each event is posted to that group bot as a short message (its type and fields), unsigned by this service but signed with the bot's own secret when botSecret is given; url is then the bot's webhook address. Set when the webhook is made." }, "description": { "type": "string", "maxLength": 200, "description": "A note for your own use." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "mailbox.created", "mailbox.updated", "mailbox.suspended", "mailbox.deleted", "domain.verified", "order.paid", "bulk_job.finished", "security.compromised_account", "security.phishing_report", "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.failed", "email.sending_paused", "message.received" ] }, "minItems": 1, "uniqueItems": true, "description": "Event types to deliver; `[\"*\"]` is every event, including ones added later." }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "enum": [ "manual", "failures", null ], "description": "Why the webhook is off: switched off through the API, or automatically after sustained delivery failure. null while enabled." }, "consecutiveFailures": { "type": "integer", "minimum": 0, "description": "Failed attempts since the last success." }, "failingSince": { "type": [ "string", "null" ], "description": "When the current run of failures began; null when the last attempt succeeded." }, "lastDeliveryAt": { "type": [ "string", "null" ], "description": "When the latest attempt (including a test) was made." }, "lastStatusCode": { "type": [ "integer", "null" ], "description": "HTTP status of the latest attempt; null when there was no answer." }, "lastError": { "type": [ "string", "null" ], "description": "Error code of the latest attempt; null when it succeeded." }, "created": { "type": "string", "description": "UTC timestamp string." }, "updated": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "id", "url", "format", "description", "events", "enabled", "disabledReason", "consecutiveFailures", "failingSince", "lastDeliveryAt", "lastStatusCode", "lastError", "created", "updated" ], "example": { "id": "webhookexample1", "url": "https://hooks.example.com/mailhq", "format": "standard", "description": "Provisioning sync", "events": [ "mailbox.created", "mailbox.deleted" ], "enabled": true, "disabledReason": null, "consecutiveFailures": 0, "failingSince": null, "lastDeliveryAt": "2026-01-01T00:00:00.000Z", "lastStatusCode": 200, "lastError": null, "created": "2026-01-01T00:00:00.000Z", "updated": "2026-01-01T00:00:00.000Z" } }, "CreatedWebhook": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "The https address events are POSTed to: default port, a public host name (no IP literal, no internal or single-label name), no user name or password. Redirects are not followed." }, "format": { "type": "string", "enum": [ "standard", "feishu", "dingtalk" ], "description": "standard: the signed JSON. feishu, dingtalk: each event is posted to that group bot as a short message (its type and fields), unsigned by this service but signed with the bot's own secret when botSecret is given; url is then the bot's webhook address. Set when the webhook is made." }, "description": { "type": "string", "maxLength": 200, "description": "A note for your own use." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "mailbox.created", "mailbox.updated", "mailbox.suspended", "mailbox.deleted", "domain.verified", "order.paid", "bulk_job.finished", "security.compromised_account", "security.phishing_report", "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.failed", "email.sending_paused", "message.received" ] }, "minItems": 1, "uniqueItems": true, "description": "Event types to deliver; `[\"*\"]` is every event, including ones added later." }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "enum": [ "manual", "failures", null ], "description": "Why the webhook is off: switched off through the API, or automatically after sustained delivery failure. null while enabled." }, "consecutiveFailures": { "type": "integer", "minimum": 0, "description": "Failed attempts since the last success." }, "failingSince": { "type": [ "string", "null" ], "description": "When the current run of failures began; null when the last attempt succeeded." }, "lastDeliveryAt": { "type": [ "string", "null" ], "description": "When the latest attempt (including a test) was made." }, "lastStatusCode": { "type": [ "integer", "null" ], "description": "HTTP status of the latest attempt; null when there was no answer." }, "lastError": { "type": [ "string", "null" ], "description": "Error code of the latest attempt; null when it succeeded." }, "created": { "type": "string", "description": "UTC timestamp string." }, "updated": { "type": "string", "description": "UTC timestamp string." }, "secret": { "type": "string", "description": "The signing secret. Returned only by this response; store it now." } }, "required": [ "id", "url", "format", "description", "events", "enabled", "disabledReason", "consecutiveFailures", "failingSince", "lastDeliveryAt", "lastStatusCode", "lastError", "created", "updated", "secret" ] }, "CreateWebhookInput": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "The https address events are POSTed to: default port, a public host name (no IP literal, no internal or single-label name), no user name or password. Redirects are not followed." }, "format": { "type": "string", "enum": [ "standard", "feishu", "dingtalk" ], "description": "standard: the signed JSON. feishu, dingtalk: each event is posted to that group bot as a short message (its type and fields), unsigned by this service but signed with the bot's own secret when botSecret is given; url is then the bot's webhook address. Set when the webhook is made." }, "botSecret": { "type": "string", "description": "The bot's own signing secret, for a bot format whose bot has signing on; never returned." }, "description": { "type": "string", "maxLength": 200, "description": "A note for your own use." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "mailbox.created", "mailbox.updated", "mailbox.suspended", "mailbox.deleted", "domain.verified", "order.paid", "bulk_job.finished", "security.compromised_account", "security.phishing_report", "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.failed", "email.sending_paused", "message.received" ] }, "minItems": 1, "uniqueItems": true, "description": "Event types to deliver; `[\"*\"]` is every event, including ones added later." } }, "required": [ "url" ] }, "UpdateWebhookInput": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "The https address events are POSTed to: default port, a public host name (no IP literal, no internal or single-label name), no user name or password. Redirects are not followed." }, "description": { "type": "string", "maxLength": 200, "description": "A note for your own use." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "mailbox.created", "mailbox.updated", "mailbox.suspended", "mailbox.deleted", "domain.verified", "order.paid", "bulk_job.finished", "security.compromised_account", "security.phishing_report", "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.failed", "email.sending_paused", "message.received" ] }, "minItems": 1, "uniqueItems": true, "description": "Event types to deliver; `[\"*\"]` is every event, including ones added later." }, "enabled": { "type": "boolean" } }, "required": [], "minProperties": 1 }, "WebhookAttempt": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "deliveryId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "eventId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "The event's id: the `id` of the payload and the X-Mailhq-Delivery header." }, "eventType": { "type": "string", "description": "The event type, or webhook.test." }, "attempt": { "type": "integer", "minimum": 1 }, "ok": { "type": "boolean", "description": "The receiver answered 2xx." }, "statusCode": { "type": [ "integer", "null" ], "description": "HTTP status the receiver answered; null when there was no answer." }, "durationMs": { "type": "integer", "minimum": 0 }, "error": { "type": "string", "description": "Empty on success; otherwise http_, timeout, network, redirect (redirects are not followed), forbidden (the address is no longer allowed), too_large or unavailable." }, "created": { "type": "string", "description": "UTC timestamp string." }, "deliveryStatus": { "type": [ "string", "null" ], "enum": [ "pending", "sending", "delivered", "dead", null ], "description": "The state of the delivery this attempt belongs to: waiting for a retry, being sent, delivered, or dead-lettered. null once the delivery is no longer kept. Only a delivered or dead delivery can be sent again." }, "nextRetry": { "type": [ "string", "null" ], "description": "When the next retry is due; set only on the latest attempt of a delivery that is waiting for one." } }, "required": [ "id", "deliveryId", "eventId", "eventType", "attempt", "ok", "statusCode", "durationMs", "error", "created", "deliveryStatus", "nextRetry" ], "example": { "id": "attemptexample1", "deliveryId": "deliveryexampl1", "eventId": "eventexample001", "eventType": "mailbox.created", "attempt": 1, "ok": true, "statusCode": 200, "durationMs": 184, "error": "", "created": "2026-01-01T00:00:00.000Z", "deliveryStatus": "delivered", "nextRetry": null } }, "Suppression": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string", "format": "email", "maxLength": 320, "description": "The recipient address, lower case." }, "reason": { "type": "string", "enum": [ "hard_bounce", "complaint", "manual", "import" ], "description": "hard_bounce: added by the bounce reader after repeated hard bounces, or at once for a late hard bounce of mail sent through the API; complaint: the recipient marked mail sent through the API as spam (a feedback loop report); manual: added in the console or through this API; import: from a CSV." }, "note": { "type": "string", "description": "Free text." }, "bounces": { "type": "integer", "minimum": 0, "description": "Hard bounces counted when the entry was added; 0 for one added by hand." }, "lastBounce": { "type": [ "string", "null" ], "description": "When the latest of those bounces arrived; null without one." }, "lastStatus": { "type": [ "string", "null" ], "description": "Its enhanced status code, such as 5.1.1; null without one." }, "addedBy": { "type": [ "string", "null" ], "description": "The sign-in address of who added it; null for the bounce reader." }, "created": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "address", "reason", "note", "bounces", "lastBounce", "lastStatus", "addedBy", "created" ], "example": { "address": "nobody@example.net", "reason": "hard_bounce", "note": "", "bounces": 2, "lastBounce": "2026-01-02T03:04:05Z", "lastStatus": "5.1.1", "addedBy": null, "created": "2026-01-02T04:17:00.000Z" } }, "SuppressionListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "AddSuppressionInput": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string", "format": "email", "maxLength": 320, "description": "The recipient address, lower case." }, "note": { "type": "string", "maxLength": 500, "default": "", "description": "Free text shown beside the entry." } }, "required": [ "address" ] }, "RemovedSuppression": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string", "format": "email", "maxLength": 320, "description": "The recipient address, lower case." }, "deleted": { "type": "boolean", "const": true } }, "required": [ "address", "deleted" ] }, "EmailRecipient": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string", "format": "email" }, "kind": { "type": "string", "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string", "enum": [ "queued", "suppressed", "sent", "delivered", "delivery_delayed", "bounced", "failed" ], "description": "queued: not handed over yet; suppressed: on the suppression list, never sent to; sent: the domain's server took it; delivered: the recipient's server accepted it; delivery_delayed: being retried; bounced: refused (at once or by the recipient's server); failed: never handed over." }, "code": { "type": [ "integer", "null" ], "description": "The SMTP reply code of the latest outcome." }, "detail": { "type": [ "string", "null" ], "description": "The server's text for it." }, "at": { "type": [ "string", "null" ], "description": "When the status last changed." }, "complainedAt": { "type": [ "string", "null" ], "description": "When a feedback loop report said this recipient marked the message as spam (email.complained); null when none did." } }, "required": [ "address", "kind", "status", "code", "detail", "at", "complainedAt" ] }, "Email": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "from": { "type": "string", "format": "email", "description": "The From address." }, "envelopeFrom": { "type": "string", "format": "email", "description": "The domain's sending account: where bounces return." }, "subject": { "type": "string" }, "messageId": { "type": "string", "description": "The Message-ID header, fixed when the message was accepted." }, "status": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "delivery_delayed", "bounced", "partially_delivered", "failed" ], "description": "queued → sending → sent → delivered | delivery_delayed | bounced | partially_delivered (some delivered, some bounced); failed: never handed over (see lastError)." }, "recipients": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string", "format": "email" }, "kind": { "type": "string", "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string", "enum": [ "queued", "suppressed", "sent", "delivered", "delivery_delayed", "bounced", "failed" ], "description": "queued: not handed over yet; suppressed: on the suppression list, never sent to; sent: the domain's server took it; delivered: the recipient's server accepted it; delivery_delayed: being retried; bounced: refused (at once or by the recipient's server); failed: never handed over." }, "code": { "type": [ "integer", "null" ], "description": "The SMTP reply code of the latest outcome." }, "detail": { "type": [ "string", "null" ], "description": "The server's text for it." }, "at": { "type": [ "string", "null" ], "description": "When the status last changed." }, "complainedAt": { "type": [ "string", "null" ], "description": "When a feedback loop report said this recipient marked the message as spam (email.complained); null when none did." } }, "required": [ "address", "kind", "status", "code", "detail", "at", "complainedAt" ] } }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "attempts": { "type": "integer", "minimum": 0, "description": "Hand-over attempts so far (at most 6)." }, "lastError": { "type": [ "string", "null" ], "description": "Why the latest attempt did not hand it over." }, "created": { "type": "string", "description": "UTC timestamp string." }, "sent": { "type": [ "string", "null" ], "description": "When the domain's server took it." } }, "required": [ "id", "from", "envelopeFrom", "subject", "messageId", "status", "recipients", "tags", "attempts", "lastError", "created", "sent" ], "example": { "id": "em9x2k4p7q1w3zd", "from": "billing@example.com", "envelopeFrom": "api-sender-k3x9qa@example.com", "subject": "Your invoice for November", "messageId": "", "status": "delivered", "recipients": [ { "address": "ada@example.net", "kind": "to", "status": "delivered", "code": 250, "detail": "250 2.0.0 OK", "at": "2026-11-13T09:00:04.000Z", "complainedAt": null } ], "tags": { "invoice": "INV-1042" }, "attempts": 1, "lastError": null, "created": "2026-11-13T09:00:00.000Z", "sent": "2026-11-13T09:00:01.000Z" } }, "EmailDetail": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "from": { "type": "string", "format": "email", "description": "The From address." }, "envelopeFrom": { "type": "string", "format": "email", "description": "The domain's sending account: where bounces return." }, "subject": { "type": "string" }, "messageId": { "type": "string", "description": "The Message-ID header, fixed when the message was accepted." }, "status": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "delivery_delayed", "bounced", "partially_delivered", "failed" ], "description": "queued → sending → sent → delivered | delivery_delayed | bounced | partially_delivered (some delivered, some bounced); failed: never handed over (see lastError)." }, "recipients": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string", "format": "email" }, "kind": { "type": "string", "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string", "enum": [ "queued", "suppressed", "sent", "delivered", "delivery_delayed", "bounced", "failed" ], "description": "queued: not handed over yet; suppressed: on the suppression list, never sent to; sent: the domain's server took it; delivered: the recipient's server accepted it; delivery_delayed: being retried; bounced: refused (at once or by the recipient's server); failed: never handed over." }, "code": { "type": [ "integer", "null" ], "description": "The SMTP reply code of the latest outcome." }, "detail": { "type": [ "string", "null" ], "description": "The server's text for it." }, "at": { "type": [ "string", "null" ], "description": "When the status last changed." }, "complainedAt": { "type": [ "string", "null" ], "description": "When a feedback loop report said this recipient marked the message as spam (email.complained); null when none did." } }, "required": [ "address", "kind", "status", "code", "detail", "at", "complainedAt" ] } }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "attempts": { "type": "integer", "minimum": 0, "description": "Hand-over attempts so far (at most 6)." }, "lastError": { "type": [ "string", "null" ], "description": "Why the latest attempt did not hand it over." }, "created": { "type": "string", "description": "UTC timestamp string." }, "sent": { "type": [ "string", "null" ], "description": "When the domain's server took it." }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.failed" ] }, "recipient": { "type": [ "string", "null" ] }, "detail": { "type": [ "string", "null" ] }, "at": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "type", "recipient", "detail", "at" ] } } }, "required": [ "id", "from", "envelopeFrom", "subject", "messageId", "status", "recipients", "tags", "attempts", "lastError", "created", "sent", "events" ] }, "EmailListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] }, "SendEmailInput": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "subject" ], "properties": { "from": { "type": "string", "maxLength": 600, "description": "`address` or `Name
`, on a domain of this workspace that sends through the API." }, "to": { "description": "Recipients: `address` or `Name
`. With cc and bcc, 1 to 50 in all.", "oneOf": [ { "type": "string", "maxLength": 600 }, { "type": "array", "items": { "type": "string", "maxLength": 600 }, "maxItems": 50 } ] }, "cc": { "description": "Copy recipients.", "oneOf": [ { "type": "string", "maxLength": 600 }, { "type": "array", "items": { "type": "string", "maxLength": 600 }, "maxItems": 50 } ] }, "bcc": { "description": "Blind copy recipients: in the envelope, not in the headers.", "oneOf": [ { "type": "string", "maxLength": 600 }, { "type": "array", "items": { "type": "string", "maxLength": 600 }, "maxItems": 50 } ] }, "replyTo": { "description": "Reply-To addresses, at most 5.", "oneOf": [ { "type": "string", "maxLength": 600 }, { "type": "array", "items": { "type": "string", "maxLength": 600 }, "maxItems": 50 } ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 500 }, "text": { "type": "string", "maxLength": 200000, "description": "The plain-text body. text or html (or both) is required." }, "html": { "type": "string", "description": "The HTML body, up to 600 KB." }, "headers": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 998 }, "description": "Extra headers: X- headers, List-Unsubscribe and List-Unsubscribe-Post only." }, "attachments": { "type": "array", "maxItems": 10, "description": "At most 5 MiB in all, decoded.", "items": { "type": "object", "additionalProperties": false, "required": [ "filename", "content" ], "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 200 }, "content": { "type": "string", "contentEncoding": "base64" }, "contentType": { "type": "string", "default": "application/octet-stream" } } } }, "inReplyTo": { "type": "string", "description": "The Message-ID (``) this message answers: replies stay in their thread." }, "references": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "The thread's earlier Message-IDs, oldest first." }, "tags": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 256 }, "description": "Your own labels, returned with the message and in its webhook events (names: letters, digits, _ and -)." } } }, "SendEmailBatchInput": { "type": "object", "additionalProperties": false, "properties": { "emails": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/SendEmailInput" } } }, "required": [ "emails" ] }, "DomainSending": { "type": "object", "additionalProperties": false, "properties": { "domainId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "domain": { "type": "string" }, "enabled": { "type": "boolean" }, "envelopeFrom": { "type": [ "string", "null" ], "description": "The domain's sending account; null when sending is off." }, "created": { "type": [ "string", "null" ], "description": "When sending was turned on." }, "simulated": { "type": "boolean", "description": "A sandbox domain (test key): delivery is simulated." } }, "required": [ "domainId", "domain", "enabled", "envelopeFrom", "created", "simulated" ] }, "SendingState": { "type": "object", "additionalProperties": false, "properties": { "approved": { "type": "boolean", "description": "Whether the workspace may send (a platform admin's approval)." }, "dailyLimit": { "type": "integer", "minimum": 0, "description": "What may be sent today (UTC): the least of approvedLimit, planCap and the warm-up limit; 0 when not approved." }, "approvedLimit": { "type": "integer", "minimum": 0, "description": "The daily limit a platform admin approved." }, "planCap": { "type": [ "integer", "null" ], "description": "The plan's cap on API sending a day; null when it has none." }, "warmupUntil": { "type": [ "string", "null" ], "description": "While a newly approved workspace warms up (50 a day, doubling each day), when dailyLimit reaches approvedLimit." }, "paused": { "type": [ "object", "null" ], "description": "Set while live sending is paused for its bounce or complaint rate (403 email_api_paused).", "properties": { "at": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "at", "reason" ] }, "sentToday": { "type": "integer", "minimum": 0 }, "day": { "type": "string", "description": "The UTC day sentToday counts, YYYY-MM-DD." }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/DomainSending" } } }, "required": [ "approved", "dailyLimit", "approvedLimit", "planCap", "warmupUntil", "paused", "sentToday", "day", "domains" ] }, "SmtpCredential": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "domainId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "name": { "type": "string" }, "username": { "type": "string", "format": "email", "description": "The SMTP user name: the domain's sending account." }, "created": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "id", "domainId", "name", "username", "created" ] }, "NewSmtpCredential": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "domainId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "name": { "type": "string" }, "username": { "type": "string", "format": "email" }, "created": { "type": "string", "description": "UTC timestamp string." }, "password": { "type": "string", "description": "The SMTP password, shown in this answer only." }, "host": { "type": [ "string", "null" ], "description": "The domain's submission server." }, "port": { "type": [ "integer", "null" ], "description": "Its port." }, "security": { "type": [ "string", "null" ], "description": "tls (implicit, usually 465) or starttls (usually 587)." } }, "required": [ "id", "domainId", "name", "username", "created", "password", "host", "port", "security" ] }, "InboundRoute": { "type": "object", "additionalProperties": false, "properties": { "mailboxId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "mailbox": { "type": "string", "format": "email" }, "lastReceived": { "type": [ "string", "null" ], "description": "When it last told a received message." }, "lastError": { "type": [ "string", "null" ], "description": "Why the latest read did not succeed." }, "created": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "mailboxId", "mailbox", "lastReceived", "lastError", "created" ] }, "ReceivedMessage": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "mailboxId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "subject": { "type": "string" }, "from": { "type": "array", "items": { "$ref": "#/components/schemas/MailAddress" } }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/MailAddress" } }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/MailAddress" } }, "replyTo": { "type": "array", "items": { "$ref": "#/components/schemas/MailAddress" } }, "date": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "text": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ], "description": "Sanitized; remote images blocked." }, "tooLarge": { "type": "boolean", "description": "Over 15 MB: the body is not read." }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "index": { "type": "integer" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "integer" }, "inline": { "type": "boolean" } }, "required": [ "index", "filename", "contentType", "size", "inline" ] } } }, "required": [ "id", "mailboxId", "subject", "from", "to", "cc", "replyTo", "date", "size", "text", "html", "tooLarge", "attachments" ] }, "MailAddress": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name", "email" ] }, "AgentMailbox": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "address": { "type": "string", "format": "email" }, "name": { "type": "string", "description": "The From name of what it sends." }, "status": { "type": "string", "description": "The mailbox's status." }, "inbound": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "lastReceived": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] } }, "required": [ "enabled", "lastReceived", "lastError" ] }, "sending": { "type": "boolean", "description": "Whether its domain sends through the API." }, "created": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "id", "address", "name", "status", "inbound", "sending", "created" ], "example": { "id": "mbx4k2p9x7q1w3z", "address": "agent-k3x9qa7m@app.example.com", "name": "Support agent", "status": "active", "inbound": { "enabled": true, "lastReceived": null, "lastError": null }, "sending": true, "created": "2026-11-13T09:00:00.000Z" } }, "CreateAgentMailboxInput": { "type": "object", "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "A domain of the workspace (with sending turned on, or turned on by this call when approved)." }, "username": { "type": "string", "description": "The local part; made up (`agent-…`) when absent." }, "name": { "type": "string", "maxLength": 200, "description": "What the agent is called: the From name." }, "quotaMb": { "type": "integer", "minimum": 0 } }, "required": [ "domain" ] }, "AgentMessage": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "messageId": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ] }, "from": { "oneOf": [ { "$ref": "#/components/schemas/MailAddress" }, { "type": "null" } ] }, "to": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "preview": { "type": "string" }, "receivedAt": { "type": [ "string", "null" ] }, "unread": { "type": "boolean" }, "hasAttachment": { "type": "boolean" } }, "required": [ "id", "messageId", "threadId", "from", "to", "subject", "preview", "receivedAt", "unread", "hasAttachment" ] }, "AgentSendInput": { "type": "object", "additionalProperties": false, "required": [ "to", "subject" ], "properties": { "to": { "description": "Recipients: an address or a list (`Name
` allowed)." }, "cc": { "description": "Copy recipients." }, "bcc": { "description": "Blind copy recipients." }, "replyTo": { "description": "Reply-To addresses." }, "subject": { "type": "string", "minLength": 1, "maxLength": 500 }, "text": { "type": "string" }, "html": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "attachments": { "type": "array", "items": { "type": "object" } }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "inReplyTo": { "type": "string" }, "references": { "type": "array", "items": { "type": "string" } } } }, "AgentReplyInput": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string" }, "html": { "type": "string" }, "replyAll": { "type": "boolean", "default": false }, "attachments": { "type": "array", "items": { "type": "object" } }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } } }, "AgentKey": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "mailboxId": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires": { "type": "string", "description": "ISO timestamp, or empty for a key that never expires." }, "revoked": { "type": "string" }, "lastUsed": { "type": "string" }, "created": { "type": "string", "description": "UTC timestamp string." }, "state": { "type": "string" }, "token": { "type": "string", "description": "The key, shown only in this response." } }, "required": [ "id", "name", "mode", "mailboxId", "scopes", "expires", "revoked", "lastUsed", "created", "state", "token" ] }, "MailApp": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "clientId": { "type": "string", "description": "The OAuth client_id: mhq_mapp_." }, "name": { "type": "string", "description": "Shown to mailbox users on the consent page." }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "mail.read", "mail.send", "mail.modify" ] } }, "grants": { "type": "integer", "minimum": 0, "description": "Mailboxes with a working authorization." }, "created": { "type": "string", "description": "UTC timestamp string." }, "revoked": { "type": [ "string", "null" ], "description": "When it was revoked." } }, "required": [ "id", "clientId", "name", "redirectUris", "scopes", "grants", "created", "revoked" ], "example": { "id": "app4k2p9x7q1w3z", "clientId": "mhq_mapp_app4k2p9x7q1w3z", "name": "Acme CRM", "redirectUris": [ "https://crm.example.com/oauth/callback" ], "scopes": [ "mail.read", "mail.send" ], "grants": 3, "created": "2026-11-13T09:00:00.000Z", "revoked": null } }, "CreateMailAppInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "redirectUris": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "format": "uri" }, "description": "https on a public host, or http on the loopback (127.0.0.1, localhost) for a native or command-line app." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "mail.read", "mail.send", "mail.modify" ] }, "default": [ "mail.read" ], "description": "What the app may ask for." } }, "required": [ "name", "redirectUris" ] }, "TraceStep": { "type": "object", "additionalProperties": false, "properties": { "at": { "type": "string", "description": "UTC timestamp string." }, "kind": { "type": "string", "enum": [ "accepted", "queued", "attempt", "tls", "delivered", "deferred", "rejected", "bounced", "notification", "completed", "info" ], "description": "What the event means on the timeline." }, "event": { "type": "string", "description": "The mail server's event id, such as delivery.delivered." }, "recipient": { "type": [ "string", "null" ], "description": "The recipient the step is about; null for a step about the whole message." }, "host": { "type": [ "string", "null" ], "description": "The remote host." }, "code": { "type": [ "integer", "null" ], "description": "The SMTP reply code." }, "response": { "type": [ "string", "null" ], "description": "The remote server's text, or the reason the mail server logged." }, "nextRetry": { "type": [ "string", "null" ], "description": "When the next attempt is due, on a deferral." } }, "required": [ "at", "kind", "event", "recipient", "host", "code", "response", "nextRetry" ], "example": { "at": "2026-01-02T03:04:07Z", "kind": "delivered", "event": "delivery.delivered", "recipient": "bob@example.net", "host": "mx.example.net", "code": 250, "response": "2.0.0 Ok: queued as 4F2A1", "nextRetry": null } }, "TraceMessage": { "type": "object", "additionalProperties": false, "properties": { "queueId": { "type": "string", "description": "The mail server's queue id." }, "serverId": { "type": "string", "description": "The mail server (an id of listServers)." }, "server": { "type": "string", "description": "Its host name." }, "from": { "type": "string", "description": "Envelope sender; empty for a bounce." }, "to": { "type": "array", "items": { "type": "string" } }, "messageId": { "type": [ "string", "null" ], "description": "The Message-ID header, when the log has it." }, "size": { "type": [ "integer", "null" ], "description": "Size in bytes, when the log has it." }, "at": { "type": "string", "description": "UTC timestamp string." }, "remoteIp": { "type": [ "string", "null" ], "description": "Where the message was accepted from, when the log says." }, "authenticatedAs": { "type": [ "string", "null" ], "description": "The account that submitted it; null for mail from outside." }, "origin": { "type": [ "string", "null" ], "enum": [ "authenticated", "inbound", "dsn", "report", "autogenerated", null ], "description": "How the message entered the queue." }, "status": { "type": "string", "enum": [ "delivered", "deferred", "bounced", "partial", "queued", "unknown" ], "description": "delivered, deferred (waiting for a retry), bounced, partial (some recipients delivered), queued (no attempt in the log yet) or unknown." }, "tls": { "type": [ "boolean", "null" ], "description": "Whether a delivery used TLS; null when the log has no TLS step." }, "dkimSigned": { "type": [ "boolean", "null" ], "description": "false when the log says signing failed; otherwise null: the mail server logs no event for a successful signature." }, "partialTimeline": { "type": "boolean", "description": "true when the message came from outside and also went to recipients outside the key's workspace: the steps that name no recipient (an attempt starting, TLS, finished) are then left out, because they may belong to another recipient's delivery, and `steps` is only part of what happened." }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/TraceStep" } } }, "required": [ "queueId", "serverId", "server", "from", "to", "messageId", "size", "at", "remoteIp", "authenticatedAs", "origin", "status", "tls", "dkimSigned", "partialTimeline", "steps" ], "example": { "queueId": "9001", "serverId": "serverexample01", "server": "mail.example.com", "from": "alice@example.com", "to": [ "bob@example.net" ], "messageId": "", "size": 2048, "at": "2026-01-02T03:04:05Z", "remoteIp": "198.51.100.7", "authenticatedAs": "alice@example.com", "origin": "authenticated", "status": "delivered", "tls": true, "dkimSigned": null, "partialTimeline": false, "steps": [ { "at": "2026-01-02T03:04:05Z", "kind": "queued", "event": "queue.authenticated-message-queued", "recipient": null, "host": null, "code": null, "response": null, "nextRetry": null }, { "at": "2026-01-02T03:04:07Z", "kind": "delivered", "event": "delivery.delivered", "recipient": "bob@example.net", "host": "mx.example.net", "code": 250, "response": "2.0.0 Ok: queued as 4F2A1", "nextRetry": null } ] } }, "TraceQueuedMessage": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The queue entry's id." }, "serverId": { "type": "string" }, "server": { "type": "string" }, "from": { "type": "string", "description": "Envelope sender." }, "createdAt": { "type": "string", "description": "UTC timestamp string." }, "nextRetry": { "type": [ "string", "null" ], "description": "When the next delivery attempt is due." }, "recipients": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string" }, "status": { "type": "string", "enum": [ "scheduled", "completed", "temporaryFailure", "permanentFailure" ] }, "retryCount": { "type": "integer", "minimum": 0 }, "retryDue": { "type": "string", "description": "UTC timestamp string." }, "host": { "type": [ "string", "null" ], "description": "The remote host of the last attempt." }, "code": { "type": [ "integer", "null" ], "description": "Its SMTP reply code." }, "response": { "type": [ "string", "null" ], "description": "Its text." } }, "required": [ "address", "status", "retryCount", "retryDue", "host", "code", "response" ] } } }, "required": [ "id", "serverId", "server", "from", "createdAt", "nextRetry", "recipients" ] }, "TraceResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/TraceMessage" } }, "queued": { "type": "array", "items": { "$ref": "#/components/schemas/TraceQueuedMessage" } }, "searchedBack": { "type": [ "string", "null" ], "description": "The oldest log entry of the key's own messages that this call reached; null when it reached none. It says nothing about how far the server's logs go." }, "servers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "server": { "type": "string" }, "exhausted": { "type": "boolean", "description": "Nothing more of the workspace's messages can be found on this server with this search: the same as `cursor` having no entry for it." }, "error": { "type": [ "string", "null" ], "description": "Set when the server's logs could not be read." }, "oldest": { "type": [ "string", "null" ], "description": "The oldest log entry of the key's own messages reached on this server." } }, "required": [ "id", "server", "exhausted", "error", "oldest" ] } } }, "required": [ "messages", "queued", "searchedBack", "servers" ] }, "cursor": { "type": [ "string", "null" ], "description": "Pass it back as `cursor` for older entries; null when nothing more of the workspace's messages was found." } }, "required": [ "data", "cursor" ] }, "ErrorResponse": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] }, "Forwarder": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Forwarding rule ID." }, "source": { "type": "string", "description": "Source address; read-only advanced rules may contain wildcards.", "example": "help@example.com" }, "destinations": { "type": "array", "items": { "type": "string", "description": "Forwarding destinations; read-only advanced rules may contain special delivery targets." }, "example": [ "support@example.com" ] }, "readonly": { "type": "boolean", "description": "When true, the rule cannot be modified or deleted through this API." }, "note": { "type": "string" } }, "required": [ "id", "source", "destinations" ] }, "MailDnsCheck": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string", "description": "DNS check identifier." }, "type": { "type": "string", "enum": [ "MX", "TXT", "CNAME", "SRV" ] }, "name": { "type": "string", "example": "example.com" }, "value": { "type": "string", "description": "Expected public DNS record value." }, "priority": { "type": "integer" }, "purpose": { "type": "string", "enum": [ "ownership", "mx", "spf", "dkim", "dmarc", "mta-sts-host", "mta-sts", "tls-rpt", "dmarc-report", "autoconfig-host", "client-discovery" ] }, "required": { "type": "boolean" }, "status": { "type": "string", "enum": [ "matched", "missing", "conflict", "error", "pending" ] }, "observed": { "type": "array", "items": { "type": "string", "description": "DNS record values actually observed." } }, "message": { "type": "string" } }, "required": [ "key", "type", "name", "value", "purpose", "required", "status", "observed", "message" ] }, "DomainOnboarding": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9]{15}$", "description": "MailHQ record ID: 15 lowercase letters or digits; not a domain, email address or upstream server ID." }, "name": { "type": "string" }, "subscriptionId": { "type": "string" }, "server": { "type": "string", "description": "Public hostname of the mail server." }, "state": { "type": "string", "enum": [ "pending", "provisioning", "active", "uncertain" ] }, "domainId": { "type": [ "string", "null" ] }, "remoteDomainId": { "type": [ "string", "null" ] }, "ownershipVerifiedAt": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "description": "UTC timestamp string." }, "created": { "type": "string", "description": "UTC timestamp string." }, "updated": { "type": "string", "description": "UTC timestamp string." } }, "required": [ "id", "name", "subscriptionId", "server", "state", "domainId", "remoteDomainId", "ownershipVerifiedAt", "expiresAt", "created", "updated" ] }, "DomainTransportSecurity": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "needs_setup", "dns_pending", "certificate_pending", "ready", "error" ] }, "policyUrl": { "type": "string", "format": "uri", "description": "The domain's HTTPS MTA-STS policy URL." }, "mode": { "type": [ "string", "null" ], "description": "The MTA-STS policy mode that was read; null until the policy has been read." }, "reportAddress": { "type": "string", "format": "email", "description": "The mailbox that receives TLS-RPT aggregate reports." }, "message": { "type": "string", "description": "Description of the current transport security state." }, "canPrepare": { "type": "boolean", "description": "Whether transport security can be verified and configured for this domain." } }, "required": [ "state", "policyUrl", "mode", "reportAddress", "message", "canPrepare" ], "description": "Transport security checks DNS, the HTTPS policy and the certificate separately; ready is not inferred from the mail DNS state." }, "DomainConnection": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "example": "example.com" }, "server": { "type": "string", "description": "Public hostname of the mail server." }, "onboarding": { "anyOf": [ { "$ref": "#/components/schemas/DomainOnboarding" }, { "type": "null" } ] }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/MailDnsCheck" } }, "checkedAt": { "type": "string", "description": "UTC timestamp string." }, "ready": { "type": "boolean", "description": "Basic mail DNS check result; see transportSecurity for the transport security state." }, "legacy": { "type": "boolean", "description": "true means a legacy imported domain without recorded ownership verification; it does not mean verification passed." }, "transportSecurity": { "$ref": "#/components/schemas/DomainTransportSecurity" } }, "required": [ "name", "server", "onboarding", "records", "checkedAt", "ready", "legacy" ], "description": "The domain's public DNS, connection and recorded ownership status, without server admin credentials." }, "Capabilities": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "string", "const": "v1" }, "backend": { "type": "string", "const": "stalwart" }, "authentication": { "type": "string", "const": "bearer" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "domains:read", "domains:write", "mailboxes:read", "mailboxes:write", "forwarders:read", "forwarders:write", "aliases:read", "aliases:write", "lists:read", "lists:write", "holds:read", "holds:write", "agent_tasks:read", "agent_tasks:write", "webhooks:read", "webhooks:write", "suppressions:read", "suppressions:write", "trace:read", "emails:read", "emails:write", "inbound:read", "inbound:write", "agent_mailboxes:read", "agent_mailboxes:write", "mail_apps:read", "mail_apps:write" ] } }, "operations": { "type": "object", "additionalProperties": false, "properties": { "domainList": { "type": "boolean", "const": true }, "domainOnboarding": { "type": "boolean", "const": true }, "domainImport": { "type": "boolean", "const": true }, "domainStatus": { "type": "boolean", "const": true }, "domainAliases": { "type": "boolean", "const": true }, "domainRemove": { "type": "string", "const": "local_only" }, "mailboxCrud": { "type": "boolean", "const": true }, "mailboxStatus": { "type": "boolean", "const": true }, "mailboxQuota": { "type": "boolean", "const": true }, "forwarders": { "type": "boolean", "const": true }, "aliasCrud": { "type": "boolean", "const": true }, "distributionLists": { "type": "boolean", "const": true }, "batchManagement": { "type": "boolean", "const": true }, "dns": { "type": "boolean", "const": true }, "catchAll": { "type": "boolean", "const": true }, "autoresponder": { "type": "boolean", "const": false }, "spamRules": { "type": "boolean", "const": false }, "sendingLimits": { "type": "boolean", "const": true }, "mailContent": { "type": "boolean", "const": false }, "smtpSend": { "type": "boolean", "const": false }, "agentTasks": { "type": "boolean", "const": true }, "webhooks": { "type": "boolean", "const": true } }, "required": [ "domainList", "domainOnboarding", "domainImport", "domainStatus", "domainAliases", "domainRemove", "mailboxCrud", "mailboxStatus", "mailboxQuota", "forwarders", "aliasCrud", "distributionLists", "batchManagement", "dns", "catchAll", "autoresponder", "spamRules", "sendingLimits", "mailContent", "smtpSend", "agentTasks", "webhooks" ] }, "limits": { "type": "object", "additionalProperties": false, "properties": { "perPage": { "type": "integer", "const": 100 }, "maxJsonBytes": { "type": "integer", "const": 16384 }, "maxBatchOperations": { "type": "integer", "const": 25 }, "requestsPerMinute": { "type": "integer", "minimum": 0, "description": "Requests one API key may make per minute, REST and MCP together; 0 means no limit is set." } }, "required": [ "perPage", "maxJsonBytes", "maxBatchOperations", "requestsPerMinute" ] }, "compatibility": { "type": "string", "const": "MailHQ REST API v1" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live: the key acts in its workspace. test: it acts in the workspace's sandbox, whose mail server is simulated: nothing is delivered and no DNS is looked up." }, "sandbox": { "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "domainZone": { "type": "string", "description": "Every domain of the sandbox must end with this name (for example example.acme.test); its ownership check passes without DNS." }, "unsupportedPaths": { "type": "array", "items": { "type": "string", "description": "Path templates a test key is refused with 403 test_mode_unsupported." } } }, "required": [ "domainZone", "unsupportedPaths" ] } ], "description": "Set for a test key only." } }, "required": [ "version", "backend", "authentication", "scopes", "operations", "limits", "compatibility", "mode", "sandbox" ], "description": "Stalwart backend and current API boundaries." } } } }