Authentication

The Smail API supports two authentication methods depending on the operation.

API key authentication

Use an API key for send operations (/api/v1/emails, /api/v1/emails/batch). Pass the key in the X-API-Key header:

curl https://api.smail.dev/api/v1/emails \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"from":"you@yourdomain.com","to":["user@example.com"],"subject":"Hello","text":"Hi there"}'

API keys are prefixed with sk_live_. Create them with POST /api/v1/keys.

JWT authentication

Use a JWT for management operations (creating API keys, managing domains). Obtain a token by logging in with POST /api/v1/auth/login, then pass it as a Bearer token:

curl https://api.smail.dev/api/v1/keys \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Production"}'

Which method to use

Error responses

If authentication fails, the API returns 401 Unauthorized:

{ "error": "unauthorized" }

If the authenticated account lacks permission, the API returns 403 Forbidden:

{ "error": "forbidden" }