Authentication

All Dispatch developer API requests are authenticated with an API key.

Sending a request

Include your key in the Authorization header:

curl -H "Authorization: Bearer your_api_key_here" \
  https://dispatch.techtranslab.com/api/v1/emails

Obtaining an API key

Log into the Dispatch dashboard → API Keys → Create. On creation you configure:

Field	Description
Name	Human-readable label for the key
Scopes	Actions the key is allowed to perform. See Scopes. Defaults to full access (*).
Domain access	all domains (default) lets the key operate on every verified domain on your account. Choosing specific domains restricts the key to the domains you select.
Expiry	Optional. Defaults to 10 years.

The secret key value is shown only once at creation time. Store it somewhere secure. You can edit a key's scopes, domain allowlist, and active flag later from the dashboard, but the secret itself is not rotatable — delete and create a new key to rotate.

Scopes

Each API key carries a list of action scopes. A request that needs a scope the key does not have returns 403 INSUFFICIENT_SCOPE.

Scope	Allows
*	Full access (default when no scopes are chosen)
email:send	POST /emails, POST /emails/batch, POST /campaigns, cancelling a scheduled email
email:read	GET /messages, GET /messages/:id, GET /messages/:id/events, GET /messages/stats
domain:read	GET /domains

Domain allowlist

Keys configured with specific domains (all_domains = false) are limited to the domains you selected. Calls outside that allowlist are rejected:

Endpoint	Behavior for a scoped key
POST /emails, /emails/batch, /campaigns	The request's from address must resolve to an allowlisted domain, otherwise 403 DOMAIN_NOT_ALLOWED. A from is always required for scoped keys.
POST /messages/:id/cancel	403 DOMAIN_NOT_ALLOWED if the target message's domain is not allowlisted (including legacy messages with no recorded domain).
GET /messages, /messages/stats	Returns only rows whose domain_id is allowlisted.
GET /domains	Returns only allowlisted domains.

Keys with all_domains = true are not affected by the allowlist.