Email overview
Bird Email is a complete sending platform: transactional and marketing email through one API, backed by Bird's managed delivery infrastructure. You call Bird's API with a bk_{region}_… key against your regional host (https://us1.platform.bird.com or https://eu1.platform.bird.com); Bird handles SMTP delivery, DKIM signing, IP reputation, and everything else between your request and the recipient's inbox.
If you just want to send something, start with the quickstart. This page is the conceptual map of the rest of the section.
How sending works
You send email with POST /v1/email/messages. The API validates your request, checks your sending domain and suppression list, and returns 202 Accepted with a message ID — delivery happens asynchronously from there. A 202 means Bird has durably accepted your send and is working on it; the actual delivery outcome (delivered, bounced, deferred, complained) arrives afterwards, per recipient, through events and webhooks and the message read endpoints. Full request and response shapes live in the API reference.
Two ideas shape the whole API:
- A send is not a delivery. One message can have many recipients, and each recipient has its own lifecycle. The message-level status you see in list and read endpoints is an aggregate over recipient states.
- Why you send matters. Every message belongs to a category — transactional or marketing — which determines how suppressions apply. Password resets must reach people who unsubscribed from your newsletter; categories are how Bird knows the difference.
Reserved fields in v1
The v1 send API reserves attachments, scheduled_at, and template for a future release. Including any of them returns 422 unsupported_feature today. They are named now so your integration and Bird's vocabulary converge on the same field names when they ship.
Sending domains and authentication
Before you can send from your own address, you verify ownership of the domain via DNS. Sending domains covers registration and verification; DKIM, SPF, and DMARC explains the authentication records themselves — what each one proves to receiving mailbox providers and how Bird generates them for you. Once DMARC is in place, BIMI lets you display your logo next to your messages in supporting inboxes.
Reputation and deliverability
Deliverability is mostly reputation management, and Bird handles the heavy lifting:
- Suppressions — hard bounces, spam complaints, and unsubscribes automatically add recipients to your workspace suppression list, so you never repeatedly mail addresses that damage your reputation. You can also manage the list yourself via the API.
- Dedicated IPs and pools — high-volume senders can isolate their reputation on their own IP addresses instead of shared infrastructure, and route different traffic through different pools.
- IP warmup — new dedicated IPs need gradually increasing volume before mailbox providers trust them; this page explains the warmup process.
Visibility
Every message produces a per-recipient event timeline — accepted, processed, delivered, bounced, opened, clicked, and more:
- Tracking and metrics — open and click tracking (on by default, per-message switchable) and the aggregate delivery, bounce, and engagement metrics derived from your traffic.
- Events — the event vocabulary, recipient lifecycle, and webhook delivery to your own endpoints.
Testing without sending
The mail sandbox lets you exercise your whole integration without delivering to a real inbox. Sending to magic addresses at messagebird.dev — delivered@, bounce@, softbounce@, complaint@, suppressed@, reject@, deferred@ — deterministically produces that outcome and drives the real webhook pipeline, so the events and payloads your handlers receive are exactly what production sends. Simulated bounces and complaints do not write to your suppression list, so the same address is reusable across test runs.
Where to go next
| Page | What it covers |
|---|---|
| Send your first email | Quickstart: API key to delivered message |
| Sending email | The send API in depth — recipients, content, tags, metadata |
| Sending domains | Registering and verifying the domains you send from |
| DKIM, SPF, and DMARC | Email authentication records |
| Categories | Transactional vs marketing and suppression policy |
| Suppressions | The suppression list and how it protects your reputation |
| Dedicated IPs and pools | Isolating and routing your sending reputation |
| IP warmup | Building trust on new dedicated IPs |
| Tracking and metrics | Opens, clicks, and aggregate stats |
| Events | Event types and webhooks |
| Testing sandbox | Simulated delivery outcomes via magic addresses |
| BIMI | Brand logos in the inbox |
| API reference: messages | Endpoint, schema, and error details |