Email overview
We send transactional and marketing email through one API. You call POST /v1/email/messages with a bk_{region}_... key against your regional host (https://us1.platform.bird.com or https://eu1.platform.bird.com), and we sign the message with DKIM, deliver it, and report back what the recipient's mail server did with it.
To send something before reading further, the quickstart takes you from an API key to a delivered message. This page covers the model the rest of this section assumes, and points at the guide for each part of it.
How sending works
A send is accepted in one call and delivered afterwards. POST /v1/email/messages checks your payload and your sending domain, then returns 202 Accepted with an em_ message ID. The delivery outcome arrives separately, per recipient, through webhook events and the message read endpoints. Sending email has the payload, the limits on each field, and the full response contract.
Two consequences of that model shape the rest of this section.
One message, many recipients, one lifecycle each. A message to five addresses produces five independent outcomes, and the message-level status you read back is an aggregate over them. Suppression is evaluated the same way: one suppressed address comes back rejected while the other four deliver.
Every message declares why you are sending it. A category of transactional or marketing decides which suppressions apply to it. Someone who unsubscribed from your newsletter still needs their password reset to arrive, and the category is what tells us the difference.
A send can also arrive by another route, or leave later. SMTP accepts submissions from anything that speaks the protocol, and scheduled sending holds a message until a time you set.
The Email section of the dashboard
Email is one of the channels in the dashboard sidebar. Its pages, in the order they appear:
| Page | What it holds |
|---|---|
| Onboarding | A three-step checklist: create an API key, send an email, add your domain. It shows until you have finished it |
| Metrics | Delivery, open, bounce, and complaint rates over time; see Email metrics |
| Emails | Every message sent; see the email log. Its Receiving tab lists what came in |
| Mailboxes | Programmable inboxes your code reads and replies from; see Agent mailboxes |
| Templates | Reusable subject and body content, with a draft and published versions; see Email templates |
| Domains | Your sending domains, their DNS records, and live verification status; see Sending domains |
| IP Pools | Dedicated IPs and the pools they sit in; see Dedicated IPs and pools |
| Broadcasts | One email to a stored audience, with delivery tracked per recipient; see Broadcasts |
| Suppressions | Addresses we will not send to, and why; see Suppressions |
| Unsubscribe page | Branding for the hosted page every marketing email links to; see Unsubscribe links |
| SMTP | Connection settings, per-key send defaults, and live connections; see SMTP |
Recipients live outside the Email section, under Contacts in the sidebar: All contacts stores people with typed custom properties (see Contacts), and Audiences groups them into the reusable lists a broadcast sends to (see Audiences).
Where each guide fits
Sending. Sending email is the one to read first: it owns the payload every other send path is a variation on. From there, templates store content you reuse, attachments add files, batch sending submits up to 100 messages in one request, and broadcasts send one email to a whole audience.
Domains and authentication. Sending domains covers registering a domain and getting it verified. DKIM, SPF, and DMARC explains what each record proves to a receiving mailbox provider, and BIMI puts your logo beside your messages in inboxes that support it.
Reputation. Suppressions is the list of addresses we stop sending to, mostly filled automatically from hard bounces, complaints, and unsubscribes. Dedicated IPs and pools and IP warmup cover sending from IP addresses only your organization uses. Email deliverability ties those together.
Knowing what happened. The email log shows one message and its per-recipient timeline. Email metrics aggregates your traffic. Events is the event vocabulary and how webhooks deliver it to your own endpoint.
Receiving. Receiving email covers both ways in: a forwarding address we generate that needs no DNS, or MX records on a subdomain you own. Agent mailboxes builds on that with inboxes your code sends from as well as reads.
Testing. The mail sandbox exercises your integration end to end without delivering anywhere: send to bounce@messagebird.dev and you get a real hard bounce through the real event and webhook pipeline, with nothing written to your suppression list.
Moving your production email over from somewhere else is its own path, and Migrate from another provider sequences it: re-map the send call, publish the DNS records, bring your suppression list over, translate the webhook vocabulary, and verify in the sandbox before you switch traffic.