Authentication

All API requests require a Bearer token in the Authorization header.

API keys

Create API keys from your dashboard under Settings > API Keys. Keys use the format sm_live_... and are shown only once at creation. Store them securely.

Each key can have an optional expiration date. You can revoke a key at any time from the dashboard.

Making requests

Pass your API key as a Bearer token:

curl https://shipmail.to/api/v1/domains \
  -H "Authorization: Bearer sm_live_..."}

Scopes

Each API key has scopes that control which endpoints it can call. For example, listing domains requires the domains:read scope. A key with * (wildcard) has access to all endpoints.

Error response

Requests with a missing or invalid token receive a 401 response with a WWW-Authenticate header:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid or missing API key.",
    "request_id": "req_abc123"
  }
}

Scope reference

Every API key is assigned one or more scopes that determine which endpoints it can access.

Scope	Permits
domains:read	List domains, get domain, verify domain
domains:write	Create, update, delete domains
mailboxes:read	List mailboxes, get mailbox
mailboxes:write	Create, update, delete mailboxes
messages:read	Get messages
messages:write	Send messages
threads:read	List threads, get thread messages
webhooks:read	List webhooks, get webhook, list deliveries
webhooks:write	Create, update, delete webhooks, rotate secret, test webhook