Authentication
API keys, scopes, version headers and test mode.
Send Authorization: Bearer st_live_… on authenticated requests. Live keys begin with st_live_; test keys begin with st_test_. The mode is determined by the key, rather than a request-body setting.
| Scope | Allowed operations |
|---|---|
full | Authenticated API operations except identity endpoints, which require a dashboard token |
sending | Only POST /emails and POST /emails/batch |
read_only | Only GET /usage |
Create accepts full, sending or read_only. A stored key may also report domain. That value cannot be created. The server allows domain the same two send routes as sending.
API key management requires a full-scope key. A test key can create only test keys. The secret is returned only when the key is created; save it on your server. Revoke a key when it is no longer needed. Key creation does not support Idempotency-Key; retrying creates another key.
API version
Include API-Version: 2026-10-01 in send requests. OpenAPI declares this header optional on the single and batch send operations. The current server does not implement a router for multiple date versions.
Test mode
Test mode never delivers a real email. The worker uses a discard sender for test jobs. Suppression checks and per-tenant send admission still apply. A test key may send from any domain the tenant has added that is not deleted, including pending and failed. A live key needs that domain verified. Test keys share a cap of 1 000 recipients per UTC day and do not consume live plan caps. Scope is chosen when the key is created and cannot be edited; revoke the key and create another.
Sources: authentication and scope checks (internal/api/auth.go), key creation (internal/api/api_keys.go), send validation (internal/api/emails.go), discard sender (internal/ses/discard.go), worker (internal/worker/worker.go), API version parameter (openapi/openapi.yaml).