Skip to main content

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 for request and response schemas. Browser authentication is documented in Authentication.

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.

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.

MethodPathAuthentication
GET/api/accountBrowser session
PUT/api/accountBrowser session
POST/api/account/deleteBrowser session
GET/api/domainsdomains:read
POST/api/domainsdomains:write
PUT/api/domains/{id}domains:write
DELETE/api/domains/{id}domains:admin
POST/api/domains/{id}/verifydomains:write
GET/api/domains/{id}/routesdomains:read
POST/api/domains/{id}/routesdomains:write
PUT/api/domains/{id}/routes/{routeId}domains:write
DELETE/api/domains/{id}/routes/{routeId}domains:write
GET/api/hosted-addressdomains:read
PUT/api/hosted-addressdomains:write
GET/api/webhookswebhooks:read
POST/api/webhookswebhooks: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}/testwebhooks:write
POST/api/webhooks/{id}/previewwebhooks:read
GET/api/deliveriesdeliveries:read
GET/api/deliveries/{id}deliveries:read
POST/api/deliveries/{id}/replaydeliveries:replay
GET/api/messagesmessages:read
GET/api/threadsmessages:read
GET/api/threads/{id}messages:read
GET/api/messages/{id}messages:read
GET/api/messages/{id}/rawmessages:read
GET/api/messages/{id}/previewmessages:read
GET/api/messages/{id}/attachments/{attachmentId}messages:read
GET/api/usageusage:read
GET/api/keysBrowser session
POST/api/keysBrowser session
DELETE/api/keys/{id}Browser session
GET/api/billingBrowser session
POST/api/billing/checkoutBrowser session
POST/api/billing/upgradeBrowser session
POST/api/billing/portalBrowser session
POST/api/billing/syncBrowser 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 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.

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.

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.