Getting started

Authentication

Authenticate with a bearer API key, choose between full access and sending access, and restrict a key to one domain.

Every request to https://api.sooner.dev carries an API key in the Authorization header. There is no other authentication method for the API.

Shell

curl https://api.sooner.dev/domains \
  -H "Authorization: Bearer sn_..."

API keys

A key starts with sn_ followed by 40 characters.
A key belongs to one project. It can only see and change that project's resources: domains, templates, contacts, broadcasts, webhooks and email logs. Quota, the rate limit and the suppression list belong to the team.
Sooner stores only a hash of the key. The full key is shown once, when you create it. The dashboard keeps a short prefix and a last-used time so you can recognize it.
Create keys in the dashboard under API keys, or with POST /api-keys. A key name is 1 to 50 characters.

Permissions

Permission	What it can do
`full_access`	Every endpoint. This is the default when you create a key through the API.
`sending_access`	Only `POST /emails` and `POST /emails/batch`. Every other endpoint returns `401 restricted_api_key`.

Use sending_access keys in application code that only sends email. If one leaks, it cannot read your logs, contacts or domains.

Each endpoint page in the API reference states the permission it needs.

Restrict a key to one domain

A key can be locked to a single verified domain in its project by passing domain_id when you create it, or by choosing the domain in the dashboard. A locked key can only send from addresses on that domain. A send from any other domain returns 401 restricted_api_key.

Shell

curl -X POST https://api.sooner.dev/api-keys \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "marketing-site",
    "permission": "sending_access",
    "domain_id": "jh7b2k4d9x1m5q8r3t6v0w2y"
  }'

JSON

{ "id": "jk3p8m2x7c4v9n1b6q5w0e2r", "token": "sn_..." }

Revoking keys

Revoke a key in the dashboard, or with DELETE /api-keys/{id}. Revoked keys stop working. Most endpoints reject the key immediately. On /emails and /suppressions, a revocation can take up to about 30 seconds to apply.

Archiving a project or deleting a team also stops its keys.

Authentication errors

Situation	Status	Error name
No `Authorization: Bearer` header	401	`missing_api_key`
Key does not start with `sn_`, is unknown, or is revoked	403	`invalid_api_key`
A `sending_access` key calls a full-access endpoint, or a domain-locked key sends from another domain	401	`restricted_api_key`
The team is suspended	451	`security_error`
Too many requests for the plan	429	`rate_limit_exceeded`

JSON

{
  "statusCode": 401,
  "message": "Missing API key in the authorization header.",
  "name": "missing_api_key"
}

Keep keys safe

Keep keys in environment variables or a secrets manager, never in client-side code or a public repository.
Create one key per service or environment so you can revoke one without touching the others.
If a key is exposed, create a replacement, deploy it, then revoke the old key.

The dashboard itself is separate from the API. You sign in to the dashboard with GitHub or Google.