# 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).
