Authentication
Authenticate requests with an API key or an OAuth access token.
Every request to /v1 must include a Bearer token in the Authorization
header. SendMailOS accepts two kinds.
API keys
Best for your own server-to-server calls. Created in the dashboard, they carry a fixed set of scopes.
curl https://api.sendmailos.com/v1/emails \
-H "Authorization: Bearer sk_live_your_key"| Prefix | Mode | Behaviour |
|---|---|---|
sk_live_… | Live | Sends real email, counts against quota. |
TEST_KEY_… | Test | Issued from the dashboard for development. |
A key's full value is shown only once, at creation. Store it in a secret manager — never in client-side code or version control.
OAuth access tokens
Best when you act on another user's behalf (a "Connect with SendMailOS"
integration). Tokens are prefixed oat_…, scoped to the grant the user
approved, and obtained through the OAuth flow
(/oauth/authorize →
/oauth/token).
curl https://api.sendmailos.com/v1/emails \
-H "Authorization: Bearer oat_user_access_token"Scopes
Both key types are constrained by scopes such as emails:write,
emails:read, domains:write, webhooks:write, and analytics:read. A request
whose token lacks the required scope returns 403 with
error.code = "forbidden". An API key can never grant itself scopes the
creator doesn't already hold.
Errors
A missing or invalid token returns 401:
{
"request_id": "req_...",
"error": { "code": "unauthorized", "message": "Invalid API key.", "retryable": false }
}