API reference
The complete surface area. Sending uses an API key; the management API uses a session token. All requests are JSON over HTTPS.
Base URL
text
https://api.mailkite.dev
Check service health any time with
GET /api/health → { ok: true }.
Endpoints
Sending · auth: API key
| POST | /v1/send | Send a message. Returns 202 with { id, status }. |
Domains · auth: Session token
| GET | /api/domains | List your domains, each with its webhook URL. |
| POST | /api/domains | Add a domain. Returns the domain + DNS records. |
| GET | /api/domains/:id | Get one domain with DNS records + webhook. |
| DELETE | /api/domains/:id | Remove a domain. |
| POST | /api/domains/:id/verify | Check DNS and update status. |
| PUT | /api/domains/:id/webhook | Set/replace the domain's catch-all webhook. |
| DELETE | /api/domains/:id/webhook | Remove the domain's webhook. |
| POST | /api/domains/:id/webhook/test | Send a signed test event. |
Routes · auth: Session token
| GET | /api/routes | List inbound routing rules. |
| POST | /api/routes | Create a route (match, action, destination). |
Messages · auth: Session token
| GET | /api/messages | List stored messages. |
| GET | /api/messages/:id | Get a message with deliveries + attachments. |
Deliveries · auth: Session token
| POST | /api/deliveries/:id/retry | Re-deliver a stored message to its webhook. |
Auth · auth: Public
| POST | /api/auth/signup | Create an account. Returns a token. |
| POST | /api/auth/login | Log in with email + password. |
| POST | /api/auth/google | Sign in with a Google auth code. |
Attachments
Inbound attachments are served from signed, time-limited URLs returned in the webhook and Messages API — no credential needed to fetch them:
http
GET /att/:mid/:idx?exp=…&sig=…
Links are valid for 7 days, then the object is deleted. An expired link
returns 410; a tampered one returns 403.
Errors
Errors use standard HTTP status codes with a JSON body:
error
{ "error": "a valid https url is required" }| Status | Meaning | When |
|---|---|---|
400 | Bad Request | A required field is missing or malformed. |
401 | Unauthorized | Missing or invalid credential. |
403 | Forbidden | Authenticated, but no access to the resource. |
404 | Not Found | Unknown route, or a resource you don't own. |
409 | Conflict | Already exists, or a required precondition isn't met. |
410 | Gone | An expired signed link (e.g. an attachment URL). |
502 | Bad Gateway | An upstream send/delivery failed. |
Conventions
- IDs are prefixed by type:
dom_,rte_,msg_,dlv_,usr_. - Timestamps are Unix epoch milliseconds.
- Webhook signatures use the
x-mailkite-signatureheader — see Verifying signatures. - Requests must be HTTPS (localhost over HTTP is allowed only for webhook testing).
New here? Start with the Quickstart.