Authentication
All API requests require a Bearer token in the Authorization header.
Last updated
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.
Choose scopes when creating each key. Each key can also 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 |
| suppressions:read | List suppressed recipient addresses |
| suppressions:write | Remove addresses from the suppression list |
| webhooks:read | List webhooks, get webhook, list deliveries |
| webhooks:write | Create, update, delete webhooks, rotate secret, test webhook |
Frequently asked questions
Where should I store my API key?
Store the key in a server-side environment variable (for example SHIPMAIL_API_KEY) and read it at runtime. Never commit it to source control and never expose it in client-side code, browser bundles, or mobile apps. Rotate the key from the dashboard if it ever leaks.
I lost my API key. Can I see it again?
No. The full key is shown only once at creation. If you lose it, revoke the old key from the dashboard and create a new one. Update every service that used the old key.
What is a scope and how do I pick the right one?
A scope restricts what a key can do. Give each key the narrowest set of scopes it actually needs. For example, a background job that only sends email should have messages:write, not the wildcard. If the key leaks, the damage is limited to what the scopes allow.
Can I use the same API key for production and staging?
It is safer to use separate keys. Create one key per environment with a descriptive name, and revoke individually if you need to. Keys are per organization, so you do not need a separate account for staging.