Authentication
The API authenticates with a bearer API key. Keys are scoped, shown once, and stored only as a hash.
Bearer keys
Every request to the sending API carries an Authorization: Bearer header with an API key. Keys begin with am_live_ and are created in the dashboard under Settings → API keys.
curl https://api.mail.atrix.dev/v1/emails/<id> \ -H "Authorization: Bearer am_live_xxxxxxxxxxxxxxxxxxxxxxxx"
The full key is returned once, at creation. Only a SHA-256 hash and the short prefix are stored — we cannot show it again, so save it immediately. Lost a key? Revoke it and create a new one.
401 unauthorized.Scopes
Each key is granted one or more scopes. A request needs the scope for the operation it performs, or it is rejected with 403 forbidden.
| Scope | Grants |
|---|---|
| email.send | Send, cancel, and reschedule email. |
| emails.read | Look up a sent email and its delivery events. |
| domains.read | List domains and read their DNS records. |
| domains.write | Add, update, verify, and delete domains. |
| audiences.read | List audiences and their contacts. |
| audiences.write | Create audiences; add, import, and delete contacts. |
| broadcasts.read | List broadcasts and read their counters. |
| broadcasts.send | Create, send, and delete broadcasts. |
| templates.read | List and read templates. |
| templates.write | Create, update, and delete templates. |
| analytics.read | Read deliverability stats and the activity log. |
| mailboxes.read | List mailboxes, aliases, and connection settings. |
| mailboxes.write | Create, update, and delete mailboxes and aliases. |
| webhooks.read | List endpoints and their delivery attempts. |
| webhooks.write | Register, test, disable, and delete endpoints. |
| * | All scopes. Only organization admins/owners may create a * key. |
emails.send is accepted as an alias of email.send. Grant the narrowest set a key needs — a key that only sends should not carry emails.read, and a reporting integration wants analytics.read alone.
What API keys can access
Everything under /v1 is key-authenticated:
| Path | Scope |
|---|---|
| /v1/emails | email.send / emails.read |
| /v1/domains | domains.read / domains.write |
| /v1/audiences | audiences.read / audiences.write |
| /v1/broadcasts | broadcasts.read / broadcasts.send |
| /v1/templates | templates.read / templates.write |
| /v1/mailboxes | mailboxes.read / mailboxes.write |
| /v1/aliases | mailboxes.read / mailboxes.write |
| /v1/webhooks | webhooks.read / webhooks.write |
| /v1/analytics/deliverability | analytics.read |
| /v1/activity | analytics.read |
API-key management, and changing an existing mailbox's password, remain dashboard-only (session-authenticated) — a key must never be able to mint another key or take over a mailbox. The TypeScript SDK and the MCP server both cover the whole key-authenticated surface.
Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing Authorization header, or an invalid/revoked key. |
| 403 | forbidden | The key is valid but lacks the required scope. |
| 403 | org_suspended | The organization is suspended from sending. |
| 429 | rate_limited | Over the per-key platform limit (60 writes / 600 reads per minute) or the plan's send budget. Carries Retry-After. |