Authentication

Get an API key

Open Account → API keys and create a key. It starts with sk- and is shown only once, so store it somewhere safe, such as a secrets manager or an environment variable.

All your keys share your account's plan and limits. Creating more keys does not raise them.

Use your key

Send the key in the Authorization header:

curl "$MAILA_API_URL/v1/inboxes" \
  -H "Authorization: Bearer $MAILA_API_KEY"

Or, if your tool prefers it, in X-Api-Key:

curl "$MAILA_API_URL/v1/inboxes" \
  -H "X-Api-Key: $MAILA_API_KEY"

A missing, wrong or revoked key returns 401.

Revoke a key

Revoke a key you no longer trust. It stops working immediately. A key is identified by the SHA-256 hash of its secret, which you can compute yourself:

KEY_HASH=$(printf %s "$OLD_MAILA_API_KEY" | sha256sum | cut -d' ' -f1)

curl -X DELETE "$MAILA_API_URL/api-keys/$KEY_HASH" \
  -H "Authorization: Bearer $MAILA_API_KEY"

{ "success": true }

Authenticate with any working key on the same account. A key that is not yours, or is already revoked, returns 404. On macOS, use shasum -a 256 instead of sha256sum.