Authentication
Authenticate requests with an API key or an OAuth access token.
Most /v1 resource requests require a Bearer token in the Authorization
header. The public health endpoints, OAuth token exchange, and agent pairing
use different authentication rules. SendMailOS accepts two Bearer credential
types for its resource API.
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; email sends are simulated and do not deliver to real mailboxes. |
Test keys can read resources, but their writes are limited to
POST /v1/emails, /v1/emails/batch, and /v1/emails/bulk. Domain-restricted
keys can send from their authorized domain and access only a small set of
domain/WordPress integration routes; they cannot read organization-wide lists.
For either kind of key, a route also requires its normal scope and plan access.
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.
Browser requests to /v1 support CORS preflight with Authorization,
Content-Type, and Idempotency-Key headers. This enables the API explorer
and OAuth browser clients; it does not make a live API key safe to embed in a
public web page. Use a server-side key or a user-approved OAuth token for
production integrations. A key's configured origin restriction is checked
on the authenticated request.
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 browser consent and token exchange flow
(/oauth/authorize →
/oauth/token).
The consent page is hosted at https://dash.sendmailos.com/oauth/authorize;
exchange the resulting code at https://api.sendmailos.com/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 scopes that its caller
key does not already hold. Managing API keys requires an unrestricted
live API key; OAuth, test, and domain-restricted credentials cannot manage them.
Some endpoints require an API key (/v1/dkim/key), while
GET /v1/oauth/organizations requires an OAuth token. An OAuth token with
approval for multiple organizations must select an approved organization using
X-Organization-ID on data requests.
Errors
A missing or invalid token returns 401:
{
"request_id": "req_...",
"error": { "code": "unauthorized", "message": "Invalid API key.", "retryable": false }
}An expired API key, missing scope, inactive organization, restricted credential
on an unsupported route, or a plan without API access returns 403 with
error.code = "forbidden". Inspect error.message for the reason; do not infer
the reason from the status code alone. See
Responses and errors for retry guidance.