# Wildmail API

Browse the HTTP operations implemented on your Wildmail application origin.

## Operation reference

- [Account](https://docs.wildmail.app/docs/api/generated/account.md): Read account status and manage message retention or account deletion.
- [API keys](https://docs.wildmail.app/docs/api/generated/api-keys.md): Manage scoped credentials for one individual Wildmail account.
- [Authentication](https://docs.wildmail.app/docs/api/generated/authentication.md): Account sign-in and security through the hosted application.
- [Billing](https://docs.wildmail.app/docs/api/generated/billing.md): Manage billing for one individual Wildmail account.
- [Delete an exact-address route](https://docs.wildmail.app/docs/api/generated/delete-api-domains-id-routes-route-id.md): Removes the exact route so future mail to that address uses the domain catch-all, if configured. Unmatched addresses are rejected when no catch-all is configured. Previously accepted messages retain their pinned route and endpoint revisions.
- [Delete custom domain](https://docs.wildmail.app/docs/api/generated/delete-api-domains-id.md): Signed-in browser session or a scoped API key. Removes a custom domain and refreshes admission routing.
- [Revoke API key](https://docs.wildmail.app/docs/api/generated/delete-api-keys-id.md): Browser session only, signed-in account owner. Revokes an active key immediately. An already revoked or missing key returns 404.
- [Delete webhook endpoint](https://docs.wildmail.app/docs/api/generated/delete-api-webhooks-id.md): Signed-in browser session or scoped API key. Refreshes affected domain routing. Related delivery history is removed with the endpoint.
- [Deliveries](https://docs.wildmail.app/docs/api/generated/deliveries.md): Inspect delivery attempts and replay eligible retained messages.
- [Domains](https://docs.wildmail.app/docs/api/generated/domains.md): Verify custom domains and assign their receiving destinations.
- [Get account settings](https://docs.wildmail.app/docs/api/generated/get-api-account.md): Returns the signed-in user's Wildmail account, current plan and configured message retention.
- [Browser authentication action](https://docs.wildmail.app/docs/api/generated/get-api-auth-path.md): Browser authentication for the hosted application. Use the Wildmail sign-in and security screens to manage sessions and second-factor challenges. Server integrations use scoped API keys. The path parameter can contain multiple segments. This wildcard is not a literal endpoint.
- [Get billing summary](https://docs.wildmail.app/docs/api/generated/get-api-billing.md): Browser session only, signed-in account. configured reports whether billing is available.
- [Inspect delivery and attempts](https://docs.wildmail.app/docs/api/generated/get-api-deliveries-id.md): Returns the delivery summary, message availability, and content-free attempt history.
- [List deliveries](https://docs.wildmail.app/docs/api/generated/get-api-deliveries.md): Returns the account's delivery history, newest first, 25 per page. Optional status filters narrow the results. Content-free delivery summaries and attempt history remain available after message content expires.
- [List exact-address routes for a custom domain](https://docs.wildmail.app/docs/api/generated/get-api-domains-id-routes.md): Lists this domain's exact local-part routes and the account-wide route allowance. UTF-8 local parts are trimmed, Unicode-normalized, and lowercased before matching. Unicode domains use lowercase IDNA ASCII for lookup. Matching is case-insensitive. Plus-tags are preserved literally and are not stripped. Exact matches take precedence over the domain catch-all. A matching exact route can accept mail without a catch-all endpoint. Unmatched addresses are rejected if no catch-all is configured. A suspended exact route or one whose endpoint is unavailable is rejected during SMTP admission instead of falling through to catch-all.
- [List custom domains](https://docs.wildmail.app/docs/api/generated/get-api-domains.md): Hosted test addresses are excluded. Returns DNS instructions, readiness and the custom-domain allowance.
- [Get hosted test address](https://docs.wildmail.app/docs/api/generated/get-api-hosted-address.md): A browser session provisions an address if needed. API keys only read an assigned address and receive 404 if none exists. ready means an active endpoint is linked.
- [List API keys and scopes](https://docs.wildmail.app/docs/api/generated/get-api-keys.md): Browser session only, signed-in account. Lists key metadata and availableScopes. Token secrets are never returned.
- [Download a retained attachment](https://docs.wildmail.app/docs/api/generated/get-api-messages-id-attachments-attachment-id.md): Streams a retained attachment while the account's current retention policy permits access. Requires the account's messages:read scope or a signed-in session. The response uses a safe Content-Disposition filename and private, no-store caching.
- [Preview message body](https://docs.wildmail.app/docs/api/generated/get-api-messages-id-preview.md): Returns a sanitized text or HTML preview of a retained message. Access follows the account's current retention policy.
- [Download raw MIME](https://docs.wildmail.app/docs/api/generated/get-api-messages-id-raw.md): Streams the retained RFC 822 email with private, no-store caching. Access follows the account's current retention policy.
- [Inspect received message](https://docs.wildmail.app/docs/api/generated/get-api-messages-id.md): Returns a message summary, parsed message details while content is available, and its delivery summaries. The message ID is the 24-character receiptId from GET /api/messages. Message content and attachments follow the account's current retention policy.
- [Search received messages](https://docs.wildmail.app/docs/api/generated/get-api-messages.md): Returns the account's message history, newest first, 25 per page. Search q matches message ID, event ID, retained sender/recipient, subject and Message-ID. Supported status filters are returned by the API. Expired summaries hide message content.
- [Inspect a retained thread](https://docs.wildmail.app/docs/api/generated/get-api-threads-id.md): Returns the complete retained thread summary and its message summaries, oldest receipt first with a stable message ID tie-breaker, 25 messages per page. Current retention applies to both counts and members. Unknown, foreign-account, fully expired and zero-day threads return 404. IDs are the threadId values from message and thread summaries. Each message links to existing preview, raw download, attachment and delivery APIs.
- [List retained threads](https://docs.wildmail.app/docs/api/generated/get-api-threads.md): Lists account-scoped retained conversations, 25 groups per page, sorted by latest receipt descending with a stable ID tie-breaker. q and status match a retained member, including older members. Counts and latestMessage describe the complete retained thread. Search is a literal case-insensitive substring across sender, routed recipient, subject, Message-ID, receipt ID, event ID and thread ID. Combined filters must match the same member. Unthreaded messages appear individually with threadId null. Zero-day retention returns an empty list. Expired delivery audits are accessible through individual messages, not threads.
- [Get account usage](https://docs.wildmail.app/docs/api/generated/get-api-usage.md): Returns the account plan, UTC-month accepted-message allowance, custom domains, exact-address routes, storage quota and current retention setting.
- [Inspect webhook endpoint](https://docs.wildmail.app/docs/api/generated/get-api-webhooks-id.md): Returns the account's endpoint and its content-free delivery summaries, 10 per page. API keys also need deliveries:read to see delivery history. Otherwise deliveries is [] and pagination is null.
- [List webhook endpoints](https://docs.wildmail.app/docs/api/generated/get-api-webhooks.md): Returns public endpoint metadata. Signing secrets are never returned by reads.
- [Hosted address](https://docs.wildmail.app/docs/api/generated/hosted-address.md): Connect a hosted test address before changing DNS.
- [Messages](https://docs.wildmail.app/docs/api/generated/messages.md): Search, inspect, and download retained messages and attachments.
- [Delete account](https://docs.wildmail.app/docs/api/generated/post-api-account-delete.md): Disables sign-in and inbound mail, cancels an active subscription, schedules removal of retained message content, and deletes account and authentication records. This operation cannot be undone. The request must come from the application origin and include the exact confirmation text.
- [Browser authentication action](https://docs.wildmail.app/docs/api/generated/post-api-auth-path.md): Browser authentication for the hosted application. Use the Wildmail sign-in and security screens to manage sessions and second-factor challenges. Server integrations use scoped API keys. The path parameter can contain multiple segments. This wildcard is not a literal endpoint.
- [Create checkout session](https://docs.wildmail.app/docs/api/generated/post-api-billing-checkout.md): Browser session only, signed-in account owner. Origin must exactly match the configured application origin. Creates hosted Stripe Checkout for Starter or Growth.
- [Create billing portal session](https://docs.wildmail.app/docs/api/generated/post-api-billing-portal.md): Browser session only, signed-in account owner. No body. Origin must exactly match the configured application origin. Requires an existing Stripe customer. Returns hosted billing portal URL. Cancellation takes effect at the end of the current billing period. The paid plan continues until then.
- [Refresh billing state](https://docs.wildmail.app/docs/api/generated/post-api-billing-sync.md): Browser session only, signed-in account owner. No body. Origin must exactly match the configured application origin. Synchronizes provider state and returns updated summary.
- [Upgrade Starter to Growth](https://docs.wildmail.app/docs/api/generated/post-api-billing-upgrade.md): Browser session only, signed-in account owner. No body. Origin must exactly match the configured application origin. Growth applies after confirmation. The prorated difference is included on the next invoice. Usage does not reset. Resolve outstanding payments or scheduled changes first.
- [Replay delivery](https://docs.wildmail.app/docs/api/generated/post-api-deliveries-id-replay.md): Queues a replay using the same event ID and pinned endpoint/shaping revision. Replay requires retained content under the account's current policy, an active endpoint, and no in-progress attempt. Zero-retention deliveries cannot be replayed.
- [Create an exact-address route](https://docs.wildmail.app/docs/api/generated/post-api-domains-id-routes.md): Creates an exact local-part route to an endpoint in this account. UTF-8 local parts are trimmed, Unicode-normalized, and lowercased before matching. The maximum is 64 UTF-8 bytes. Free has an allowance of zero and returns 409 route_limit_reached. Recognized non-Free plans have unlimited exact routes. Route status is suspended while the effective plan disallows routes. Stored suspended routes remain counted. Hosted test addresses are managed separately.
- [Check domain DNS](https://docs.wildmail.app/docs/api/generated/post-api-domains-id-verify.md): No body. Checks ownership TXT and MX separately with an eight-second DNS timeout. A 200 response may have observed.ownership or observed.mx false. domain.ready reports domain catch-all readiness. With no catch-all, a verified domain with valid MX can still accept matching active exact-address routes with active endpoints.
- [Create a custom domain](https://docs.wildmail.app/docs/api/generated/post-api-domains.md): The authenticated account can create a domain. Domain names normalize to DNS form. Domains reserved for Wildmail service use cannot be added. Configure returned TXT and MX records before verification.
- [Create scoped API key](https://docs.wildmail.app/docs/api/generated/post-api-keys.md): Browser session only, signed-in account. name is 1–80 trimmed characters. scopes is a nonempty unique array of available scope identifiers. token is returned once. Store securely.
- [Preview a draft webhook payload mapping](https://docs.wildmail.app/docs/api/generated/post-api-webhooks-id-preview.md): Evaluates a draft against a supplied sample object without saving or sending. Endpoint must belong to the authenticated account. Null mapping returns the standard body. Missing optional fields are reported in missingPaths, separate from validation errors.
- [Queue a test webhook](https://docs.wildmail.app/docs/api/generated/post-api-webhooks-id-test.md): No body. Endpoint must be active with a saved revision and signing secret. Asynchronously queues a test payload with type: email.test, schema_version: 2026-09-01, and a 24-hour deadline. It is not a parsed email.received payload. Applies the saved payload mapping, which can omit these fields. A 202 response confirms scheduling. Inspect the delivery to determine success.
- [Rotate webhook signing secret](https://docs.wildmail.app/docs/api/generated/post-api-webhooks-id.md): Rotates the endpoint signing secret. The new secret is returned once. Accepted messages continue to use their pinned signing-key version.
- [Create webhook endpoint](https://docs.wildmail.app/docs/api/generated/post-api-webhooks.md): name is trimmed (1–80 characters). Description is at most 300 characters. Destinations require public HTTPS on port 443 and pass DNS/address checks. Save signingSecret now: it is returned once. Optional payloadMapping shapes the complete body. Omit it or use null for the standard body.
- [Update account retention](https://docs.wildmail.app/docs/api/generated/put-api-account.md): Sets account retention in whole days. The setting applies to existing and newly received messages. Zero permits at most one self-contained webhook attempt with no retry or replay.
- [Update an exact-address route](https://docs.wildmail.app/docs/api/generated/put-api-domains-id-routes-route-id.md): Replaces the route's local part and endpoint for future accepted mail. UTF-8 local parts (at most 64 UTF-8 bytes) are trimmed, Unicode-normalized, and lowercased before matching. Plus-tags are preserved literally and are not stripped. Previously accepted messages retain their pinned route and endpoint revisions.
- [Set domain destination](https://docs.wildmail.app/docs/api/generated/put-api-domains-id.md): Requires endpointId. Set null or an empty string to disconnect. Hosted addresses use /api/hosted-address. Newly accepted messages use the selected destination, while previously accepted messages keep the destination recorded at acceptance.
- [Set hosted address destination](https://docs.wildmail.app/docs/api/generated/put-api-hosted-address.md): Requires endpointId: a UUID in this account or null to disconnect. Provisions the address if necessary.
- [Update webhook endpoint](https://docs.wildmail.app/docs/api/generated/put-api-webhooks-id.md): Updates any supplied endpoint fields: name, URL, description, status, and payload mapping. Newly accepted messages pin the endpoint destination and shaping revision. Pending deliveries keep those pinned revisions. Pausing an endpoint stops sends.
- [Threads](https://docs.wildmail.app/docs/api/generated/threads.md): Browse retained conversations and their chronological messages.
- [Usage](https://docs.wildmail.app/docs/api/generated/usage.md): Inspect account plan, monthly message allowance, mailbox quota, and retention.
- [Webhook endpoints](https://docs.wildmail.app/docs/api/generated/webhook-endpoints.md): Manage endpoint destinations, signing secrets and test events.
- [Wildmail API](https://docs.wildmail.app/docs/api/generated/wildmail-api.md): Customer API for individual Wildmail accounts. Management scopes are recorded in x-required-scope. Account settings, billing, and API key management require a signed-in browser session. Use the hosted application to sign in and manage security factors. Events contain parsed email and can be reshaped with an endpoint payload mapping.
