Every request to the email API (/api/v2) is authenticated with an API key in the Authorization header:
Authorization: Bearer rb_live_xxxxxxxxxxxxxxxx
Create and revoke keys in the app under Developers › API keys, or with the API keys endpoints.
Key types
| Setting | Values | What it means |
|---|---|---|
| Mode | live, test | Test keys (rb_test_…) never deliver email: the outcome is simulated. Live keys (rb_live_…) send for real. |
| Permission | sending, full | Sending keys can only call POST /emails and POST /emails/batch. Full keys can also read the email log, list domains and manage keys. |
| Domain | any, or one domain | A key limited to a domain can only send from addresses at that domain. |
Use the smallest permission that works. A web server that only sends receipts needs a sending key limited to your domain.
Keeping keys safe
- A key is shown once, when it is created. Store it in an environment variable or a secrets manager, never in your code repository.
- Never send a key to a browser or mobile app. Call the API from your server.
- Revoke a key straight away if it may have leaked, then create a new one.
Authentication errors
| Status | name | Cause |
|---|---|---|
| 401 | missing_api_key | No Authorization: Bearer header. |
| 403 | invalid_api_key | The key is wrong, revoked, or its account is disabled. |
| 403 | restricted_api_key | A sending key called a full-access endpoint, API access is not in your plan, or the key is limited to another domain. |
See Errors for the full list.