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

https://api.mailkite.dev

Check service health any time with GET /api/health → { ok: true }.

Endpoints

Grouped by area — each group has its own page, and every endpoint on it expands to its request and response schema:

OpenAPI document

The whole HTTP surface in one OpenAPI 3.1.1 document: every path, parameter, request body and response, with all schemas in components.schemas. It is generated from the same contract as this reference, the SDKs and the MCP server, so it cannot drift. Download it at /api/openapi.json; the API serves the identical document at https://api.mailkite.dev/openapi.json.

# download the spec
curl https://api.mailkite.dev/openapi.json -o mailkite.openapi.json

# validate or generate a client
npx @redocly/cli lint mailkite.openapi.json
npx openapi-typescript mailkite.openapi.json -o mailkite.d.ts

Drop it into Postman, Insomnia, Bump.sh, an SDK generator or an API gateway. Because it is the canonical contract — not a hand-written copy — a schema change ships in the same deploy as the endpoint.

Machine-readable schemas

Every request and response body is described by a JSON Schema (draft-07) — the same schemas our SDKs and MCP server validate against, so they can't drift from what the API enforces. Fetch them all from GET /v1/schemas, or one at a time:

# every schema, with its URL
curl https://api.mailkite.dev/v1/schemas

# one schema — point a validator straight at it
curl https://api.mailkite.dev/v1/schemas/send-request.json
curl https://api.mailkite.dev/v1/schemas/email-received-event.json

Contract version 0.19.0. Schemas are served as application/schema+json with an absolute $id, and are additive — we add fields, we don't remove or repurpose them.

Conventions

• IDs are prefixed by type: dom_, rte_, msg_, dlv_, usr_.
• Timestamps are Unix epoch milliseconds. Where a timestamp is central — like the inbound event's receivedAt — an ISO 8601 twin sits alongside it.
• Errors use standard HTTP status codes with a JSON body — see Errors.
• Webhook signatures use the x-mailkite-signature header — see Verifying signatures.
• Requests must be HTTPS (localhost over HTTP is allowed only for webhook testing).

New here? Start with the Quickstart.