# Wildmail documentation > Documentation for the implemented inbound email service. API origin and documentation origin are separate. # Authentication # Authentication Use a scoped API key for server integrations. Sign in to the hosted application to manage your account, API keys, security settings, and billing. ## API keys Create a key in **Settings** and grant only the scopes your integration needs. The plaintext key is shown once. Store it in a secret manager and keep it out of browser code, URLs, logs, and shared examples. ```bash curl --fail-with-body "https://wildmail.app/api/messages" \ -H "Authorization: Bearer $WILDMAIL_API_KEY" ``` A key accesses resources in the account where it was created. A missing or invalid key returns **401**. A valid key without the required scope returns **403**. When an `Authorization` header is present, it takes precedence over browser session cookies, even if the key is invalid. Revoke a key in **Settings** to stop future requests using it. Account settings, account deletion, key management, and billing require a signed-in browser session. API keys cannot perform those actions. See the [API reference](https://docs.wildmail.app/docs/api/reference.md) for each operation's required scope and authentication method. ## Sign in to your account Email-code sign-in is the default option. Enter your email, request a six-digit code, and use it within five minutes. Each code works once and allows three verification attempts. Requesting a new code replaces the previous one. Password sign-in is also available. Registration is available only when enabled for the hosted service. If you have enabled two-factor authentication, email-code and password sign-in also require your authenticator, security key, or recovery code. A sign-in email code is the first step and does not replace your second factor. Google and GitHub sign-in use the provider's authentication, so protect those accounts with the provider's security controls. Use **Settings** to enroll and manage authenticators, security keys, and recovery codes. Sign in with email first to manage these settings. Save recovery codes when they are shown. Replacing them invalidates the previous set. Password reset links are single-use and expire after one hour. Completing a reset signs out existing sessions and preserves second-factor settings. For more account-security behavior, see [Integration and account security](https://docs.wildmail.app/docs/guides/security.md). ## Webhook signatures A Wildmail API key authenticates requests from your application to Wildmail. An endpoint's signing secret lets your receiver authenticate incoming webhook requests. They are separate credentials and rotate independently. Follow [Verify and consume webhooks](https://docs.wildmail.app/docs/guides/webhooks.md) to validate signatures against the exact request bytes and deduplicate retries by event ID. # API reference # API reference Use `https://wildmail.app` as the API base. The documentation site at `https://docs.wildmail.app` does not serve API requests. Download the [OpenAPI 3.1 specification](/openapi.json) for request and response schemas. Browser authentication is documented in [Authentication](https://docs.wildmail.app/docs/api/authentication.md). Each customer has one Wildmail account. Domains, routes, hosted addresses, webhook endpoints, messages, deliveries, billing, and API keys belong to that account. ## Authentication and errors Customer management routes accept an account API key or signed-in browser session unless the table below says **Browser session**. API keys cannot manage account settings, billing, or other API keys. Keep API keys on your server and grant only the required scopes. If an `Authorization` header is present, it takes precedence over session cookies, even when the key is invalid. Most errors are JSON `{ "error": "Human-readable explanation" }`. Some quota and conflict responses also include a stable `code` and `limit`. Use HTTP status and documented error codes for branching rather than matching message text. Dates are ISO 8601 timestamps. The message `receiptId` is a 24-character hexadecimal identifier. Other resource IDs are opaque strings. ```bash export WILDMAIL_API_BASE="https://wildmail.app" export WILDMAIL_API_KEY="your-secret-kmx-token" curl --fail-with-body "$WILDMAIL_API_BASE/api/messages?page=1" \ -H "Authorization: Bearer $WILDMAIL_API_KEY" ``` Key creation returns the plaintext token once. `GET /api/keys` lists available scopes. Create, list, and revoke keys from the signed-in dashboard. ## Request rate limits Requests share limits by client IP: **300 per 60 seconds** and **60 per 10 seconds**. Authenticated management, billing, key management, account settings, and message downloads also share account limits: **600 per 60 seconds** and **100 per 10 seconds**. Dashboard requests and API-key requests from one account use the same account allowance. An exhausted allowance returns **429** with JSON `code: "rate_limit_exceeded"`, `Retry-After` in seconds, and `Cache-Control: no-store`. When the service cannot enforce request limits, it returns **503** with JSON `code: "rate_limit_unavailable"`. Authentication endpoints also have endpoint-specific limits. ## Customer routes API-key scopes shown in this table apply to API-key requests. Routes marked **Browser session** require a signed-in browser session and the expected application `Origin` on mutations. | Method | Path | Authentication | | --- | --- | --- | | GET | `/api/account` | Browser session | | PUT | `/api/account` | Browser session | | POST | `/api/account/delete` | Browser session | | GET | `/api/domains` | `domains:read` | | POST | `/api/domains` | `domains:write` | | PUT | `/api/domains/{id}` | `domains:write` | | DELETE | `/api/domains/{id}` | `domains:admin` | | POST | `/api/domains/{id}/verify` | `domains:write` | | GET | `/api/domains/{id}/routes` | `domains:read` | | POST | `/api/domains/{id}/routes` | `domains:write` | | PUT | `/api/domains/{id}/routes/{routeId}` | `domains:write` | | DELETE | `/api/domains/{id}/routes/{routeId}` | `domains:write` | | GET | `/api/hosted-address` | `domains:read` | | PUT | `/api/hosted-address` | `domains:write` | | GET | `/api/webhooks` | `webhooks:read` | | POST | `/api/webhooks` | `webhooks:write` | | GET | `/api/webhooks/{id}` | `webhooks:read` | | PUT | `/api/webhooks/{id}` | `webhooks:write` | | POST | `/api/webhooks/{id}` | `webhooks:admin` | | DELETE | `/api/webhooks/{id}` | `webhooks:admin` | | POST | `/api/webhooks/{id}/test` | `webhooks:write` | | POST | `/api/webhooks/{id}/preview` | `webhooks:read` | | GET | `/api/deliveries` | `deliveries:read` | | GET | `/api/deliveries/{id}` | `deliveries:read` | | POST | `/api/deliveries/{id}/replay` | `deliveries:replay` | | GET | `/api/messages` | `messages:read` | | GET | `/api/threads` | `messages:read` | | GET | `/api/threads/{id}` | `messages:read` | | GET | `/api/messages/{id}` | `messages:read` | | GET | `/api/messages/{id}/raw` | `messages:read` | | GET | `/api/messages/{id}/preview` | `messages:read` | | GET | `/api/messages/{id}/attachments/{attachmentId}` | `messages:read` | | GET | `/api/usage` | `usage:read` | | GET | `/api/keys` | Browser session | | POST | `/api/keys` | Browser session | | DELETE | `/api/keys/{id}` | Browser session | | GET | `/api/billing` | Browser session | | POST | `/api/billing/checkout` | Browser session | | POST | `/api/billing/upgrade` | Browser session | | POST | `/api/billing/portal` | Browser session | | POST | `/api/billing/sync` | Browser session | | GET, POST | `/api/auth/{path}` | Endpoint-specific browser authentication | ## Domains and receiving addresses Create a custom domain with `POST /api/domains`, configure its TXT and MX records, and verify DNS with `POST /api/domains/{id}/verify`. The hosted test address is managed separately through `/api/hosted-address` and does not consume a custom-domain slot. Exact-address routes use `localPart` and `endpointId`. Wildmail trims, Unicode-normalizes, and lowercases configured UTF-8 local parts. Plus-tags remain literal. Exact routes take precedence over a domain catch-all. If no route matches and no catch-all is configured, Wildmail rejects the recipient during SMTP admission. A suspended route or unavailable endpoint does not fall through to the catch-all. Domain and route limits depend on the account's current plan. A limit conflict returns **409** with a stable code such as `domain_limit_reached` or `route_limit_reached`. See [Receiving domains and DNS](https://docs.wildmail.app/docs/guides/domains.md) for DNS setup and routing behavior. ## Webhook endpoints Create an endpoint with `POST /api/webhooks`. The signing secret is returned once. `PUT /api/webhooks/{id}` updates its name, URL, description, status, or payload mapping. `POST /api/webhooks/{id}` rotates the signing secret. Rotation returns the new secret once. Destination validation requires public HTTPS on port 443. Wildmail sends `email.received` events. The standard payload uses `wildmail.v1`, includes parsed email under `message`, and limits `envelope.recipients` to the addresses matched for that endpoint. Payload shaping can select and rename fields. Preview mappings with `POST /api/webhooks/{id}/preview` before saving them. `POST /api/webhooks/{id}/test` sends a synthetic `email.test` event that does not consume inbound message allowance. When spam metadata is available, `message.is_spam` and `message.spam` carry the verdict and scan details. The boolean is true only for a completed Rspamd scan with a positive verdict; false means no positive verdict, not a guarantee of clean mail. Details include scan `status` (`scanned`, `skipped`, or `error`), `score`, `action`, `required_score`, and scored `symbols`. Explicitly unavailable details yield `spam: null` and `is_spam: false`; older events may omit both keys. Handle missing scan data in your receiver. ### Payload shaping A payload mapping selects JSON Pointer paths from the standard event, renames fields, builds nested objects, and projects arrays. Unmapped fields are omitted. Missing values become `null`, and missing arrays become empty arrays. Mappings do not run scripts, create constants, fetch data, or convert types. Use the dashboard preview or `POST /api/webhooks/{id}/preview` to inspect the output before saving. Verify signatures over the exact raw request bytes. Automatic retries and replay retain the event ID and the endpoint and shaping revision selected when Wildmail accepted the message. Retries preserve the request body. See [Verify and consume webhooks](https://docs.wildmail.app/docs/guides/webhooks.md). ## Messages, deliveries, and replay `GET /api/messages` returns message summaries. `GET /api/messages/{id}` returns a summary, parsed message details while content is available, and related delivery summaries. Raw email and attachments are available from the message routes while allowed by the account's current retention policy. Attachment descriptors use stable Wildmail download routes. Message summaries include `threadId`, the conversation identifier also emitted as `message.thread_id` in webhooks. Treat it as an opaque string. Missing thread metadata returns `null`, and that message appears individually. Expired message summaries return `threadId: null`. `GET /api/threads?q=&status=&page=` lists retained conversations, newest receipt first, with a stable identifier tie-breaker and 25 groups per page. Each summary includes `threadId`, `latestMessage`, `messageCount`, `firstReceivedAt`, `latestReceivedAt`, and `statusCounts` (`pending`, `processing`, `parsed`, `failed`). Counts cover the complete retained thread, even when a search or status filter matches only an older member. `parsed` means complete in the dashboard. Search matches sender, routed recipient, subject, Message-ID, receipt ID, event ID, or thread ID. A combined search and status filter must match the same retained member. Messages without thread metadata appear as individual groups with `threadId: null`. `GET /api/threads/{id}?page=` returns `{ thread, messages, pagination }`, with 25 message summaries per page, oldest receipt first. Unknown IDs, IDs outside your account, and threads with no retained messages return **404**. Thread membership follows message references and normalized subjects. A shared subject alone does not join unrelated messages, and a changed subject can start a separate thread. Thread browsing follows current retention, so expired members disappear from both messages and counts. At 0 days, the thread list is empty. Content-free history remains available through individual messages and deliveries. Delivery history is content-free. `GET /api/deliveries` lists delivery summaries, and `GET /api/deliveries/{id}` includes attempt status and message availability. After message content expires, the API can still return a content-free delivery summary and attempt history. Replay with `POST /api/deliveries/{id}/replay`. Replay uses the pinned endpoint and shaping revision and keeps the stable event ID. It does not count as a new inbound message. Expired content and 0-day deliveries cannot be replayed. A current attempt can return **409**, and unavailable content can return **410**. See [Delivery, retries, and replay](https://docs.wildmail.app/docs/guides/delivery-and-replay.md). ## Usage, settings, and billing `GET /api/usage` reports plan allowances, monthly accepted and reserved messages, custom-domain and exact-route use, retained storage usage, and current retention. `GET /api/account` and `PUT /api/account` manage individual account settings, including retention. The signed-in dashboard handles account API keys and billing. Billing routes create checkout or portal sessions and synchronize subscription state. Retention changes apply to existing messages and affect content access, downloads, retries, and replay under the current policy. At 0 days, Wildmail permits at most one webhook attempt, disables automatic retry and replay, and includes attachment bytes inline as base64. See [Usage, size limits, and retention](https://docs.wildmail.app/docs/guides/usage-and-retention.md). # Account access Each Wildmail customer account belongs to one sign-in identity. Domains, receiving addresses, webhook endpoints, messages, usage, billing, and API keys belong to that account. Use the authentication methods configured for your account. See [Authentication](https://docs.wildmail.app/docs/api/authentication.md) for password, email-code, OAuth, and second-factor behavior. ## API keys Create API keys from **Settings** in the signed-in dashboard. Grant only the scopes your integration needs. A key can access resources in its Wildmail account only. The plaintext token is shown once at creation, so store it in a secret manager and never include it in browser code or public logs. Revoke a key from **Settings** to stop future requests using it. Key creation, listing, and revocation require a signed-in dashboard session. Customer API requests can use the key in `Authorization: Bearer `. ## Delete your account Account deletion is available in **Settings**. Type `DELETE` to confirm. Wildmail disables sign-in and inbound mail, cancels an active subscription, schedules removal of retained message content, and removes the account's API keys and authentication records. This cannot be undone. If cleanup is temporarily unavailable, account access remains disabled. Retry the deletion action to continue cleanup or contact Wildmail support. # Delivery, retries, and replay For messages with positive retention, Wildmail retries eligible delivery failures within the delivery and retention window. Messages with 0-day retention allow at most one HTTP attempt and cannot be retried or replayed. Processing failures, invalid payload mappings, disabled destinations, or expiry can prevent an HTTP attempt. Persist the signed `wildmail-event-id` header atomically with your business changes so retries cannot apply the same action twice. A network failure after your application commits may cause another attempt for a retained message. ## Endpoint responses These retry rules apply to messages with positive retention. A 0-day message is never retried, including after a timeout, `429`, or server error. | Response | Behavior | | --------------------------- | ----------------------------------------------- | | `200`–`299` | Acknowledge delivery. | | Connection error or timeout | Retry while the delivery window remains open. | | `408`, `429`, `500`–`599` | Retry with exponential backoff and jitter. | | Redirect or other status | Mark failed. Investigate and explicitly replay. | ```mermaid flowchart TD A[Send attempt] --> B{Receiver response} B -->|2xx| D[Delivered] B -->|Timeout, connection error, 408, 429, or 5xx| W[Back off] W --> C{Delivery window open?} C -->|Yes| A C -->|No| F[Failed] B -->|Redirect or other status| F F --> X[Fix receiver and explicitly replay] ``` Connection establishment is limited to five seconds. An HTTP attempt has a fifteen-second overall deadline, and Wildmail reads at most 64 KiB of its response body. A received 2xx status acknowledges delivery even if the response body later exceeds the limit or cannot be read completely. Return a small response promptly after a durable application commit or durable enqueue. Automatic retries start at a minimum of ten seconds and back off to a one-hour base interval. Valid `Retry-After` values are respected. If the requested delay exceeds the delivery deadline, the event fails rather than retrying earlier. Automatic delivery ends after 24 hours or content expiry, whichever occurs first. Every attempt has a new attempt ID and signature timestamp. The event ID, endpoint, and shaping revision remain pinned. Retries preserve the request body. Delivery stops if the same event can no longer be rendered with identical bytes. SMTP retransmission creates a separate stored message and may create a separate event. `Message-ID` is sender-supplied and is unsuitable as a universal deduplication key. ## Inspect and replay Open **Deliveries**, select a delivery, inspect its status and content-free attempt history, then choose **Replay** after fixing the receiving application. Replay keeps the same event ID and pinned endpoint and shaping revision. Replay does not consume additional inbound message allowance. Messages with 0-day retention cannot be replayed. ```mermaid flowchart LR A[Automatic delivery window] --> B[Several attempts may occur] B --> C[Same event ID and pinned shaping revision] B --> D[New attempt ID and signature timestamp each time] B --> E[Failed: fix receiver, then explicitly replay] E --> F[Replay requests another delivery window] X[Current content expiry] -. bounds both windows .-> A X -. remains the hard limit .-> F Y[Destination revision captured at acceptance] -. remains pinned .-> F ``` API keys need `deliveries:replay`: ```bash curl --fail-with-body -X POST \ "$WILDMAIL_BASE_URL/api/deliveries/$DELIVERY_ID/replay" \ -H "Authorization: Bearer $WILDMAIL_API_KEY" ``` An in-progress delivery attempt can cause `409` because another attempt is in flight. An inactive endpoint also needs correction before replay. Expired content produces `410`. Retrying the replay request cannot extend retention. Current events preserve the endpoint revision captured at acceptance, including its URL and payload mapping. Editing either changes new messages. Retained deliveries keep their pinned endpoint and mapping. Replay does not apply a newer mapping. Changing a mapping does not repair an existing event that uses an invalid pinned mapping. Correct the mapping for future email and send a new message. Keep your application's deduplication records at least as long as the replay window. Replaying an event already applied successfully should acknowledge the duplicate without repeating side effects. # Receiving domains and DNS Use a dedicated receiving subdomain such as `intake.example.com`. Changing the MX records of your normal mail domain changes where incoming mail is delivered. ## Configure a custom domain 1. Create an active webhook endpoint. 2. In **Receiving domains**, add your domain and select the endpoint. 3. Publish the exact verification TXT value displayed by Wildmail. 4. Publish the MX destination displayed by Wildmail. 5. Select **Check DNS** and wait for the domain to show **Ready**. Example records for `intake.example.com`: | Type | Name | Value | | ---- | ----------------------------- | ---------------------------------------------------- | | TXT | `_wildmail.intake.example.com` | `wildmail-verification=` | | MX | `intake.example.com` | Priority `10`, destination `` | Your DNS provider may expect a relative name such as `_wildmail.intake` rather than a fully qualified name. Avoid adding the zone name twice. Keep other TXT records intact. Check the public answer using your system resolver: ```bash dig TXT _wildmail.intake.example.com dig MX intake.example.com ``` Ownership verification, MX health, billing availability, and an active endpoint all affect readiness. A domain without a usable route is rejected during SMTP recipient admission. Re-run the DNS check after propagation. A TXT success alone does not establish readiness. The domain's **Ready** indicator describes its catch-all endpoint. A domain configured only with exact-address routes can still accept mail for those addresses when DNS, billing, the plan, and each route's endpoint allow it, even without a Ready catch-all. Wildmail automatically rechecks custom-domain TXT ownership and MX records every hour. If a check confirms that the ownership TXT is missing or incorrect, the domain returns to **Pending**. Missing or incorrect MX records mark MX setup as needed. Either condition stops new mail from being accepted for that domain. Once DNS is corrected, a later scheduled check can restore readiness. Temporary DNS lookup failures leave the last confirmed status in place. ```mermaid flowchart TD A[TXT proves ownership] --> E{All readiness checks pass?} B[MX points to Wildmail] --> E C[Active catch-all endpoint] --> E D[Billing available] --> E E -->|Yes| R[Ready to receive] E -->|No| F[Fix DNS or account setup] F --> V[Check DNS again] V --> E ``` ## Routing behavior Verified custom domains can use exact-address routes alongside the domain catch-all. An exact match such as `orders+acme@intake.example.com` goes to its configured endpoint first. Wildmail trims, Unicode-normalizes, and lowercases the configured UTF-8 local part before matching, so uppercase and lowercase forms use the same route. Unicode domain names are normalized with IDNA to lowercase ASCII before lookup. Plus-tags remain literal and are not stripped, so `orders+acme@intake.example.com` is distinct from `orders@intake.example.com`. Patterns and named parameters are not supported. When no exact route matches, Wildmail uses the domain's selected catch-all endpoint, if one is configured. A matching exact route can accept mail without a catch-all endpoint. Unmatched addresses are rejected when no catch-all is configured. A matching route that is suspended by the plan or has an unavailable endpoint is rejected during SMTP admission. It does not fall back to catch-all. Deleting the exact route restores catch-all behavior for future mail to that address, if configured. ```mermaid flowchart LR I["orders+acme@intake.example.com"] --> X{Exact route exists?} X -->|Yes| A{Route and endpoint active?} A -->|Yes| RE[Exact route endpoint] A -->|No| S[Not accepted] X -->|No| C{Catch-all configured?} C -->|Yes| CA{Catch-all endpoint active?} CA -->|Yes| E[Catch-all endpoint] CA -->|No| N[Not accepted] C -->|No| N[Not accepted] H[Assigned hosted address] --> HE[Its selected endpoint] U[Other hosted-domain address] --> HU[Not accepted] ``` Free includes domain catch-all routing. Starter and Growth also include unlimited exact-address routes. The allowance is shared across the individual account's customer-owned domains. Suspended routes stay stored and count toward usage. Upgrading restores them. The hosted test address remains separate and keeps its own endpoint assignment. Wildmail pins the matched route and endpoint destination when it accepts a message, so later configuration edits do not redirect that message. Pausing an endpoint stops pending sends. [Replay](https://docs.wildmail.app/docs/guides/delivery-and-replay.md) uses the delivery's pinned endpoint revision. Manage custom-domain routes with the [domain routes API](https://docs.wildmail.app/docs/api/reference.md). ## Hosted address Each account also has an assigned hosted test address. It needs an active endpoint and no customer DNS records. The hosted address does not consume a custom-domain slot. Only the receiving address assigned to your account accepts mail. ## Limits Pending and suspended custom domains count toward your domain allowance. Deleting a custom domain releases its slot. The API returns `409` with `code: domain_limit_reached` when creation would exceed the allowance. See [usage and retention](https://docs.wildmail.app/docs/guides/usage-and-retention.md). SMTP intake also applies limits to source-IP connections, source-IP message attempts, and messages for each receiving domain. Multiple recipients at one domain in the same SMTP transaction count once toward that domain's rate limit. Assigned hosted addresses use account-specific message limits, so unrelated customers do not share one hosted-domain allowance. Exceeding a rate limit temporarily refuses the SMTP command. The sending server should retry later. Rate limits are separate from monthly message and storage allowances. # Receive your first email ## 1. Create a webhook endpoint Sign in to Wildmail, open **Webhooks**, and create an endpoint for your application. Destinations must be publicly reachable HTTPS URLs on port 443. Save the signing secret when Wildmail displays it. It is shown once. Store it in your application's secret manager, separately from your Wildmail API key. Implement the [webhook receiver example](https://docs.wildmail.app/docs/guides/webhooks.md) before receiving real data. Select **Send test**. This sends an `email.test` event and checks endpoint reachability and signature verification. It does not receive email through SMTP or consume an inbound message. ## 2. Assign your hosted address Open **Receiving domains** and attach the active endpoint to your hosted test address. Copy the exact address shown in your account. You do not need DNS access for this address. Only your assigned address accepts mail. The hosted domain is not a customer catch-all. Hosted messages count toward your account's monthly message allowance. ## 3. Send an email Send an email from your normal email client to that address. Include a subject, a short body, and an optional small attachment. Wildmail parses and stores the email before accepting it. Wildmail then sends an `email.received` event to the endpoint. Use **Messages** to inspect the received email and authentication results. Use **Deliveries** to inspect HTTP attempts and replay retained events. A successful SMTP submission and a successful webhook delivery are separate outcomes. For this walkthrough, keep retention at 1 or more days so you can inspect content and try replay. With 0-day retention, Wildmail allows at most one webhook attempt after parsing. Its standard payload includes inline bodies and base64 attachments instead of download URLs. It does not retry or allow replay, and message content is cleared after the attempt settles or its deadline passes. See [usage and retention](https://docs.wildmail.app/docs/guides/usage-and-retention.md). ## 4. Read state through the API Create an API key with `domains:read`, `messages:read`, and `deliveries:read`. The following shell examples assume the Wildmail application URL and key are already set: ```bash export WILDMAIL_BASE_URL="https://wildmail.app" export WILDMAIL_API_KEY="your-api-key" curl --fail-with-body "$WILDMAIL_BASE_URL/api/hosted-address" \ -H "Authorization: Bearer $WILDMAIL_API_KEY" curl --fail-with-body "$WILDMAIL_BASE_URL/api/messages" \ -H "Authorization: Bearer $WILDMAIL_API_KEY" curl --fail-with-body "$WILDMAIL_BASE_URL/api/deliveries?page=1" \ -H "Authorization: Bearer $WILDMAIL_API_KEY" ``` Keep API keys on your server. See the [API reference](https://docs.wildmail.app/docs/api/reference.md) for all routes and [custom domains](https://docs.wildmail.app/docs/guides/domains.md) to use your own address. # Integration and account security Wildmail API keys authenticate your application's requests to Wildmail. Endpoint signing secrets authenticate Wildmail webhook bodies to your receiver. They serve different purposes and rotate independently. ```mermaid flowchart LR A[Your application] -->|Scoped API key authenticates request| K[Wildmail API] K -->|Webhook signed with endpoint secret| R[Your receiver] R --> V[Verify signature against exact raw body] A -->|Authenticated message or attachment request| O[Retained message content] ``` ## Credentials and permissions Create keys with the smallest required scope set, store their values in a secret manager, and send them as `Authorization: Bearer `. A missing or invalid key returns `401`. A valid key without the required scope returns `403`. Account settings, key management, account deletion, and billing require a signed-in browser session instead of API keys. Consult the [API reference](https://docs.wildmail.app/docs/api/reference.md). API access is scoped to the individual account that owns the key. Account authorization also governs message content, raw email, attachments, and delivery records. Do not put credentials in URLs, client-side JavaScript, logs, or shared examples. Webhook secrets are shown at creation or rotation. Deploy a new secret to your receiver when rotating. Each accepted message keeps its signing-key version for retries and replay. New messages use the newly rotated secret. ## Treat message content as untrusted Validate webhook signatures against raw bytes before parsing. Inspect `message.authentication` in standard events for SPF, DKIM, DMARC, and ARC results, and distinguish permanent failures from temporary verification errors. Authentication results are signals for your policy. They do not make attachments safe. Spam results in `message.spam` describe the email scan, not a malware verdict for each attachment. A false `message.is_spam` value does not prove the message is clean. Check the scan status and apply your own review policy. Validate types, limit downloads, and use suitable malware scanning or manual review for your workflow. Sender-supplied filenames and MIME types are untrusted. Never render HTML email directly into an unrestricted application page. Raw message and attachment downloads use authenticated Wildmail message routes. They require an account API key with `messages:read` or a signed-in dashboard session. The URL alone does not authorize access. Access follows the current account retention policy and requires an active credential. Keep URLs and keys out of public logs and tickets. ## Account protection Email code is the default email sign-in option. Password sign-in remains available. Codes contain six digits, expire after five minutes, allow three verification attempts, and work once. Resending replaces the previous code. Settings supports TOTP authenticators, WebAuthn security keys, and single-use recovery codes. Both email-code and password sign-in require the enabled second factor. An email sign-in code is not a second factor. Google and GitHub sign-in use the provider’s security and do not use Wildmail’s second-factor challenge for email and password sign-ins. Linking a provider leaves protection on your email sign-ins intact. Sign in with email to enroll or manage your authentication factors. Enrollment does not require password confirmation: confirm an initial authenticator code or complete browser security-key registration. Removing protection or replacing recovery codes requires your current password if you have one. Otherwise, request a fresh email code for that specific action. Save recovery codes when shown. Replacing them invalidates the previous set. You cannot remove your last security key unless a verified authenticator remains. If you first use an email code for an existing account whose email was unverified, its previous password and linked providers are removed and its existing sessions are signed out. Your Wildmail account and enrolled authentication factors remain. Use password recovery to add a password again and relink providers afterward. Password reset links expire after one hour and are single-use. Resetting a password revokes account sessions and preserves second-factor settings. Password changes using the current password sign out other sessions. Webhook endpoints must use publicly reachable HTTPS on port 443. Private-network and loopback destinations are not supported. Configure the final HTTPS URL, because Wildmail does not follow redirects. # Troubleshooting intake and delivery Use the receipt ID to find a stored message, the event ID to correlate webhook retries, and the attempt ID to investigate one HTTP request. ```mermaid flowchart TD A{Receiving address ready?} -->|No| DNS[Check TXT, MX, endpoint, plan and billing] A -->|Yes| B{SMTP accepted?} B -->|No| SMTP[Inspect SMTP response, recipient, size and quota] B -->|Yes| C[Message is stored] C --> D{Webhook attempted?} D -->|No| PENDING[Inspect delivery status and next retry time] D -->|Yes| ATT[Inspect attempt ID and receiver response] ``` Wildmail parses and stores the email before SMTP acceptance, then prepares webhook delivery. A successful SMTP response confirms storage, not successful webhook delivery. | Symptom | Check | Next action | | --- | --- | --- | | Domain is not ready | TXT ownership, MX destination, endpoint, plan and billing | Correct DNS or configuration and run **Check DNS** again. Exact-address routes can work without a catch-all, see [routing behavior](https://docs.wildmail.app/docs/guides/domains.md#routing-behavior). | | SMTP `550` at recipient admission | Unknown address, unready domain, inactive or suspended route | Confirm the exact receiving address and domain status. | | SMTP `451` at admission | Monthly allowance, storage quota, rate limits, temporary service availability | Check account usage. Allow normal sender retries. Contact support if failures persist. | | SMTP `552` for message size | Entire raw email size, including headers and encoded attachments | Reduce the message size to fit your plan. Retrying the unchanged email will not resolve it. | | SMTP succeeds but no webhook arrives | Delivery status, next retry time, attempts and current endpoint status | Inspect **Deliveries**. Allow the bounded retry window to run. Contact support with the receipt ID and event ID if it remains pending. | | Webhook signature fails | Raw body capture, signing-key version, header names and clock skew | Follow the [verification example](https://docs.wildmail.app/docs/guides/webhooks.md). Verify before parsing or reserializing the JSON. | | HTTP `401` or `403` in delivery attempts | Your receiver's authentication or verification policy | Fix receiver credentials or signature verification, then replay while the message remains available. | | HTTP `429` or `5xx` | Receiver capacity or outage | Restore receiver capacity. Positive-retention mail retries within the bounded window. A 0-day message gets at most one attempt. | | Redirect response | Endpoint URL redirects to a different host or path | Configure the final HTTPS URL. Wildmail does not follow redirects. | | Raw message or attachment unavailable | Current account retention, message expiry and API-key scope | Retrieve retained content before expiry. At 0 days, attachment bytes are available inline in the webhook event only. | | Replay returns `409` | Attempt in progress, endpoint paused, signing key unavailable or mapping invalid | Follow the returned error. Wait for an active attempt or correct the endpoint or mapping. A failed render cannot be repaired by replaying the same pinned mapping. | | Replay returns `410` | Content expired or the message uses 0-day retention | Use content already stored by your application. Expired and 0-day messages cannot be replayed. | ## Intake failures Malformed email, size limits, recipient routing, or temporary service failures can cause SMTP to reject a message. The sending mail server should retry temporary `4xx` responses. A rejected message has no webhook delivery to replay. ## Delivery failures Wildmail sends the signed event using the endpoint and payload mapping selected when the email was accepted. An expired message, unavailable endpoint revision, or invalid mapping can stop delivery. The delivery detail page shows content-free attempt results and the latest safe error code. Contact Wildmail support with the receipt ID and event ID if a message stays pending beyond its delivery window. **Send test** checks endpoint connectivity and signature verification with a synthetic event. Send a real email to your receiving address to verify SMTP intake, email parsing, message access, and attachment handling. # Usage, size limits, and retention The dashboard and `GET /api/usage` show your account's plan, monthly accepted-message allowance, domain and exact-address route limits, storage usage and quota, and current retention. API keys require `usage:read`. Your exact plan limits and billing availability are shown in the account. ## Plans and included limits | | Free | Starter | Growth | | --- | ---: | ---: | ---: | | Monthly price | €0 | €20 | €49 | | Custom domains | 1 | 3 | 10 | | Accepted messages per UTC month | 10,000 | 30,000 | 100,000 | | Maximum complete raw email | 5 MiB | 25 MiB | 25 MiB | | Retained storage capacity | 5 GB | 50 GB | 150 GB | | Maximum content retention | 7 days | 30 days | 60 days | | Exact-address routes | Not included | Unlimited | Unlimited | Paid prices are per month, before applicable tax. All three plans include a hosted test address separate from the custom-domain allowance, domain catch-all routing, signed webhooks, and delivery history. Automatic retry and manual replay require positive retention and available content. Every plan lets you choose 0 days or any whole number up to its maximum retention. A new account starts at its plan maximum. One MiB is 1,048,576 bytes. One GB is 1,000,000,000 bytes. Storage is a capacity limit on content retained at one time. ## Message and storage limits An accepted inbound message counts once for your account, even when several addresses in that account receive it. A separately accepted SMTP retransmission counts as a new message. Delivery attempts, replay, and synthetic webhook tests do not count as accepted inbound mail. Allowances reset at 00:00 UTC on the first day of each month. Unused messages do not roll over, and Wildmail does not charge automatic message overages. The maximum message size includes the complete raw email: headers, body parts, MIME boundaries, encoded attachments, and line endings. The dashboard shows the current per-message limit. An oversized message is rejected, so the sender must reduce its size. Exhausting monthly message or storage capacity temporarily refuses new mail. The sender can retry after capacity becomes available. The Usage page reports used and remaining storage capacity. Retained content uses that capacity until expiry and cleanup complete. The dashboard displays the current domain and exact-address route limits for your plan. ## Choose account retention Open **Settings** to choose 0 days or a whole number of days up to your plan maximum. The initial setting uses the plan maximum. Updating retention applies to messages already stored in your account and to future inbound mail. Wildmail also checks the current policy before showing message content, downloading raw mail or attachments, retrying delivery, or replaying an event. With positive retention, message content and attachments remain available until their expiry under the current setting. Retry and replay stop when the content is no longer available. Extending retention can keep existing content available longer if it has not already been deleted. It cannot restore deleted content. With **0 days**, Wildmail allows at most one webhook attempt and includes attachment bytes inline as base64. Automatic retry and replay are disabled. Content is kept only for delivery and has a 24-hour safety deadline if the message never reaches an attempt. When changing retention to 0 days, completed or previously attempted messages are purged. Eligible messages that have not been attempted can receive at most one attempt before cleanup. The event outcome and content-free delivery history remain after message content is removed. ## Message downloads The dashboard opens in **Threads** view. Switch to **Individual messages** to inspect each receipt or its expired delivery history. Search and delivery-status filters carry across views, and switching resets pagination. Threads show retained messages only, oldest first on the thread page, with links to each message's preview, attachments, downloads, and delivery history. Counts shrink as members expire. Accounts using 0-day retention have no browsable threads. The API provides the same retained view through `GET /api/threads` and `GET /api/threads/{id}` with `messages:read`. Use `GET /api/messages` and `GET /api/messages/{id}` to find and inspect retained mail. A message detail response can include a raw-message link and parsed message fields while content is available. Attachment descriptors contain stable Wildmail URLs in normal retention mode. Download an attachment from `GET /api/messages/{id}/attachments/{attachmentId}` with an account API key that has `messages:read`, or through the signed-in dashboard. Download access is checked against the current retention setting. At 0 days, use attachment bytes from the webhook event. There is no later attachment download or replay after content has been purged. ## Usage data `GET /api/usage` reports the current plan and usage as account data: - `messages` reports accepted and reserved messages for the current UTC month. - `domains` and `addressRoutes` report their current use and plan limits. - `storage` reports retained storage usage, quota, and remaining capacity. - `retention` reports effective `retentionDays`, the plan maximum `maxDays`, and saved `configuredDays`. - `period.resetsAt` is the next UTC monthly reset. Billing changes are available through **Billing** in the account dashboard. Subscription status and plan limits shown in the dashboard are authoritative. Content access expiry and physical deletion are separate. Wildmail records content-free delivery history after expiry. Expired messages and attachments are removed through the service’s cleanup process, which releases storage capacity. Cleanup may take time, and backup copies have separate expiry policies. # Verify and consume webhooks Wildmail sends HTTP `POST` requests with `Content-Type: application/json`. Verify the signature against the original request bytes before parsing JSON. Parsing and reserializing can change whitespace, escaping, or field order. ## Signing contract Webhook requests use these headers: | Header | Value | | -------------------- | ---------------------------------------------------------------- | | `wildmail-timestamp` | Unix seconds for this HTTP attempt. | | `wildmail-event-id` | Stable logical event ID shared by retries and replay. | | `wildmail-attempt-id` | Unique ID for this HTTP attempt. | | `wildmail-key-id` | Signing-key version ID for the endpoint. | | `wildmail-signature` | `v1=` followed by a 64-character hexadecimal HMAC-SHA256 digest. | Compute the digest using the endpoint signing secret as the key and this exact input: ```text .. ``` Compare digests in constant time and reject timestamps outside a short tolerance, such as five minutes. Keep receiver clocks synchronized. Automatic retries receive new timestamps, attempt IDs, and signatures. They keep the event ID and pinned endpoint and shaping revision. Retries preserve the request body. ```mermaid flowchart TD A[Receive request] --> B[Capture exact raw bytes] B --> C[Check timestamp and HMAC] C -->|Invalid| X[Reject request] C -->|Valid| D[Parse JSON] D --> E[Deduplicate event_id and commit] E -->|Duplicate already applied| OK[Return 2xx without repeating effects] E -->|Commit succeeds| OK2[Return 2xx] E -->|Temporary commit failure| R[Return failure so retained mail can retry] ``` Verify before parsing, then persist the event ID with your business change. A duplicate event should be acknowledged without repeating its side effect. Return success only after a durable commit or enqueue. ## Standard and shaped payloads The standard event uses the `wildmail.v1` schema and nests the parsed email under `message`. Receiver-added headers remain available, including delivery and authentication headers. `envelope.recipients` contains the Wildmail addresses matched for this endpoint. Original `to`, `cc`, and `bcc` fields are message content supplied by the sender and can differ from that envelope. ```json { "schema_version": "wildmail.v1", "event_type": "email.received", "event_id": "evt_example", "received_at": "2026-11-02T12:00:00.000Z", "envelope": { "sender": "vendor@example.com", "recipients": ["orders@example.net"] }, "message": { "message_id": "", "thread_id": "507f1f77bcf86cd799439011", "date": "2026-11-02T11:59:59.000Z", "from": { "name": "Vendor", "address": "vendor@example.com" }, "reply_to": [], "to": [{ "name": "Orders", "address": "orders@example.net" }], "cc": [], "bcc": [], "subject": "Purchase order", "headers": [ { "name": "Delivered-To", "value": "orders@example.net" }, { "name": "Authentication-Results", "value": "mx.example.net; dkim=pass" } ], "text": "Please see the attached order.", "html": ["

Please see the attached order.

"], "content_type": { "value": "multipart/mixed", "params": {} }, "attachments": [], "authentication": { "dkim": { "result": "pass" } }, "is_spam": false, "spam": { "engine": "rspamd", "status": "scanned", "score": 0.1, "action": "no action", "required_score": 6.0, "symbols": [] } } } ``` `message.subject` and some address fields can be null or empty. Message headers, HTML, MIME types, filenames, and attachment bytes are untrusted input. Authentication results are signals for your application, not proof that attachments are safe. `message.thread_id` is the conversation ID, identical to `threadId` in the message and thread APIs. It is `null` when thread metadata is unavailable. Thread matching uses message references and normalized subjects, so unrelated messages sharing a subject stay separate and changing the subject can create a new thread. Select `/message/thread_id` in payload shaping to include or rename it. Older events can omit the field. Automatic retries and replay reproduce the original body exactly, including omission of `thread_id` and any earlier schema name. When scan data is available, `message.is_spam` is a quick boolean verdict and is true only when Rspamd completed a scan and marked the message as spam. False means there is no positive spam verdict; it does not prove the message is clean. Check `message.spam.status` to distinguish a completed scan (`scanned`) from a skipped scan (`skipped`) or scanner error (`error`). `message.spam` is null when scan details are unavailable. When present, it contains `engine`, `status`, numeric or null `score`, string or null `action`, numeric or null `required_score`, and `symbols` entries with `name` and numeric `score`. These fields are selectable in payload shaping. Older events may omit both `is_spam` and `spam`. Receivers should handle missing scan data. If you configure **Payload shaping**, Wildmail sends the selected fields and structure instead of the standard JSON body. A mapping can omit or rename `event_id`, message content, or attachment fields. The `wildmail-event-id` signature header remains the stable deduplication identity. ## Attachments and retention With positive retention, attachment descriptors include an ID, filename, content type, disposition, content ID, byte count, SHA-256 digest, and a Wildmail download URL. Download with an account API key that has `messages:read`: ```json { "id": "att_example", "filename": "purchase-order.pdf", "content_type": "application/pdf", "disposition": "attachment", "content_id": null, "byte_count": 12000, "sha256": "<64-character hexadecimal digest>", "download_url": "https://wildmail.app/api/messages//attachments/att_example" } ``` Use the `download_url` with `Authorization: Bearer `. The URL is not a bearer credential by itself. Wildmail checks current account retention before and after opening a download. Verify the returned byte count and SHA-256 digest. Treat sender filenames as untrusted input and do not use them directly as filesystem paths. With 0-day retention, each attachment has `content_base64` containing the base64 encoding of its bytes and has no download URL. Decode the value before using the bytes. `byte_count` and `sha256` describe the decoded content. Wildmail permits at most one delivery attempt and does not retry or replay the event. A message that has not reached an attempt has a 24-hour safety deadline. Changing retention applies to existing and future messages. Reducing retention can make existing content unavailable immediately. Extending it can keep eligible existing content available longer. Delivery retry, replay, message detail, raw downloads, and attachment downloads all follow the current policy. ## Test events The dashboard test action sends a synthetic event with `event_type: "email.test"` and a synthetic message. It does not count toward inbound message usage. It checks signing and endpoint connectivity, but does not contain customer email or attachments. Handle `email.test` separately from `email.received`. ## Runnable TypeScript receiver Save this as `receiver.ts`, set `WILDMAIL_WEBHOOK_SECRET` to the endpoint secret, and run it with Node.js 24. The example listens on loopback for local receiver development. To receive Wildmail deliveries, expose the receiver through a public HTTPS endpoint and configure that URL in your account. This sample caps its own request body at 32 MiB. Set the receiver's limit to fit your workload and infrastructure. ```ts import { createHmac, timingSafeEqual } from "node:crypto"; import { createServer, type IncomingMessage } from "node:http"; const secret = process.env.WILDMAIL_WEBHOOK_SECRET; if (!secret) throw new Error("Set WILDMAIL_WEBHOOK_SECRET"); const signingSecret: string = secret; const maxBodyBytes = 32 * 1_048_576; function header(req: IncomingMessage, name: string): string { const value = req.headers[name]; return typeof value === "string" ? value : ""; } function verify(req: IncomingMessage, raw: Buffer): string | null { const timestamp = header(req, "wildmail-timestamp"); const eventId = header(req, "wildmail-event-id"); const signature = header(req, "wildmail-signature"); if (!/^\d+$/.test(timestamp) || !eventId) return null; if (!Number.isSafeInteger(Number(timestamp))) return null; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return null; if (!/^v1=[a-f0-9]{64}$/.test(signature)) return null; const expected = createHmac("sha256", signingSecret) .update(`${timestamp}.${eventId}.`) .update(raw) .digest(); const received = Buffer.from(signature.slice(3), "hex"); return timingSafeEqual(expected, received) ? eventId : null; } // Demonstration only. Persist event IDs with business changes in production. const seen = new Set(); createServer(async (req, res) => { if (req.method !== "POST" || req.url !== "/webhook") { res.writeHead(404).end(); return; } try { const chunks: Buffer[] = []; let bytes = 0; for await (const chunk of req) { const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk); bytes += buffer.length; if (bytes > maxBodyBytes) { res.writeHead(413).end(); return; } chunks.push(buffer); } const raw = Buffer.concat(chunks); const eventId = verify(req, raw); if (!eventId) { res.writeHead(401).end(); return; } const event = JSON.parse(raw.toString("utf8")); if (!event || typeof event !== "object" || Array.isArray(event)) { res.writeHead(400).end(); return; } if (!seen.has(eventId)) { console.log({ eventId, type: event.event_type }); seen.add(eventId); } res.writeHead(204).end(); } catch (error) { res.writeHead(error instanceof SyntaxError ? 400 : 500).end(); } }).listen(8787, "127.0.0.1", () => console.log("Receiver on port 8787")); ``` For production, replace the in-memory set with durable deduplication. In one transaction, insert `event_id` with a unique constraint and apply your application changes. If the ID already exists, acknowledge it without repeating effects. Another option is to commit the unique event ID and a durable work item together, then process it asynchronously. Respond with 2xx only after committing durable state. Return a retryable status if a temporary database or queue failure prevents that commit. Positive-retention events can retry while content remains available. Zero-day events cannot retry. A network failure can leave your receiver unsure whether the event was committed, so always make repeated event IDs safe. # Wildmail documentation Wildmail gives each customer an individual account with a hosted test address. Connect a webhook and receive a signed event before changing DNS, then verify a customer-owned domain to receive mail there. The dashboard provides message search, delivery history, raw message downloads, and replay while the account's current retention policy permits access. ```mermaid sequenceDiagram participant Sender participant Wildmail participant App as Your application Sender->>Wildmail: Submit email over SMTP Wildmail->>Wildmail: Parse and store the email Wildmail-->>Sender: Accept after durable storage Wildmail->>App: Signed webhook (may retry) App-->>Wildmail: 2xx acknowledgement ``` SMTP acceptance confirms durable message storage. It does not mean webhook delivery succeeded. Wildmail prepares delivery from the stored message after acceptance. Retained-message deliveries can retry within their delivery window. With 0-day retention, Wildmail allows at most one webhook attempt and does not allow automatic retry or replay. See [usage and retention](https://docs.wildmail.app/docs/guides/usage-and-retention.md) for the current retention behavior. Start with the [quickstart](https://docs.wildmail.app/docs/guides/quickstart.md), then implement [signature verification](https://docs.wildmail.app/docs/guides/webhooks.md). Read [delivery and replay](https://docs.wildmail.app/docs/guides/delivery-and-replay.md) before performing business actions from events. The [API reference](https://docs.wildmail.app/docs/api/reference.md) describes the customer HTTP routes, permissions, and request examples. For document intake, receive mail at an address such as `invoices@intake.example.com`, verify the signature, and store the stable event ID with your application's database change. With positive retention, fetch attachments before content expires. With 0-day retention, use the attachment bytes included in the webhook. Sender authentication results are useful signals for your application's review policy. Standard events contain parsed message data, authentication results, attachment metadata, and the envelope addresses matched by Wildmail. Optional [payload shaping](https://docs.wildmail.app/docs/api/reference.md#payload-shaping) can select, rename, and nest these fields for an endpoint. It does not extract new data or validate customer-defined schemas. Integrations should use the [documented event format](https://docs.wildmail.app/docs/guides/webhooks.md) and perform any application-specific extraction or validation in their own receiver. # Terms and Conditions These Terms govern access to and use of the hosted Wildmail service, including its dashboard, APIs, hosted email addresses, message processing, storage, and webhook delivery (the “Service”). By creating an account or using the Service, you agree to these Terms. If you use the Service for an organization, you confirm that you may accept these Terms for that organization. References to “you” include that organization. ## The Service Wildmail receives email for configured addresses, stores messages in your account, and delivers signed events and related content under the account's current retention policy and plan limits. Features, quotas, and retention limits depend on the plan shown in your account and the [usage and retention policy](https://docs.wildmail.app/docs/guides/usage-and-retention.md). The API documentation describes the current API behavior. The Service is provided online. Unless a separate written agreement says otherwise, no uptime, delivery-time, or support response-time commitment applies. We may update or change features, and will use reasonable efforts to give notice when a material change affects an active paid subscription. ## Your account and responsibilities You are responsible for activity under your account, protecting account credentials and API keys, and keeping account information current. Notify us promptly if you believe an account or credential has been compromised. You are responsible for actions taken by people you authorize to use your account. You must use the Service lawfully and in accordance with these Terms. You must not use it to send or facilitate unsolicited or unlawful email, distribute malware, probe or compromise systems, bypass limits or access controls, interfere with the Service, or process content you have no right to submit. You must not use the Service as an open relay or attempt to evade abuse controls. You are responsible for your email domains, sender and recipient notices, webhook destinations, and the security and lawful use of systems that receive delivered events. Configure your endpoints to authenticate signed deliveries and treat message bodies and attachments as untrusted input. The [security guide](https://docs.wildmail.app/docs/guides/security.md) describes recommended integration safeguards. ## Your content and our permission to process it You retain your rights in email, attachments, configuration, and other content submitted to the Service (“Customer Content”). You give Wildmail permission to host, copy, process, transmit, and display Customer Content only as reasonably necessary to provide, secure, and support the Service and to comply with law. This includes receiving and parsing messages, storing them during the applicable retention period, and delivering events and content to destinations you configure. You confirm that you have the rights and permissions needed for Customer Content and for the processing and delivery instructions you configure. You are responsible for determining whether your use of the Service meets your legal obligations to senders, recipients, employees, and other affected people. Every plan includes account retention controls at no extra charge. You may select 0 days or any whole number from 1 to your plan's maximum. The default uses that maximum. Changing the setting applies to existing messages and future inbound mail. At 0 days, Wildmail allows at most one self-contained webhook attempt, without retry or replay. A message that never reaches an attempt has a 24-hour safety deadline. Delivery outcomes remain in content-free history after message content is purged. At positive retention, content access follows the current retention setting. Content access expiry does not promise immediate physical erasure or expiry of backup copies. See the [usage and retention policy](https://docs.wildmail.app/docs/guides/usage-and-retention.md) for details. ## Privacy and data processing Wildmail runs its application, databases, and mail processing on infrastructure it manages in the European Union. Attachment files are stored in Backblaze B2’s S3-compatible EU Central region in Amsterdam, the Netherlands. Wildmail delivers events and content to the destinations you configure. You are responsible for copies received or downloaded into your own systems. The [Privacy Policy](https://wildmail.app/privacy) explains how Wildmail handles personal data. Where you engage Wildmail as a processor and Article 28 of the GDPR applies, you must have an applicable data processing agreement in place. ## Plans, payment, and cancellation Available plans, prices, billing intervals, taxes, and included usage are shown in the Service and at checkout. You authorize the displayed payment method to be charged for the plan you select. Paid subscriptions renew at the interval shown at checkout until cancelled. Stripe acts as merchant of record through Stripe Managed Payments and handles payment, applicable sales taxes, and transaction support under the terms shown at checkout. You can manage or cancel a paid subscription through the billing controls available in your account. Cancellation through the billing controls takes effect at the end of the current billing period, subject to the terms shown at checkout and applicable law. Plan changes can affect future intake, limits, and enabled custom domains. Existing accepted content remains subject to your account’s current retention policy. Unused quotas do not roll over, and the Service does not apply automatic message overage charges. Any mandatory consumer rights, including withdrawal and refund rights where applicable, continue to apply. ## Suspension and termination You may stop using the Service and delete your account in **Settings**. Account deletion disables sign-in and inbound mail, requests immediate cancellation of an active subscription recorded on the account, schedules mailbox removal, and removes account records. Wildmail issues no automatic refund for unused paid time or previous payments. Any refund due under applicable law or the checkout terms still applies. If the deletion screen reports a cleanup error, retry from that screen or contact Wildmail. We may suspend or restrict access when reasonably necessary to address a security risk, suspected unlawful or abusive use, non-payment, material breach of these Terms, or a legal requirement. Where practical, we will give notice and an opportunity to resolve the issue before suspension. You remain responsible for charges incurred through the effective cancellation date, subject to applicable law. Export any content or invoices you need before deleting your account or losing access. For details on background cleanup and records that may be retained, see the [Privacy Policy](https://wildmail.app/privacy). ## Intellectual property Wildmail and its licensors retain rights in the Service, including its software, design, and documentation. These Terms give you a limited, non-exclusive right to use the Service during your subscription or other authorized access, subject to these Terms. You may not copy, resell, or make the Service available to others as a service, or reverse engineer it except where applicable law permits. If you send suggestions about the Service, you allow Wildmail to use them without restriction or payment, provided this does not transfer ownership of your Customer Content. ## Service changes and disclaimers We work to keep the Service useful and reliable, but the Service may be unavailable or delayed because of maintenance, failures, network conditions, or events outside our reasonable control. Email and webhook delivery can be delayed, rejected, or fail. You are responsible for monitoring delivery status and maintaining any application safeguards your workflow requires. To the extent permitted by applicable law, the Service is provided as available, without warranties beyond those that cannot legally be excluded. Nothing in these Terms removes a warranty or right that applicable law makes mandatory. ## Liability Nothing in these Terms excludes or limits liability, or any remedy, that cannot legally be excluded or limited. Subject to that rule, Wildmail is not responsible for indirect or consequential loss, loss of profits, revenue, goodwill, or data, or interruption of your business arising from use of the Service. This section does not limit your obligation to pay charges due for the Service. ## Changes to these Terms We may revise these Terms to reflect changes to the Service or legal requirements. We will update the date and give reasonable notice of material changes through the Service or another appropriate channel. Changes apply from the date stated in the notice. If you do not agree to a material change, stop using the Service and cancel any paid subscription before the change takes effect. Continued use after that date means you accept the revised Terms, subject to rights that applicable law does not allow us to waive. ## Contact For questions about these Terms, email [hello@wildmail.app](mailto:hello@wildmail.app). For payment disputes or transaction support, use the contact details in your Stripe receipt. **Last updated: 17 November 2026** # Wildmail documentation # Wildmail documentation Wildmail receives email and attachments, keeps the source durably, and delivers parsed JSON to your endpoint. Build document intake workflows with signed events, delivery history and replay, and your own receiving domain. ## Get started [Receive your first email](https://docs.wildmail.app/docs/guides/quickstart.md) with a hosted test address before changing DNS. [Introduction](https://docs.wildmail.app/docs.md) describes the available features and current scope. ## Capabilities - Connect your hosted test address to an endpoint to receive real email. - Verify HMAC signatures against the exact request bytes and deduplicate by stable event ID. - Download retained attachments through authenticated links with byte counts and SHA-256 hashes. Access follows your current retention setting. - Inspect original email and delivery attempts, then replay retained events after correcting a destination. - Manage domains and endpoints, search messages, and replay deliveries with scoped API credentials. - Accepted email is stored durably so processing can recover from temporary interruptions. ## Find your next step - [Receiving domains](https://docs.wildmail.app/docs/guides/domains.md): verify a domain and configure DNS. - [API overview](https://docs.wildmail.app/docs/api/reference.md): methods, authentication, examples and failures. - [Verify webhooks](https://docs.wildmail.app/docs/guides/webhooks.md): runnable Node.js signature verification. - [Delivery and replay](https://docs.wildmail.app/docs/guides/delivery-and-replay.md): handle retries and replay retained events. - [Plans, usage, and retention](https://docs.wildmail.app/docs/guides/usage-and-retention.md): compare prices, limits, and content availability. - [Troubleshooting](https://docs.wildmail.app/docs/guides/troubleshooting.md): diagnose receiving and delivery problems. Open your Wildmail application to connect an endpoint and send your first email. # Account Read account status and manage message retention or account deletion. [Download the OpenAPI specification](/openapi.json). ## Operations - [Get account settings](/docs/api/generated/get-api-account.md) - [Delete account](/docs/api/generated/post-api-account-delete.md) - [Update account retention](/docs/api/generated/put-api-account.md) # API keys Manage scoped credentials for one individual Wildmail account. [Download the OpenAPI specification](/openapi.json). ## Operations - [Revoke API key](/docs/api/generated/delete-api-keys-id.md) - [List API keys and scopes](/docs/api/generated/get-api-keys.md) - [Create scoped API key](/docs/api/generated/post-api-keys.md) # Authentication Account sign-in and security through the hosted application. [Download the OpenAPI specification](/openapi.json). ## Operations - [Browser authentication action](/docs/api/generated/get-api-auth-path.md) - [Browser authentication action](/docs/api/generated/post-api-auth-path.md) # Billing Manage billing for one individual Wildmail account. [Download the OpenAPI specification](/openapi.json). ## Operations - [Get billing summary](/docs/api/generated/get-api-billing.md) - [Create checkout session](/docs/api/generated/post-api-billing-checkout.md) - [Create billing portal session](/docs/api/generated/post-api-billing-portal.md) - [Refresh billing state](/docs/api/generated/post-api-billing-sync.md) - [Upgrade Starter to Growth](/docs/api/generated/post-api-billing-upgrade.md) # Delete an exact-address route `DELETE /api/domains/{id}/routes/{routeId}` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:write`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ``` ### routeId path parameter; required. ```json { "name": "routeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ``` ## Responses ### 204 Deleted. Empty body. ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Domain or route not found in this account. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Delete custom domain `DELETE /api/domains/{id}` Signed-in browser session or a scoped API key. Removes a custom domain and refreshes admission routing. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:admin`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 204 Deleted. Empty body. ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Domain not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Revoke API key `DELETE /api/keys/{id}` Browser session only, signed-in account owner. Revokes an active key immediately. An already revoked or missing key returns 404. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Audience: session. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 204 Deleted. Empty body ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Active API key not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Delete webhook endpoint `DELETE /api/webhooks/{id}` Signed-in browser session or scoped API key. Refreshes affected domain routing. Related delivery history is removed with the endpoint. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `webhooks:admin`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 204 Deleted. Empty body ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Endpoint not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Deliveries Inspect delivery attempts and replay eligible retained messages. [Download the OpenAPI specification](/openapi.json). ## Operations - [Inspect delivery and attempts](/docs/api/generated/get-api-deliveries-id.md) - [List deliveries](/docs/api/generated/get-api-deliveries.md) - [Replay delivery](/docs/api/generated/post-api-deliveries-id-replay.md) # Domains Verify custom domains and assign their receiving destinations. [Download the OpenAPI specification](/openapi.json). ## Operations - [Delete an exact-address route](/docs/api/generated/delete-api-domains-id-routes-route-id.md) - [Delete custom domain](/docs/api/generated/delete-api-domains-id.md) - [List exact-address routes for a custom domain](/docs/api/generated/get-api-domains-id-routes.md) - [List custom domains](/docs/api/generated/get-api-domains.md) - [Create an exact-address route](/docs/api/generated/post-api-domains-id-routes.md) - [Check domain DNS](/docs/api/generated/post-api-domains-id-verify.md) - [Create a custom domain](/docs/api/generated/post-api-domains.md) - [Update an exact-address route](/docs/api/generated/put-api-domains-id-routes-route-id.md) - [Set domain destination](/docs/api/generated/put-api-domains-id.md) # Get account settings `GET /api/account` Returns the signed-in user's Wildmail account, current plan and configured message retention. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. ## Responses ### 200 Account settings. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "account": { "type": "object", "additionalProperties": true, "properties": { "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended", "disabled" ] }, "plan": { "$ref": "#/components/schemas/AccountPlan" }, "billing": { "$ref": "#/components/schemas/AccountBilling" }, "retentionDays": { "type": "integer", "minimum": 0 } } } }, "required": [ "account" ] } ``` ### 401 A signed-in session is required. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Account not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/AccountPlan ```json { "type": "object", "properties": { "id": { "type": "string" }, "maxMessageBytes": { "type": "integer" }, "monthlyMessageLimit": { "type": "integer" }, "storageLimitBytes": { "type": "integer" }, "customDomainLimit": { "type": [ "integer", "null" ] }, "retentionLimitDays": { "type": "integer" } }, "required": [ "id", "maxMessageBytes", "monthlyMessageLimit", "storageLimitBytes", "customDomainLimit", "retentionLimitDays" ] } ``` ### #/components/schemas/AccountBilling ```json { "type": "object", "properties": { "status": { "type": "string" }, "paidThrough": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "status", "paidThrough", "cancelAtPeriodEnd" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Browser authentication action `GET /api/auth/{path}` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication No authentication scheme is required by this operation. Audience: auth. ## Parameters ### path path parameter; required. ```json { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 200 Library-defined response: JSON, redirect or session-cookie update according to the selected auth endpoint. Schema intentionally unspecified. ### 400 Authentication validation error. ### 401 Authentication required. ### 403 Origin or authorization denied. ### 429 Authentication rate limit. Shared request limiting can also return 429 rate_limit_exceeded with Retry-After (seconds) and Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying a throttled authentication request.", "schema": { "type": "integer", "minimum": 1 } } } ``` Content type: `application/json`. Schema: ```json { "anyOf": [ { "$ref": "#/components/schemas/RequestLimitError" }, { "type": "object", "description": "Authentication error returned by the selected sign-in action." } ] } ``` ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/RequestLimitError ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "rate_limit_exceeded", "rate_limit_unavailable" ] } }, "required": [ "error", "code" ] } ``` # Get billing summary `GET /api/billing` Browser session only, signed-in account. configured reports whether billing is available. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Audience: session. ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "billing": { "$ref": "#/components/schemas/Billing" }, "configured": { "type": "boolean" } }, "required": [ "billing", "configured" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 account missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 Billing unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } } } ``` Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Billing ```json { "type": "object", "properties": { "plan": { "type": "string" }, "status": { "type": "string" }, "hasCustomer": { "type": "boolean" }, "hasSubscription": { "type": "boolean" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "graceUntil": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "lastSyncedAt": { "type": [ "string", "null" ], "format": "date-time" }, "suspendedDomains": { "type": "array", "items": { "type": "string" } } }, "required": [ "plan", "status", "hasCustomer", "hasSubscription", "currentPeriodEnd", "graceUntil", "cancelAtPeriodEnd", "lastSyncedAt", "suspendedDomains" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Inspect delivery and attempts `GET /api/deliveries/{id}` Returns the delivery summary, message availability, and content-free attempt history. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `deliveries:read`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "message": { "type": [ "object", "null" ], "properties": { "receiptId": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "receivedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "contentAvailable": { "type": "boolean" } }, "required": [ "receiptId", "receivedAt", "expiresAt", "contentAvailable" ] }, "contentAvailable": { "type": "boolean" } }, "required": [ "delivery", "message", "contentAvailable" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Delivery not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Delivery ```json { "type": "object", "properties": { "id": { "type": "string" }, "deliveryId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string", "const": "email.received" }, "endpointId": { "type": "string" }, "endpointName": { "type": "string" }, "endpointStatus": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "retrying", "delivered", "failed" ] }, "inProgress": { "type": "boolean" }, "responseCode": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "attemptCount": { "type": "integer" }, "nextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryDeadlineAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "null" }, "payloadBody": { "type": "null" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttempt" } } }, "required": [ "id", "deliveryId", "eventId", "eventType", "endpointId", "endpointName", "endpointStatus", "status", "inProgress", "responseCode", "durationMs", "attemptCount", "nextRetryAt", "deliveryDeadlineAt", "lastError", "createdAt", "payload", "payloadBody", "attempts" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/MessageAttempt ```json { "type": "object", "properties": { "id": { "type": "string" }, "deliveryId": { "type": "string" }, "status": { "type": "string" }, "responseCode": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "deliveryId", "status", "responseCode", "durationMs", "error", "createdAt", "completedAt" ] } ``` # List deliveries `GET /api/deliveries` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `deliveries:read`. Audience: management. ## Parameters ### page query parameter; optional. Pages are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page. ```json { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Pages are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page." } ``` ### status query parameter; optional. ```json { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "retrying", "delivered", "failed" ] } } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/DeliverySummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "deliveries", "pagination" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/DeliverySummary ```json { "allOf": [ { "$ref": "#/components/schemas/Delivery" }, { "type": "object", "properties": { "receiptId": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "recipients": { "type": "array", "items": { "type": "string" } }, "receivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "contentAvailable": { "type": "boolean" } }, "required": [ "receiptId", "recipients", "receivedAt", "contentAvailable" ] } ] } ``` ### #/components/schemas/Pagination ```json { "type": "object", "properties": { "page": { "type": "integer" }, "pageCount": { "type": "integer" }, "total": { "type": "integer" }, "pageSize": { "type": "integer" } }, "required": [ "page", "pageCount", "total" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/Delivery ```json { "type": "object", "properties": { "id": { "type": "string" }, "deliveryId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string", "const": "email.received" }, "endpointId": { "type": "string" }, "endpointName": { "type": "string" }, "endpointStatus": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "retrying", "delivered", "failed" ] }, "inProgress": { "type": "boolean" }, "responseCode": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "attemptCount": { "type": "integer" }, "nextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryDeadlineAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "null" }, "payloadBody": { "type": "null" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttempt" } } }, "required": [ "id", "deliveryId", "eventId", "eventType", "endpointId", "endpointName", "endpointStatus", "status", "inProgress", "responseCode", "durationMs", "attemptCount", "nextRetryAt", "deliveryDeadlineAt", "lastError", "createdAt", "payload", "payloadBody", "attempts" ] } ``` ### #/components/schemas/MessageAttempt ```json { "type": "object", "properties": { "id": { "type": "string" }, "deliveryId": { "type": "string" }, "status": { "type": "string" }, "responseCode": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "deliveryId", "status", "responseCode", "durationMs", "error", "createdAt", "completedAt" ] } ``` # List exact-address routes for a custom domain `GET /api/domains/{id}/routes` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:read`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "routes": { "type": "array", "items": { "$ref": "#/components/schemas/DomainRoute" } }, "allowance": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": [ "integer", "null" ], "minimum": 0 }, "planName": { "type": "string" } }, "required": [ "used", "limit", "planName" ] } }, "required": [ "routes", "allowance" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Domain not found in this account. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/DomainRoute ```json { "type": "object", "description": "An exact local-part route on one customer-owned custom domain. Status reflects whether the account plan and domain allow the route. endpointStatus reports the current endpoint state.", "properties": { "id": { "type": "string", "format": "uuid" }, "domainId": { "type": "string", "format": "uuid" }, "localPart": { "type": "string", "maxLength": 64, "description": "Valid UTF-8 email local part, at most 64 UTF-8 bytes. Trimmed, Unicode-normalized, and lowercased before matching. Matching is case-insensitive. Plus-tags are preserved literally and are not stripped." }, "endpointId": { "type": [ "string", "null" ], "format": "uuid", "description": "Null when the selected endpoint was deleted. The stored exact route still blocks catch-all fallback until deleted or updated." }, "endpointName": { "type": [ "string", "null" ] }, "endpointStatus": { "type": [ "string", "null" ], "enum": [ "active", "paused", "failing", null ] }, "status": { "type": "string", "enum": [ "active", "suspended" ], "description": "Free plan downgrades suspend stored routes. A suspended exact match is rejected during SMTP admission and does not use the catch-all." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "domainId", "localPart", "endpointId", "endpointName", "endpointStatus", "status", "createdAt", "updatedAt" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # List custom domains `GET /api/domains` Hosted test addresses are excluded. Returns DNS instructions, readiness and the custom-domain allowance. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:read`. Audience: management. ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "allowance": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "planName": { "type": "string" } }, "required": [ "used", "limit", "planName" ] } }, "required": [ "domains", "allowance" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Domain ```json { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string" }, "mxStatus": { "type": "string" }, "billingSuspended": { "type": "boolean" }, "ready": { "type": "boolean", "description": "Domain catch-all readiness: ownership verified, MX valid, billing not suspended, and an active catch-all endpoint assigned. False does not rule out delivery through an active exact-address route." }, "endpointId": { "type": [ "string", "null" ] }, "endpointName": { "type": [ "string", "null" ] }, "endpointStatus": { "type": [ "string", "null" ] }, "ownershipVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastOwnershipCheckAt": { "type": [ "string", "null" ], "format": "date-time" }, "mxRecords": { "type": "array", "items": { "type": "string" } }, "mxCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dns": { "type": "object", "properties": { "txtHost": { "type": "string" }, "txtValue": { "type": "string" }, "mxHost": { "type": "string" }, "mxPriority": { "type": "integer" } }, "required": [ "txtHost", "txtValue", "mxHost", "mxPriority" ] } }, "required": [ "id", "domain", "status", "mxStatus", "billingSuspended", "ready", "endpointId", "endpointName", "endpointStatus", "ownershipVerifiedAt", "lastOwnershipCheckAt", "mxRecords", "mxCheckedAt", "createdAt", "updatedAt", "dns" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Get hosted test address `GET /api/hosted-address` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:read`. Audience: management. ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "address": { "type": "string" }, "endpointId": { "type": [ "string", "null" ] }, "endpointName": { "type": [ "string", "null" ] }, "ready": { "type": "boolean" } }, "required": [ "address", "endpointId", "endpointName", "ready" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Test address not assigned. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # List API keys and scopes `GET /api/keys` Browser session only, signed-in account. Lists key metadata and availableScopes. Token secrets are never returned. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Audience: session. ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } }, "availableScopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "description" ] } } }, "required": [ "keys", "availableScopes" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Key ```json { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hint": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "hint", "createdAt", "lastUsedAt", "revokedAt", "scopes" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Download a retained attachment `GET /api/messages/{id}/attachments/{attachmentId}` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `messages:read`. Audience: management. ## Parameters ### id path parameter; required. Opaque message ID returned as receiptId by the message API. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "description": "Opaque message ID returned as receiptId by the message API." } ``` ### attachmentId path parameter; required. Attachment ID from the message details. ```json { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Attachment ID from the message details." } ``` ## Responses ### 200 Attachment bytes. Content type: `application/octet-stream`. Schema: ```json { "type": "string", "format": "binary" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required API key scope is missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Message or attachment not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 410 Attachment content is no longer available under the current retention policy. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Preview message body `GET /api/messages/{id}/preview` Returns a sanitized text or HTML preview of a retained message. Access follows the account's current retention policy. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `messages:read`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ### kind query parameter; optional. ```json { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "text", "html" ], "default": "text" } } ``` ## Responses ### 200 Success Content type: `text/plain`. Schema: ```json { "type": "string" } ``` Content type: `text/html`. Schema: ```json { "type": "string" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Content/body not available (may be empty). Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 413 Body exceeds 2 MiB preview limit. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 Storage unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } } } ``` Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Download raw MIME `GET /api/messages/{id}/raw` Streams the retained RFC 822 email with private, no-store caching. Access follows the account's current retention policy. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `messages:read`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 200 Success Content type: `message/rfc822`. Schema: ```json { "type": "string", "format": "binary" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Message unavailable or expired. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 410 Message content is no longer available under the current retention policy. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 Message storage temporarily unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } } } ``` Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Inspect received message `GET /api/messages/{id}` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `messages:read`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "message": { "allOf": [ { "$ref": "#/components/schemas/MessageSummary" }, { "type": "object", "properties": { "processedAt": { "type": [ "string", "null" ], "format": "date-time" }, "contentAvailable": { "type": "boolean" }, "rawDownloadUrl": { "type": [ "string", "null" ] } }, "required": [ "processedAt", "contentAvailable", "rawDownloadUrl" ] } ] }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/MessageDelivery" } }, "details": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Parsed message details, or null when content is unavailable." } }, "required": [ "message", "details", "deliveries" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Message not found or outside this account. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/MessageSummary ```json { "type": "object", "properties": { "receiptId": { "type": "string", "pattern": "^[a-f0-9]{24}$", "description": "Message identifier. Treat it as opaque." }, "sender": { "type": [ "string", "null" ] }, "recipients": { "type": "array", "items": { "type": "string" } }, "subject": { "type": [ "string", "null" ] }, "messageId": { "type": [ "string", "null" ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "parsed", "failed", "expired" ] }, "processingErrorCode": { "type": [ "string", "null" ] }, "processingError": { "type": [ "string", "null" ] }, "processingAttemptCount": { "type": "integer" }, "processingNextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "rawBytes": { "type": "integer" }, "processedAt": { "type": [ "string", "null" ], "format": "date-time" }, "contentAvailable": { "type": "boolean" }, "rawDownloadUrl": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ], "description": "Conversation ID, identical to message.thread_id in webhooks. Null for unavailable metadata or expired content. Treat as opaque." } }, "required": [ "receiptId", "sender", "recipients", "subject", "messageId", "processingStatus", "processingErrorCode", "processingError", "processingAttemptCount", "processingNextRetryAt", "receivedAt", "expiresAt", "rawBytes", "processedAt", "contentAvailable", "rawDownloadUrl", "threadId" ] } ``` ### #/components/schemas/MessageDelivery ```json { "type": "object", "properties": { "id": { "type": "string" }, "deliveryId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string", "const": "email.received" }, "endpointId": { "type": "string" }, "endpointName": { "type": "string" }, "endpointStatus": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "retrying", "delivered", "failed" ] }, "inProgress": { "type": "boolean" }, "responseCode": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "attemptCount": { "type": "integer" }, "nextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryDeadlineAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "null" }, "payloadBody": { "type": "null" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttempt" } } }, "required": [ "id", "deliveryId", "eventId", "eventType", "endpointId", "endpointName", "endpointStatus", "status", "inProgress", "responseCode", "durationMs", "attemptCount", "nextRetryAt", "deliveryDeadlineAt", "lastError", "createdAt", "payload", "payloadBody", "attempts" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/MessageAttempt ```json { "type": "object", "properties": { "id": { "type": "string" }, "deliveryId": { "type": "string" }, "status": { "type": "string" }, "responseCode": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "deliveryId", "status", "responseCode", "durationMs", "error", "createdAt", "completedAt" ] } ``` # Search received messages `GET /api/messages` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `messages:read`. Audience: management. ## Parameters ### page query parameter; optional. Pages are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page. ```json { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Pages are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page." } ``` ### q query parameter; optional. Case-insensitive substring search. ```json { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring search." } ``` ### status query parameter; optional. ```json { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processing", "parsed", "failed", "expired" ] } } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "messages", "pagination" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/MessageSummary ```json { "type": "object", "properties": { "receiptId": { "type": "string", "pattern": "^[a-f0-9]{24}$", "description": "Message identifier. Treat it as opaque." }, "sender": { "type": [ "string", "null" ] }, "recipients": { "type": "array", "items": { "type": "string" } }, "subject": { "type": [ "string", "null" ] }, "messageId": { "type": [ "string", "null" ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "parsed", "failed", "expired" ] }, "processingErrorCode": { "type": [ "string", "null" ] }, "processingError": { "type": [ "string", "null" ] }, "processingAttemptCount": { "type": "integer" }, "processingNextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "rawBytes": { "type": "integer" }, "processedAt": { "type": [ "string", "null" ], "format": "date-time" }, "contentAvailable": { "type": "boolean" }, "rawDownloadUrl": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ], "description": "Conversation ID, identical to message.thread_id in webhooks. Null for unavailable metadata or expired content. Treat as opaque." } }, "required": [ "receiptId", "sender", "recipients", "subject", "messageId", "processingStatus", "processingErrorCode", "processingError", "processingAttemptCount", "processingNextRetryAt", "receivedAt", "expiresAt", "rawBytes", "processedAt", "contentAvailable", "rawDownloadUrl", "threadId" ] } ``` ### #/components/schemas/Pagination ```json { "type": "object", "properties": { "page": { "type": "integer" }, "pageCount": { "type": "integer" }, "total": { "type": "integer" }, "pageSize": { "type": "integer" } }, "required": [ "page", "pageCount", "total" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Inspect a retained thread `GET /api/threads/{id}` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `messages:read`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } } ``` ### page query parameter; optional. Pages start at 1. Invalid input becomes 1. Pages beyond the result set are empty. ```json { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Pages start at 1. Invalid input becomes 1. Pages beyond the result set are empty." } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "thread": { "$ref": "#/components/schemas/ThreadSummary" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "thread", "messages", "pagination" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Thread not found, outside this account, or without retained messages. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/ThreadSummary ```json { "type": "object", "description": "A complete retained thread, or a single retained message without thread metadata.", "properties": { "threadId": { "type": [ "string", "null" ], "description": "Untranslated conversation ID. Null means the latestMessage stands alone." }, "latestMessage": { "$ref": "#/components/schemas/MessageSummary" }, "messageCount": { "type": "integer", "minimum": 1 }, "firstReceivedAt": { "type": "string", "format": "date-time" }, "latestReceivedAt": { "type": "string", "format": "date-time" }, "statusCounts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "processing": { "type": "integer", "minimum": 0 }, "parsed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "pending", "processing", "parsed", "failed" ], "description": "Message counts for the whole retained thread. Each message is counted once." } }, "required": [ "threadId", "latestMessage", "messageCount", "firstReceivedAt", "latestReceivedAt", "statusCounts" ] } ``` ### #/components/schemas/MessageSummary ```json { "type": "object", "properties": { "receiptId": { "type": "string", "pattern": "^[a-f0-9]{24}$", "description": "Message identifier. Treat it as opaque." }, "sender": { "type": [ "string", "null" ] }, "recipients": { "type": "array", "items": { "type": "string" } }, "subject": { "type": [ "string", "null" ] }, "messageId": { "type": [ "string", "null" ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "parsed", "failed", "expired" ] }, "processingErrorCode": { "type": [ "string", "null" ] }, "processingError": { "type": [ "string", "null" ] }, "processingAttemptCount": { "type": "integer" }, "processingNextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "rawBytes": { "type": "integer" }, "processedAt": { "type": [ "string", "null" ], "format": "date-time" }, "contentAvailable": { "type": "boolean" }, "rawDownloadUrl": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ], "description": "Conversation ID, identical to message.thread_id in webhooks. Null for unavailable metadata or expired content. Treat as opaque." } }, "required": [ "receiptId", "sender", "recipients", "subject", "messageId", "processingStatus", "processingErrorCode", "processingError", "processingAttemptCount", "processingNextRetryAt", "receivedAt", "expiresAt", "rawBytes", "processedAt", "contentAvailable", "rawDownloadUrl", "threadId" ] } ``` ### #/components/schemas/Pagination ```json { "type": "object", "properties": { "page": { "type": "integer" }, "pageCount": { "type": "integer" }, "total": { "type": "integer" }, "pageSize": { "type": "integer" } }, "required": [ "page", "pageCount", "total" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # List retained threads `GET /api/threads` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `messages:read`. Audience: management. ## Parameters ### page query parameter; optional. Pages start at 1. Invalid input becomes 1. Pages beyond the result set are empty. ```json { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Pages start at 1. Invalid input becomes 1. Pages beyond the result set are empty." } ``` ### q query parameter; optional. Case-insensitive substring search. ```json { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring search." } ``` ### status query parameter; optional. Match any retained member with this message status. parsed means complete. expired returns no threads. ```json { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processing", "parsed", "failed", "expired" ] }, "description": "Match any retained member with this message status. parsed means complete. expired returns no threads." } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "retentionDays": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "threads", "pagination", "retentionDays" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/ThreadSummary ```json { "type": "object", "description": "A complete retained thread, or a single retained message without thread metadata.", "properties": { "threadId": { "type": [ "string", "null" ], "description": "Untranslated conversation ID. Null means the latestMessage stands alone." }, "latestMessage": { "$ref": "#/components/schemas/MessageSummary" }, "messageCount": { "type": "integer", "minimum": 1 }, "firstReceivedAt": { "type": "string", "format": "date-time" }, "latestReceivedAt": { "type": "string", "format": "date-time" }, "statusCounts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "processing": { "type": "integer", "minimum": 0 }, "parsed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "pending", "processing", "parsed", "failed" ], "description": "Message counts for the whole retained thread. Each message is counted once." } }, "required": [ "threadId", "latestMessage", "messageCount", "firstReceivedAt", "latestReceivedAt", "statusCounts" ] } ``` ### #/components/schemas/Pagination ```json { "type": "object", "properties": { "page": { "type": "integer" }, "pageCount": { "type": "integer" }, "total": { "type": "integer" }, "pageSize": { "type": "integer" } }, "required": [ "page", "pageCount", "total" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/MessageSummary ```json { "type": "object", "properties": { "receiptId": { "type": "string", "pattern": "^[a-f0-9]{24}$", "description": "Message identifier. Treat it as opaque." }, "sender": { "type": [ "string", "null" ] }, "recipients": { "type": "array", "items": { "type": "string" } }, "subject": { "type": [ "string", "null" ] }, "messageId": { "type": [ "string", "null" ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "parsed", "failed", "expired" ] }, "processingErrorCode": { "type": [ "string", "null" ] }, "processingError": { "type": [ "string", "null" ] }, "processingAttemptCount": { "type": "integer" }, "processingNextRetryAt": { "type": [ "string", "null" ], "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "rawBytes": { "type": "integer" }, "processedAt": { "type": [ "string", "null" ], "format": "date-time" }, "contentAvailable": { "type": "boolean" }, "rawDownloadUrl": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ], "description": "Conversation ID, identical to message.thread_id in webhooks. Null for unavailable metadata or expired content. Treat as opaque." } }, "required": [ "receiptId", "sender", "recipients", "subject", "messageId", "processingStatus", "processingErrorCode", "processingError", "processingAttemptCount", "processingNextRetryAt", "receivedAt", "expiresAt", "rawBytes", "processedAt", "contentAvailable", "rawDownloadUrl", "threadId" ] } ``` # Get account usage `GET /api/usage` Returns the account plan, UTC-month accepted-message allowance, custom domains, exact-address routes, storage quota and current retention setting. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `usage:read`. Audience: management. ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "usage" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Account not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Usage ```json { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/Plan" }, "retention": { "type": "object", "description": "Current account retention policy. Changes apply to existing and newly accepted messages.", "properties": { "retentionDays": { "type": "integer", "minimum": 0 }, "maxDays": { "type": "integer", "minimum": 1 }, "configuredDays": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "retentionDays", "maxDays", "configuredDays" ] }, "period": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "resetsAt": { "type": "string", "format": "date-time" } }, "required": [ "start", "resetsAt" ] }, "messages": { "type": "object", "properties": { "accepted": { "type": "integer" }, "reserved": { "type": "integer" }, "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "status": { "type": "string", "enum": [ "available", "approaching", "reached" ] } }, "required": [ "accepted", "reserved", "limit", "remaining", "status" ] }, "domains": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "remaining": { "type": [ "integer", "null" ] } }, "required": [ "used", "limit", "remaining" ] }, "addressRoutes": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "remaining": { "type": [ "integer", "null" ] } }, "required": [ "used", "limit", "remaining" ] }, "storage": { "$ref": "#/components/schemas/StorageUsage" } }, "required": [ "plan", "retention", "period", "messages", "domains", "addressRoutes", "storage" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/Plan ```json { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "offered": { "type": "boolean" }, "monthlyPriceEur": { "type": [ "number", "null" ] }, "customDomains": { "type": [ "integer", "null" ] }, "monthlyMessages": { "type": "integer" }, "rawMessageLimitBytes": { "type": "integer" }, "retentionDays": { "type": "integer", "minimum": 1, "description": "Maximum content retention for this plan. Account settings may select 0 days or any whole number of days from 1 through this maximum." }, "storageLimitBytes": { "type": "integer", "minimum": 0, "description": "Current retained storage capacity in bytes. One GB is 1,000,000,000 bytes." }, "artifactDownloadLimitBytes": { "type": "integer", "description": "Informational plan value in bytes. It is not an enforced monthly attachment-download limit." }, "perAddressRoutes": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "id", "name", "offered", "monthlyPriceEur", "customDomains", "monthlyMessages", "rawMessageLimitBytes", "retentionDays", "storageLimitBytes", "artifactDownloadLimitBytes", "perAddressRoutes" ] } ``` ### #/components/schemas/StorageUsage ```json { "type": "object", "properties": { "rawBytes": { "type": "integer" }, "artifactBytes": { "type": "integer" }, "retainedBytes": { "type": "integer" }, "reservedBytes": { "type": "integer" }, "limitBytes": { "type": "integer" }, "remainingBytes": { "type": "integer" }, "status": { "type": "string", "enum": [ "available", "approaching", "reached" ] } }, "required": [ "rawBytes", "artifactBytes", "retainedBytes", "reservedBytes", "limitBytes", "remainingBytes", "status" ] } ``` # Inspect webhook endpoint `GET /api/webhooks/{id}` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `webhooks:read`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ### page query parameter; optional. Pages are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page. ```json { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Pages are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page." } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/Endpoint" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointDeliverySummary" } }, "pagination": { "anyOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "null" } ] } }, "required": [ "endpoint", "deliveries", "pagination" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Endpoint not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Endpoint ```json { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "failing" ] }, "signingSecretHint": { "type": "string" }, "secretReady": { "type": "boolean" }, "subscribedEvents": { "type": "array", "items": { "type": "string" } }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "payloadMapping": { "anyOf": [ { "$ref": "#/components/schemas/PayloadMapping" }, { "type": "null" } ], "description": "Null uses the standard body. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body." } }, "required": [ "id", "name", "url", "description", "status", "signingSecretHint", "secretReady", "subscribedEvents", "lastDeliveryAt", "payloadMapping" ] } ``` ### #/components/schemas/EndpointDeliverySummary ```json { "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string", "const": "email.received" }, "status": { "type": "string" }, "responseCode": { "type": [ "integer", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "messageId": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{24}$" } }, "required": [ "id", "eventId", "eventType", "status", "responseCode", "createdAt", "messageId" ] } ``` ### #/components/schemas/Pagination ```json { "type": "object", "properties": { "page": { "type": "integer" }, "pageCount": { "type": "integer" }, "total": { "type": "integer" }, "pageSize": { "type": "integer" } }, "required": [ "page", "pageCount", "total" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/PayloadMapping ```json { "type": "object", "additionalProperties": false, "description": "Version 1 copies and reshapes fields from the standard wildmail.v1 event. Root output must be an object. Missing fields become null and missing arrays become []. Unmapped fields are omitted. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body. Maximum input size 64 KiB, 500 nodes, depth 12 including root, and 128 MiB output. No scripts, constants, fetching, or type conversion. Unsafe keys and pointer segments __proto__, prototype, constructor are rejected.", "properties": { "version": { "const": 1 }, "output": { "$ref": "#/components/schemas/PayloadObjectNode" } }, "required": [ "version", "output" ], "example": { "version": 1, "output": { "type": "object", "fields": { "title": { "type": "field", "path": "/subject" }, "files": { "type": "array", "path": "/attachments", "items": { "type": "field", "path": "/filename" } } } } } } ``` ### #/components/schemas/PayloadObjectNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "object" }, "fields": { "type": "object", "propertyNames": { "minLength": 1, "maxLength": 128, "not": { "enum": [ "__proto__", "prototype", "constructor" ] } }, "additionalProperties": { "$ref": "#/components/schemas/PayloadMappingNode" } } }, "required": [ "type", "fields" ] } ``` ### #/components/schemas/PayloadMappingNode ```json { "oneOf": [ { "$ref": "#/components/schemas/PayloadFieldNode" }, { "$ref": "#/components/schemas/PayloadObjectNode" }, { "$ref": "#/components/schemas/PayloadArrayNode" } ] } ``` ### #/components/schemas/PayloadFieldNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "field" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." } }, "required": [ "type", "path" ] } ``` ### #/components/schemas/PayloadArrayNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "array" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." }, "items": { "$ref": "#/components/schemas/PayloadMappingNode" } }, "required": [ "type", "path", "items" ] } ``` # List webhook endpoints `GET /api/webhooks` Returns public endpoint metadata. Signing secrets are never returned by reads. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `webhooks:read`. Audience: management. ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } } }, "required": [ "endpoints" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Endpoint ```json { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "failing" ] }, "signingSecretHint": { "type": "string" }, "secretReady": { "type": "boolean" }, "subscribedEvents": { "type": "array", "items": { "type": "string" } }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "payloadMapping": { "anyOf": [ { "$ref": "#/components/schemas/PayloadMapping" }, { "type": "null" } ], "description": "Null uses the standard body. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body." } }, "required": [ "id", "name", "url", "description", "status", "signingSecretHint", "secretReady", "subscribedEvents", "lastDeliveryAt", "payloadMapping" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/PayloadMapping ```json { "type": "object", "additionalProperties": false, "description": "Version 1 copies and reshapes fields from the standard wildmail.v1 event. Root output must be an object. Missing fields become null and missing arrays become []. Unmapped fields are omitted. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body. Maximum input size 64 KiB, 500 nodes, depth 12 including root, and 128 MiB output. No scripts, constants, fetching, or type conversion. Unsafe keys and pointer segments __proto__, prototype, constructor are rejected.", "properties": { "version": { "const": 1 }, "output": { "$ref": "#/components/schemas/PayloadObjectNode" } }, "required": [ "version", "output" ], "example": { "version": 1, "output": { "type": "object", "fields": { "title": { "type": "field", "path": "/subject" }, "files": { "type": "array", "path": "/attachments", "items": { "type": "field", "path": "/filename" } } } } } } ``` ### #/components/schemas/PayloadObjectNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "object" }, "fields": { "type": "object", "propertyNames": { "minLength": 1, "maxLength": 128, "not": { "enum": [ "__proto__", "prototype", "constructor" ] } }, "additionalProperties": { "$ref": "#/components/schemas/PayloadMappingNode" } } }, "required": [ "type", "fields" ] } ``` ### #/components/schemas/PayloadMappingNode ```json { "oneOf": [ { "$ref": "#/components/schemas/PayloadFieldNode" }, { "$ref": "#/components/schemas/PayloadObjectNode" }, { "$ref": "#/components/schemas/PayloadArrayNode" } ] } ``` ### #/components/schemas/PayloadFieldNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "field" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." } }, "required": [ "type", "path" ] } ``` ### #/components/schemas/PayloadArrayNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "array" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." }, "items": { "$ref": "#/components/schemas/PayloadMappingNode" } }, "required": [ "type", "path", "items" ] } ``` # Hosted address Connect a hosted test address before changing DNS. [Download the OpenAPI specification](/openapi.json). ## Operations - [Get hosted test address](/docs/api/generated/get-api-hosted-address.md) - [Set hosted address destination](/docs/api/generated/put-api-hosted-address.md) # Messages Search, inspect, and download retained messages and attachments. [Download the OpenAPI specification](/openapi.json). ## Operations - [Download a retained attachment](/docs/api/generated/get-api-messages-id-attachments-attachment-id.md) - [Preview message body](/docs/api/generated/get-api-messages-id-preview.md) - [Download raw MIME](/docs/api/generated/get-api-messages-id-raw.md) - [Inspect received message](/docs/api/generated/get-api-messages-id.md) - [Search received messages](/docs/api/generated/get-api-messages.md) # Delete account `POST /api/account/delete` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. ## Parameters ### Origin header parameter; required. Must match the configured Wildmail application origin. ```json { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Must match the configured Wildmail application origin." } ``` ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "confirmation": { "type": "string", "const": "DELETE" } }, "required": [ "confirmation" ], "additionalProperties": false } ``` Example: ```json { "confirmation": "DELETE" } ``` ## Responses ### 200 Deletion completed. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } ``` ### 400 The confirmation value is missing or invalid. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 A signed-in session is required. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Cross-origin request refused. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 503 Deletion is still in progress. Retry the request or contact support. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Browser authentication action `POST /api/auth/{path}` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication No authentication scheme is required by this operation. Audience: auth. ## Parameters ### path path parameter; required. ```json { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 200 Library-defined response: JSON, redirect or session-cookie update according to the selected auth endpoint. Schema intentionally unspecified. ### 400 Authentication validation error. ### 401 Authentication required. ### 403 Origin or authorization denied. ### 429 Authentication rate limit. Shared request limiting can also return 429 rate_limit_exceeded with Retry-After (seconds) and Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying a throttled authentication request.", "schema": { "type": "integer", "minimum": 1 } } } ``` Content type: `application/json`. Schema: ```json { "anyOf": [ { "$ref": "#/components/schemas/RequestLimitError" }, { "type": "object", "description": "Authentication error returned by the selected sign-in action." } ] } ``` ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/RequestLimitError ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "rate_limit_exceeded", "rate_limit_unavailable" ] } }, "required": [ "error", "code" ] } ``` # Create checkout session `POST /api/billing/checkout` Browser session only, signed-in account owner. Origin must exactly match the configured application origin. Creates hosted Stripe Checkout for Starter or Growth. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Audience: session. ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "Starter", "Growth" ] } }, "required": [ "plan" ] } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } ``` ### 400 Missing or invalid plan. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 account missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 409 Existing subscription/conflicting billing operation where applicable. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 Billing/provider unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } } } ``` Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Create billing portal session `POST /api/billing/portal` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Audience: session. ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 account missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 409 Existing subscription/conflicting billing operation where applicable. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 Billing/provider unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } } } ``` Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Refresh billing state `POST /api/billing/sync` Browser session only, signed-in account owner. No body. Origin must exactly match the configured application origin. Synchronizes provider state and returns updated summary. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Audience: session. ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "billing": { "$ref": "#/components/schemas/Billing" } }, "required": [ "billing" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 account missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 409 Existing subscription/conflicting billing operation where applicable. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 Billing/provider unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } } } ``` Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Billing ```json { "type": "object", "properties": { "plan": { "type": "string" }, "status": { "type": "string" }, "hasCustomer": { "type": "boolean" }, "hasSubscription": { "type": "boolean" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "graceUntil": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "lastSyncedAt": { "type": [ "string", "null" ], "format": "date-time" }, "suspendedDomains": { "type": "array", "items": { "type": "string" } } }, "required": [ "plan", "status", "hasCustomer", "hasSubscription", "currentPeriodEnd", "graceUntil", "cancelAtPeriodEnd", "lastSyncedAt", "suspendedDomains" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Upgrade Starter to Growth `POST /api/billing/upgrade` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Audience: session. ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "billing": { "$ref": "#/components/schemas/Billing" } }, "required": [ "billing" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 account missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 409 Subscription cannot be changed or has a conflicting operation. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 Billing/provider unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } } } ``` Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Billing ```json { "type": "object", "properties": { "plan": { "type": "string" }, "status": { "type": "string" }, "hasCustomer": { "type": "boolean" }, "hasSubscription": { "type": "boolean" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "graceUntil": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "lastSyncedAt": { "type": [ "string", "null" ], "format": "date-time" }, "suspendedDomains": { "type": "array", "items": { "type": "string" } } }, "required": [ "plan", "status", "hasCustomer", "hasSubscription", "currentPeriodEnd", "graceUntil", "cancelAtPeriodEnd", "lastSyncedAt", "suspendedDomains" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Replay delivery `POST /api/deliveries/{id}/replay` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `deliveries:replay`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 202 Success Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Queued" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Delivery not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 409 Inactive/unconfigured endpoint, unavailable payload or delivery in flight. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 410 Content or replay window expired. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Queued ```json { "type": "object", "properties": { "queued": { "type": "boolean" }, "deliveryId": { "type": "string" }, "eventId": { "type": "string" } }, "required": [ "queued", "deliveryId", "eventId" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Create an exact-address route `POST /api/domains/{id}/routes` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:write`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ``` ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "localPart": { "type": "string", "maxLength": 64, "description": "Valid UTF-8 email local part, at most 64 UTF-8 bytes. Trimmed, Unicode-normalized, and lowercased before matching. Plus-tags are preserved literally and are not stripped. Patterns are not supported." }, "endpointId": { "type": "string", "format": "uuid" } }, "required": [ "localPart", "endpointId" ] } ``` Example: ```json { "localPart": "orders+acme", "endpointId": "11111111-1111-4111-8111-111111111111" } ``` ## Responses ### 201 Created Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "route": { "$ref": "#/components/schemas/DomainRoute" } }, "required": [ "route" ] } ``` ### 400 Invalid local part or endpoint identifier. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Domain or endpoint not found in this account. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 409 Exact route already exists or the account allowance is exhausted. For Free, code is route_limit_reached and limit is 0. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/DomainRoute ```json { "type": "object", "description": "An exact local-part route on one customer-owned custom domain. Status reflects whether the account plan and domain allow the route. endpointStatus reports the current endpoint state.", "properties": { "id": { "type": "string", "format": "uuid" }, "domainId": { "type": "string", "format": "uuid" }, "localPart": { "type": "string", "maxLength": 64, "description": "Valid UTF-8 email local part, at most 64 UTF-8 bytes. Trimmed, Unicode-normalized, and lowercased before matching. Matching is case-insensitive. Plus-tags are preserved literally and are not stripped." }, "endpointId": { "type": [ "string", "null" ], "format": "uuid", "description": "Null when the selected endpoint was deleted. The stored exact route still blocks catch-all fallback until deleted or updated." }, "endpointName": { "type": [ "string", "null" ] }, "endpointStatus": { "type": [ "string", "null" ], "enum": [ "active", "paused", "failing", null ] }, "status": { "type": "string", "enum": [ "active", "suspended" ], "description": "Free plan downgrades suspend stored routes. A suspended exact match is rejected during SMTP admission and does not use the catch-all." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "domainId", "localPart", "endpointId", "endpointName", "endpointStatus", "status", "createdAt", "updatedAt" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Check domain DNS `POST /api/domains/{id}/verify` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:write`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "domain": { "$ref": "#/components/schemas/Domain" }, "observed": { "type": "object", "properties": { "ownership": { "type": "boolean" }, "mx": { "type": "boolean" } }, "required": [ "ownership", "mx" ] } }, "required": [ "domain", "observed" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Domain not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 DNS lookup unavailable or timed out. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } } } ``` Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Domain ```json { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string" }, "mxStatus": { "type": "string" }, "billingSuspended": { "type": "boolean" }, "ready": { "type": "boolean", "description": "Domain catch-all readiness: ownership verified, MX valid, billing not suspended, and an active catch-all endpoint assigned. False does not rule out delivery through an active exact-address route." }, "endpointId": { "type": [ "string", "null" ] }, "endpointName": { "type": [ "string", "null" ] }, "endpointStatus": { "type": [ "string", "null" ] }, "ownershipVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastOwnershipCheckAt": { "type": [ "string", "null" ], "format": "date-time" }, "mxRecords": { "type": "array", "items": { "type": "string" } }, "mxCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dns": { "type": "object", "properties": { "txtHost": { "type": "string" }, "txtValue": { "type": "string" }, "mxHost": { "type": "string" }, "mxPriority": { "type": "integer" } }, "required": [ "txtHost", "txtValue", "mxHost", "mxPriority" ] } }, "required": [ "id", "domain", "status", "mxStatus", "billingSuspended", "ready", "endpointId", "endpointName", "endpointStatus", "ownershipVerifiedAt", "lastOwnershipCheckAt", "mxRecords", "mxCheckedAt", "createdAt", "updatedAt", "dns" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Create a custom domain `POST /api/domains` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:write`. Audience: management. ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "domain": { "type": "string" }, "endpointId": { "type": [ "string", "null" ] } }, "required": [ "domain" ] } ``` Example: ```json { "domain": "in.example.com", "endpointId": "11111111-1111-4111-8111-111111111111" } ``` ## Responses ### 201 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "domain": { "$ref": "#/components/schemas/Domain" } }, "required": [ "domain" ] } ``` ### 400 Invalid request. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Resource not found in this account. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 409 Already claimed or domain_limit_reached. Quota errors include the limit. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Domain ```json { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string" }, "mxStatus": { "type": "string" }, "billingSuspended": { "type": "boolean" }, "ready": { "type": "boolean", "description": "Domain catch-all readiness: ownership verified, MX valid, billing not suspended, and an active catch-all endpoint assigned. False does not rule out delivery through an active exact-address route." }, "endpointId": { "type": [ "string", "null" ] }, "endpointName": { "type": [ "string", "null" ] }, "endpointStatus": { "type": [ "string", "null" ] }, "ownershipVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastOwnershipCheckAt": { "type": [ "string", "null" ], "format": "date-time" }, "mxRecords": { "type": "array", "items": { "type": "string" } }, "mxCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dns": { "type": "object", "properties": { "txtHost": { "type": "string" }, "txtValue": { "type": "string" }, "mxHost": { "type": "string" }, "mxPriority": { "type": "integer" } }, "required": [ "txtHost", "txtValue", "mxHost", "mxPriority" ] } }, "required": [ "id", "domain", "status", "mxStatus", "billingSuspended", "ready", "endpointId", "endpointName", "endpointStatus", "ownershipVerifiedAt", "lastOwnershipCheckAt", "mxRecords", "mxCheckedAt", "createdAt", "updatedAt", "dns" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Create scoped API key `POST /api/keys` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Audience: session. ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true } }, "required": [ "name", "scopes" ] } ``` Example: ```json { "name": "Order intake integration", "scopes": [ "messages:read", "deliveries:read", "deliveries:replay" ] } ``` ## Responses ### 201 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/Key" }, "token": { "type": "string" } }, "required": [ "key", "token" ] } ``` ### 400 Invalid name or scope selection. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Key ```json { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hint": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "hint", "createdAt", "lastUsedAt", "revokedAt", "scopes" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Preview a draft webhook payload mapping `POST /api/webhooks/{id}/preview` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `webhooks:read`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "payloadMapping": { "anyOf": [ { "$ref": "#/components/schemas/PayloadMapping" }, { "type": "null" } ], "description": "One optional mapping per endpoint. Null uses the standard webhook body. Mapping changes apply only to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body." }, "sample": { "type": "object", "additionalProperties": true, "description": "Sample webhook object. May omit optional fields to inspect missing-value behavior." } }, "required": [ "payloadMapping", "sample" ] } ``` Example: ```json { "payloadMapping": { "version": 1, "output": { "type": "object", "fields": { "title": { "type": "field", "path": "/subject" } } } }, "sample": { "subject": "Purchase order PO-8812" } } ``` ## Responses ### 200 Successful preview output and exact body. The errors array is empty. Missing source values are reported separately in missingPaths. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/PayloadPreview" } ``` ### 400 Malformed input, invalid mapping, or evaluation failure. Mapping errors include field-level errors with path and message. Evaluation failures return null output and body. Content type: `application/json`. Schema: ```json { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/PayloadPreview" } ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Endpoint not found in this account. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/PayloadMapping ```json { "type": "object", "additionalProperties": false, "description": "Version 1 copies and reshapes fields from the standard wildmail.v1 event. Root output must be an object. Missing fields become null and missing arrays become []. Unmapped fields are omitted. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body. Maximum input size 64 KiB, 500 nodes, depth 12 including root, and 128 MiB output. No scripts, constants, fetching, or type conversion. Unsafe keys and pointer segments __proto__, prototype, constructor are rejected.", "properties": { "version": { "const": 1 }, "output": { "$ref": "#/components/schemas/PayloadObjectNode" } }, "required": [ "version", "output" ], "example": { "version": 1, "output": { "type": "object", "fields": { "title": { "type": "field", "path": "/subject" }, "files": { "type": "array", "path": "/attachments", "items": { "type": "field", "path": "/filename" } } } } } } ``` ### #/components/schemas/PayloadPreview ```json { "type": "object", "properties": { "output": { "type": [ "object", "null" ], "additionalProperties": true }, "body": { "type": [ "string", "null" ], "description": "Exact serialized JSON body, or null when evaluation fails." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/PayloadMappingError" } }, "missingPaths": { "type": "array", "items": { "type": "string" }, "description": "Output JSON Pointers for missing sample values. Missing sources produce null or empty arrays." } }, "required": [ "output", "body", "errors", "missingPaths" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/PayloadObjectNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "object" }, "fields": { "type": "object", "propertyNames": { "minLength": 1, "maxLength": 128, "not": { "enum": [ "__proto__", "prototype", "constructor" ] } }, "additionalProperties": { "$ref": "#/components/schemas/PayloadMappingNode" } } }, "required": [ "type", "fields" ] } ``` ### #/components/schemas/PayloadMappingError ```json { "type": "object", "properties": { "path": { "type": "string", "description": "JSON Pointer identifying the invalid field." }, "message": { "type": "string" } }, "required": [ "path", "message" ] } ``` ### #/components/schemas/PayloadMappingNode ```json { "oneOf": [ { "$ref": "#/components/schemas/PayloadFieldNode" }, { "$ref": "#/components/schemas/PayloadObjectNode" }, { "$ref": "#/components/schemas/PayloadArrayNode" } ] } ``` ### #/components/schemas/PayloadFieldNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "field" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." } }, "required": [ "type", "path" ] } ``` ### #/components/schemas/PayloadArrayNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "array" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." }, "items": { "$ref": "#/components/schemas/PayloadMappingNode" } }, "required": [ "type", "path", "items" ] } ``` # Queue a test webhook `POST /api/webhooks/{id}/test` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `webhooks:write`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 202 Success Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Queued" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Endpoint not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 409 Endpoint paused or not configured. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Queued ```json { "type": "object", "properties": { "queued": { "type": "boolean" }, "deliveryId": { "type": "string" }, "eventId": { "type": "string" } }, "required": [ "queued", "deliveryId", "eventId" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Rotate webhook signing secret `POST /api/webhooks/{id}` Rotates the endpoint signing secret. The new secret is returned once. Accepted messages continue to use their pinned signing-key version. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `webhooks:admin`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/Endpoint" }, "signingSecret": { "type": "string" } }, "required": [ "endpoint", "signingSecret" ] } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Endpoint not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 Secret encryption unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } } } ``` Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Endpoint ```json { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "failing" ] }, "signingSecretHint": { "type": "string" }, "secretReady": { "type": "boolean" }, "subscribedEvents": { "type": "array", "items": { "type": "string" } }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "payloadMapping": { "anyOf": [ { "$ref": "#/components/schemas/PayloadMapping" }, { "type": "null" } ], "description": "Null uses the standard body. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body." } }, "required": [ "id", "name", "url", "description", "status", "signingSecretHint", "secretReady", "subscribedEvents", "lastDeliveryAt", "payloadMapping" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/PayloadMapping ```json { "type": "object", "additionalProperties": false, "description": "Version 1 copies and reshapes fields from the standard wildmail.v1 event. Root output must be an object. Missing fields become null and missing arrays become []. Unmapped fields are omitted. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body. Maximum input size 64 KiB, 500 nodes, depth 12 including root, and 128 MiB output. No scripts, constants, fetching, or type conversion. Unsafe keys and pointer segments __proto__, prototype, constructor are rejected.", "properties": { "version": { "const": 1 }, "output": { "$ref": "#/components/schemas/PayloadObjectNode" } }, "required": [ "version", "output" ], "example": { "version": 1, "output": { "type": "object", "fields": { "title": { "type": "field", "path": "/subject" }, "files": { "type": "array", "path": "/attachments", "items": { "type": "field", "path": "/filename" } } } } } } ``` ### #/components/schemas/PayloadObjectNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "object" }, "fields": { "type": "object", "propertyNames": { "minLength": 1, "maxLength": 128, "not": { "enum": [ "__proto__", "prototype", "constructor" ] } }, "additionalProperties": { "$ref": "#/components/schemas/PayloadMappingNode" } } }, "required": [ "type", "fields" ] } ``` ### #/components/schemas/PayloadMappingNode ```json { "oneOf": [ { "$ref": "#/components/schemas/PayloadFieldNode" }, { "$ref": "#/components/schemas/PayloadObjectNode" }, { "$ref": "#/components/schemas/PayloadArrayNode" } ] } ``` ### #/components/schemas/PayloadFieldNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "field" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." } }, "required": [ "type", "path" ] } ``` ### #/components/schemas/PayloadArrayNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "array" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." }, "items": { "$ref": "#/components/schemas/PayloadMappingNode" } }, "required": [ "type", "path", "items" ] } ``` # Create webhook endpoint `POST /api/webhooks` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `webhooks:write`. Audience: management. ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ], "maxLength": 300 }, "payloadMapping": { "anyOf": [ { "$ref": "#/components/schemas/PayloadMapping" }, { "type": "null" } ], "description": "One optional mapping per endpoint. Null uses the standard webhook body. Mapping changes apply only to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body." } }, "required": [ "name", "url" ] } ``` Example: ```json { "name": "Order intake", "url": "https://api.example.com/email", "description": "Incoming purchase orders" } ``` ## Responses ### 201 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/Endpoint" }, "signingSecret": { "type": "string" } }, "required": [ "endpoint", "signingSecret" ] } ``` ### 400 Invalid fields or unsafe destination. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 500 Creation failed. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 503 Webhook secret encryption unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store. Headers: ```json { "Cache-Control": { "description": "Request limiter responses use no-store.", "schema": { "type": "string" } } } ``` Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/PayloadMapping ```json { "type": "object", "additionalProperties": false, "description": "Version 1 copies and reshapes fields from the standard wildmail.v1 event. Root output must be an object. Missing fields become null and missing arrays become []. Unmapped fields are omitted. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body. Maximum input size 64 KiB, 500 nodes, depth 12 including root, and 128 MiB output. No scripts, constants, fetching, or type conversion. Unsafe keys and pointer segments __proto__, prototype, constructor are rejected.", "properties": { "version": { "const": 1 }, "output": { "$ref": "#/components/schemas/PayloadObjectNode" } }, "required": [ "version", "output" ], "example": { "version": 1, "output": { "type": "object", "fields": { "title": { "type": "field", "path": "/subject" }, "files": { "type": "array", "path": "/attachments", "items": { "type": "field", "path": "/filename" } } } } } } ``` ### #/components/schemas/Endpoint ```json { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "failing" ] }, "signingSecretHint": { "type": "string" }, "secretReady": { "type": "boolean" }, "subscribedEvents": { "type": "array", "items": { "type": "string" } }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "payloadMapping": { "anyOf": [ { "$ref": "#/components/schemas/PayloadMapping" }, { "type": "null" } ], "description": "Null uses the standard body. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body." } }, "required": [ "id", "name", "url", "description", "status", "signingSecretHint", "secretReady", "subscribedEvents", "lastDeliveryAt", "payloadMapping" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/PayloadObjectNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "object" }, "fields": { "type": "object", "propertyNames": { "minLength": 1, "maxLength": 128, "not": { "enum": [ "__proto__", "prototype", "constructor" ] } }, "additionalProperties": { "$ref": "#/components/schemas/PayloadMappingNode" } } }, "required": [ "type", "fields" ] } ``` ### #/components/schemas/PayloadMappingNode ```json { "oneOf": [ { "$ref": "#/components/schemas/PayloadFieldNode" }, { "$ref": "#/components/schemas/PayloadObjectNode" }, { "$ref": "#/components/schemas/PayloadArrayNode" } ] } ``` ### #/components/schemas/PayloadFieldNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "field" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." } }, "required": [ "type", "path" ] } ``` ### #/components/schemas/PayloadArrayNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "array" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." }, "items": { "$ref": "#/components/schemas/PayloadMappingNode" } }, "required": [ "type", "path", "items" ] } ``` # Update account retention `PUT /api/account` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "retentionDays": { "type": "integer", "minimum": 0 } }, "required": [ "retentionDays" ], "additionalProperties": false } ``` Example: ```json { "retentionDays": 7 } ``` ## Responses ### 200 Retention setting updated. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "account": { "type": "object", "properties": { "retentionDays": { "type": "integer", "minimum": 0 } }, "required": [ "retentionDays" ] } }, "required": [ "account" ] } ``` ### 400 Retention must be a whole number within the account plan's maximum. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 A signed-in session is required. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Account not found. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 503 Retention could not be synchronized. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Update an exact-address route `PUT /api/domains/{id}/routes/{routeId}` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:write`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ``` ### routeId path parameter; required. ```json { "name": "routeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ``` ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "localPart": { "type": "string", "maxLength": 64, "description": "Valid UTF-8 email local part, at most 64 UTF-8 bytes. Trimmed, Unicode-normalized, and lowercased before matching. Plus-tags are preserved literally and are not stripped. Patterns are not supported." }, "endpointId": { "type": "string", "format": "uuid" } }, "required": [ "localPart", "endpointId" ] } ``` Example: ```json { "localPart": "orders+acme", "endpointId": "11111111-1111-4111-8111-111111111111" } ``` ## Responses ### 200 Updated Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "route": { "$ref": "#/components/schemas/DomainRoute" } }, "required": [ "route" ] } ``` ### 400 Invalid local part or endpoint identifier. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Domain, route or endpoint not found in this account. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 409 The local part is already routed on this domain. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/DomainRoute ```json { "type": "object", "description": "An exact local-part route on one customer-owned custom domain. Status reflects whether the account plan and domain allow the route. endpointStatus reports the current endpoint state.", "properties": { "id": { "type": "string", "format": "uuid" }, "domainId": { "type": "string", "format": "uuid" }, "localPart": { "type": "string", "maxLength": 64, "description": "Valid UTF-8 email local part, at most 64 UTF-8 bytes. Trimmed, Unicode-normalized, and lowercased before matching. Matching is case-insensitive. Plus-tags are preserved literally and are not stripped." }, "endpointId": { "type": [ "string", "null" ], "format": "uuid", "description": "Null when the selected endpoint was deleted. The stored exact route still blocks catch-all fallback until deleted or updated." }, "endpointName": { "type": [ "string", "null" ] }, "endpointStatus": { "type": [ "string", "null" ], "enum": [ "active", "paused", "failing", null ] }, "status": { "type": "string", "enum": [ "active", "suspended" ], "description": "Free plan downgrades suspend stored routes. A suspended exact match is rejected during SMTP admission and does not use the catch-all." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "domainId", "localPart", "endpointId", "endpointName", "endpointStatus", "status", "createdAt", "updatedAt" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Set domain destination `PUT /api/domains/{id}` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:write`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "endpointId": { "type": [ "string", "null" ] } }, "required": [ "endpointId" ] } ``` Example: ```json { "endpointId": "11111111-1111-4111-8111-111111111111" } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "domain": { "$ref": "#/components/schemas/Domain" } }, "required": [ "domain" ] } ``` ### 400 Invalid request. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Resource not found in this account. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Domain ```json { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string" }, "mxStatus": { "type": "string" }, "billingSuspended": { "type": "boolean" }, "ready": { "type": "boolean", "description": "Domain catch-all readiness: ownership verified, MX valid, billing not suspended, and an active catch-all endpoint assigned. False does not rule out delivery through an active exact-address route." }, "endpointId": { "type": [ "string", "null" ] }, "endpointName": { "type": [ "string", "null" ] }, "endpointStatus": { "type": [ "string", "null" ] }, "ownershipVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastOwnershipCheckAt": { "type": [ "string", "null" ], "format": "date-time" }, "mxRecords": { "type": "array", "items": { "type": "string" } }, "mxCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dns": { "type": "object", "properties": { "txtHost": { "type": "string" }, "txtValue": { "type": "string" }, "mxHost": { "type": "string" }, "mxPriority": { "type": "integer" } }, "required": [ "txtHost", "txtValue", "mxHost", "mxPriority" ] } }, "required": [ "id", "domain", "status", "mxStatus", "billingSuspended", "ready", "endpointId", "endpointName", "endpointStatus", "ownershipVerifiedAt", "lastOwnershipCheckAt", "mxRecords", "mxCheckedAt", "createdAt", "updatedAt", "dns" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Set hosted address destination `PUT /api/hosted-address` Requires endpointId: a UUID in this account or null to disconnect. Provisions the address if necessary. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `domains:write`. Audience: management. ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "endpointId": { "type": [ "string", "null" ] } }, "required": [ "endpointId" ] } ``` Example: ```json { "endpointId": "11111111-1111-4111-8111-111111111111" } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } ``` ### 400 Invalid request. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Resource not found in this account. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` # Update webhook endpoint `PUT /api/webhooks/{id}` 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. Send API requests to your Wildmail application origin. The documentation host does not serve API requests. ## Authentication - apiKey: Send `Authorization: Bearer ` in the request headers. Wildmail scoped kmx_ API token. - session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies. Each bullet above is an alternative authentication method. Required API key scope: `webhooks:write`. Audience: management. ## Parameters ### id path parameter; required. ```json { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ``` ## Request body Required. Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ], "maxLength": 300 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "payloadMapping": { "anyOf": [ { "$ref": "#/components/schemas/PayloadMapping" }, { "type": "null" } ], "description": "One optional mapping per endpoint. Null uses the standard webhook body. Mapping changes apply only to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body." } }, "required": [] } ``` Example: ```json { "status": "paused" } ``` ## Responses ### 200 Success Content type: `application/json`. Schema: ```json { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/Endpoint" } }, "required": [ "endpoint" ] } ``` ### 400 Invalid request. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 401 Missing, invalid or revoked credentials. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 403 Required scope or account access missing. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 404 Resource not found in this account. Content type: `application/json`. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` ### 429 ### 503 ## Referenced schemas References resolve against the [OpenAPI specification](/openapi.json). ### #/components/schemas/PayloadMapping ```json { "type": "object", "additionalProperties": false, "description": "Version 1 copies and reshapes fields from the standard wildmail.v1 event. Root output must be an object. Missing fields become null and missing arrays become []. Unmapped fields are omitted. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body. Maximum input size 64 KiB, 500 nodes, depth 12 including root, and 128 MiB output. No scripts, constants, fetching, or type conversion. Unsafe keys and pointer segments __proto__, prototype, constructor are rejected.", "properties": { "version": { "const": 1 }, "output": { "$ref": "#/components/schemas/PayloadObjectNode" } }, "required": [ "version", "output" ], "example": { "version": 1, "output": { "type": "object", "fields": { "title": { "type": "field", "path": "/subject" }, "files": { "type": "array", "path": "/attachments", "items": { "type": "field", "path": "/filename" } } } } } } ``` ### #/components/schemas/Endpoint ```json { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "failing" ] }, "signingSecretHint": { "type": "string" }, "secretReady": { "type": "boolean" }, "subscribedEvents": { "type": "array", "items": { "type": "string" } }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "payloadMapping": { "anyOf": [ { "$ref": "#/components/schemas/PayloadMapping" }, { "type": "null" } ], "description": "Null uses the standard body. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body." } }, "required": [ "id", "name", "url", "description", "status", "signingSecretHint", "secretReady", "subscribedEvents", "lastDeliveryAt", "payloadMapping" ] } ``` ### #/components/schemas/Error ```json { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "error" ] } ``` ### #/components/schemas/PayloadObjectNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "object" }, "fields": { "type": "object", "propertyNames": { "minLength": 1, "maxLength": 128, "not": { "enum": [ "__proto__", "prototype", "constructor" ] } }, "additionalProperties": { "$ref": "#/components/schemas/PayloadMappingNode" } } }, "required": [ "type", "fields" ] } ``` ### #/components/schemas/PayloadMappingNode ```json { "oneOf": [ { "$ref": "#/components/schemas/PayloadFieldNode" }, { "$ref": "#/components/schemas/PayloadObjectNode" }, { "$ref": "#/components/schemas/PayloadArrayNode" } ] } ``` ### #/components/schemas/PayloadFieldNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "field" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." } }, "required": [ "type", "path" ] } ``` ### #/components/schemas/PayloadArrayNode ```json { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "array" }, "path": { "type": "string", "maxLength": 1024, "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported." }, "items": { "$ref": "#/components/schemas/PayloadMappingNode" } }, "required": [ "type", "path", "items" ] } ``` # Threads Browse retained conversations and their chronological messages. [Download the OpenAPI specification](/openapi.json). ## Operations - [Inspect a retained thread](/docs/api/generated/get-api-threads-id.md) - [List retained threads](/docs/api/generated/get-api-threads.md) # Usage Inspect account plan, monthly message allowance, mailbox quota, and retention. [Download the OpenAPI specification](/openapi.json). ## Operations - [Get account usage](/docs/api/generated/get-api-usage.md) # Webhook endpoints Manage endpoint destinations, signing secrets and test events. [Download the OpenAPI specification](/openapi.json). ## Operations - [Delete webhook endpoint](/docs/api/generated/delete-api-webhooks-id.md) - [Inspect webhook endpoint](/docs/api/generated/get-api-webhooks-id.md) - [List webhook endpoints](/docs/api/generated/get-api-webhooks.md) - [Preview a draft webhook payload mapping](/docs/api/generated/post-api-webhooks-id-preview.md) - [Queue a test webhook](/docs/api/generated/post-api-webhooks-id-test.md) - [Rotate webhook signing secret](/docs/api/generated/post-api-webhooks-id.md) - [Create webhook endpoint](/docs/api/generated/post-api-webhooks.md) - [Update webhook endpoint](/docs/api/generated/put-api-webhooks-id.md) # Wildmail API 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. [Download the OpenAPI specification](/openapi.json). # 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.