Mail · Getting started
Authentication
Every request carries an API key. The key says which plan the request is for, so keep it as safe as a password.
API keys
You create and revoke API keys in your account, on your Email API plan. Keys start with mb_live_.
- A key is shown once, when you create it. Copy it then. If you lose it, revoke it and create a new one.
- Your plan sets how many keys you can have (see Plans and limits).
- Every key can use every endpoint. There are no read-only keys.
- A key belongs to one Email API plan. Everything you do with it (domains, emails, webhooks and the suppression list) belongs to that plan. If you have more than one Email API plan, each has its own keys.
- Revoking a key takes effect immediately. Requests with it fail from then on.
- Every key starting with
mb_live_sends real email. For development there are test keys, which never send.
Sending the key
Send the key as a bearer token in the Authorization header of every request:
Authorization: Bearer mb_live_...For example, to list your sending domains:
curl https://services.my-beast.com/mail/api/email/v1/domains \
-H "Authorization: Bearer $MYBEAST_API_KEY"The API only works over HTTPS, at https://services.my-beast.com/mail/api/email/v1. Never send a key over plain HTTP.
Test keys
A test inbox is a mailbox inside the Email API dashboard that nothing leaves. Each has its own key, starting with mb_test_, shown once when the inbox is made. Use it in development exactly as you would a live key:
export MYBEAST_API_KEY="mb_test_..."- The same request, the same checks.
POST /emailsis validated exactly as with a live key, so a422you get in development is the one production would give. Then the email is kept in the test inbox instead of being sent. - Nothing is needed and nothing is spent. Any
fromis accepted (no verified domain), nothing leaves, nothing counts towards your monthly allowance, and no webhook is sent. - Reading back works. Retrieve an email and List emails answer from the inbox, in the same shape, with simulated statuses and events: a recipient is
sentand thendelivered. - Only emails. Domains, webhooks and suppressions take a live key: with a test key they return
403 test_key. - The inbox shows the email as a phone, a tablet or a desktop client would, with its text, headers and raw source, and says what the live API would have answered the same request.
To exercise your handling of the other statuses, send to one of these recipients:
| Send to | Meaning |
|---|---|
delivered@sandbox.my-beast.com | Delivered, as any other address is. |
bounced@sandbox.my-beast.com | Bounces for good: the recipient becomes bounced, with a 550 reply in the event's message. |
complained@sandbox.my-beast.com | Delivered, then marked as spam: the recipient becomes complained. |
suppressed@sandbox.my-beast.com | Skipped as if on your suppression list: a failed event with reason suppressed. |
Each takes a +label after the word, such as bounced+order-42@sandbox.my-beast.com, to tell test cases apart. Every other address is delivered.
Errors
A problem with the key returns one of these errors. The format of error responses is described in Errors and limits.
| Status | Type | What it means |
|---|---|---|
| 401 | missing_api_key | There's no Authorization: Bearer header with an API key. |
| 401 | invalid_api_key | The API key doesn't exist or has been revoked. |
| 403 | plan_inactive | The Email API plan the key belongs to isn't active, for example because it has ended. |
| 403 | test_key | The key is a test inbox's (mb_test_…). A test key sends to its inbox and reads what it sent; domains, webhooks and suppressions take a live key. See Test keys. |
Keeping keys safe
- Keep keys on your server, in environment variables or a secret manager. Don't commit them to version control.
- Never use a key in code that runs in a browser or a mobile app: anyone can read it there. Send email from your server instead.
- Use a separate key for each app or environment, so you can revoke one without touching the others.
- To replace a key, create a new one, deploy it, then revoke the old one. Nothing stops working in between.
If a key leaks