Authentication

Access tokens

Every request to /api/v1 needs an access token in the X-API-KEY header:

curl "$EE_URL/api/v1/accounts" -H "X-API-KEY: $EE_KEY"

Generate tokens in your dashboard under API keys, or with the API keys endpoints. A token is shown once: the engine only stores its SHA-256 hash.
Revoke a token in the same place. It stops working at once.
Give each app or environment its own token, so you can revoke one without affecting the others.
Tokens go in the header only. A token in the query string is ignored.

A missing, wrong or revoked token gets:

401 Unauthorized

{ "status": 401, "type": "errors/unauthorized", "title": "Unauthorized", "detail": "missing or invalid API key" }

DSN

Your DSN is your workspace’s API address, shown on your dashboard, for example https://mail-api.example.com. All API paths start with /api/v1:

https://mail-api.example.com/api/v1/emails

API keys

You can also manage access tokens through the API. Each key has a pk_… id.

Create a key

curl -X POST "$EE_URL/api/v1/api-keys" \
  -H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Production" }'

string

required

Your name for the key, up to 100 characters.

Response

{
  "object": "ApiKey",
  "id": "pk_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "name": "Production",
  "prefix": "ee_Zq3Rk",
  "role": "service",
  "issued_at": "2026-10-07T08:00:00Z",
  "last_used_at": null,
  "key": "ee_Zq3Rk8Tn2Vb6Xy1Lm4Pw7Hs9Jd5Fg0aB"
}

key is the access token. It’s in this response only, so store it safely.

List and revoke keys

Request	What it does
`GET /api/v1/api-keys`	Your keys, without the tokens themselves. Paged with `offset` and `limit` (see Pagination)
`DELETE /api/v1/api-keys/{pk_id}`	Revokes the key at once. Returns `{ "object": "ApiKeyDeleted", "id": "pk_…" }`

curl -X DELETE "$EE_URL/api/v1/api-keys/pk_0f1e2d3c4b5a69788796a5b4c3d2e1f0" -H "X-API-KEY: $EE_KEY"

Each key in the list has these fields:

Field
`id`	The key’s `pk_…` id
`name`	Your name for it
`prefix`	The first characters of the token, so you can recognise it
`role`	Always `service`
`issued_at`	When it was created
`last_used_at`	When it was last used, or `null`

Public endpoints

A few paths are reached by your users’ browsers, so they don’t take an access token. Each is protected in its own way:

Path	Used by	Protected by
`/t/{id}/o.gif`, `/t/{id}/c`	Open and click tracking	Link signatures (no open redirect)
`/up`	Health checks	Nothing sensitive (returns `ok`)

Keep access tokens on your server. Never put them in a browser or mobile app: anyone with a token can read every connected mailbox.

Getting started

Accounts

Emails

Webhooks

Reference

Access tokens

DSN

API keys

Create a key

List and revoke keys

Public endpoints

​Access tokens

​DSN

​API keys

​Create a key

​List and revoke keys

​Public endpoints

Access tokens

DSN

API keys

Create a key

List and revoke keys

Public endpoints