Getting started

Authentication

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

SettingValuesWhat it means
Modelive, testTest keys (rb_test_…) never deliver email: the outcome is simulated. Live keys (rb_live_…) send for real.
Permissionsending, fullSending keys can only call POST /emails and POST /emails/batch. Full keys can also read the email log, list domains and manage keys.
Domainany, or one domainA 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

StatusnameCause
401missing_api_keyNo Authorization: Bearer header.
403invalid_api_keyThe key is wrong, revoked, or its account is disabled.
403restricted_api_keyA 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.