MailwurfHTTP API
Plain HTTP under /api/v1. The TypeScript client is optional.
Every mailbox call except health needs your project API key:
Authorization: Bearer mw_live_…or header X-Api-Key: mw_live_…. Inboxes and messages that do not belong to the key return 404. JSON errors look like {"error":"…"}.
Call the API at your Mailwurf origin, for example https://api.mailwurf.io. /v1 is an alias of /api/v1. /health is an alias of /api/v1/health. /llm and /llms.txt return this contract as Markdown and do not require a key.
The same contract is published as OpenAPI: browse the API Reference or download openapi.yaml.
Endpoints
| Method | Path | Auth | Success | Notes |
|---|---|---|---|---|
| GET | /llm | no | 200 markdown | machine-readable guide |
| GET | /llms.txt | no | 200 markdown | same as /llm |
| GET | /api/v1/health | no | 200 | {"status":"ok"} |
| POST | /api/v1/inboxes | yes | 201 | empty body; custom address is rejected |
| GET | /api/v1/inboxes?address= | yes | 200 | lookup by address; address required |
| GET | /api/v1/inboxes/{id} | yes | 200 | 404 if the inbox is not yours |
| DELETE | /api/v1/inboxes/{id} | yes | 204 | temporary inboxes only |
| GET | /api/v1/inboxes/{id}/messages | yes | 200 | newest first; query subject, after |
| POST | /api/v1/inboxes/{id}/messages | yes | 202 | send from this inbox; to, subject, text |
| GET | /api/v1/inboxes/{id}/messages/wait | yes | 200 | server-side wait |
| GET | /api/v1/messages/{id} | yes | 200 | one message |
Status: 400 bad JSON / missing query / invalid after / bad send body, 401 missing or wrong API key, 403 permanent inbox cannot be deleted here, 404 unknown inbox, message, or local send recipient, 408 wait timeout, 429 too many concurrent waits or sends, 500 server error.
Wait
GET /api/v1/inboxes/{id}/messages/wait
Keep one request open. Do not poll from the client.
| Query | Meaning |
|---|---|
timeout | milliseconds. Default 15000. Max 120000. 0 = one lookup. Invalid → default |
subject | case-insensitive substring of Subject |
after | message id; only later messages |
Matching is oldest-first. If a match is already stored, it returns immediately. At most four waits may run at once per API key.
timeout=0 and no match → 404. Positive timeout and no match → 408. Too many concurrent waits → 429.
Examples
Create an inbox:
curl -s -X POST https://api.mailwurf.io/v1/inboxes \
-H "Authorization: Bearer $MAILWURF_API_KEY"Wait up to 15s for a subject containing Confirm:
curl -s "https://api.mailwurf.io/v1/inboxes/{id}/messages/wait?timeout=15000&subject=Confirm" \
-H "Authorization: Bearer $MAILWURF_API_KEY"Then use links[0] or otp from the body.
Send from an inbox to another Mailwurf address (or the internet):
curl -s -X POST https://api.mailwurf.io/v1/inboxes/{id}/messages \
-H "Authorization: Bearer $MAILWURF_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":"other@mailwurf.io","subject":"Hello","text":"ping"}'