Audiences
Preview — Audiences, contacts, and broadcasts are part of Bird's new email platform and are still in preview, not yet generally available. These APIs aren't live yet; the model below is what's coming, and the interface may change before launch.
The send and batch endpoints take recipients you enumerate on every request. Audiences flip that around: you store recipients with Bird once, group them into lists, and address a whole list by reference. It's the model behind newsletters and campaigns, where the recipient set lives in the platform rather than in your code.
There are four pieces.
Contacts
A contact is a stored recipient — an email address plus whatever you know about them. Beyond the address, a contact carries custom fields you define (see contact properties below): first name, plan tier, signup date, anything you'd personalize or segment on. You manage contacts individually or upsert them in bulk, so syncing from your own database is one call per batch rather than per person.
Contact properties
Contact properties are the schema for those custom fields, defined once per workspace. Registering a property (first_name as text, signup_date as a date, and so on) means every contact shares a known, typed shape — which is what lets you segment and personalize reliably instead of stuffing untyped blobs onto each contact.
Audiences
An audience is a named list of contacts — what other tools call a recipient list. A contact can belong to many audiences, and you add or remove members as people subscribe and unsubscribe. An audience is the thing you point a broadcast at.
Broadcasts
A broadcast is one message sent to an entire audience. Instead of listing addresses, you name the audience; Bird resolves its current members at send time, drops anyone on the suppression list, and delivers to the rest. Broadcasts default to the marketing category — they're marketing mail by intent — so unsubscribes and complaints are honored automatically, and Bird sets the one-click List-Unsubscribe headers for you. A broadcast can be sent immediately, scheduled for later, or canceled while it's still a draft.
How it relates to sending today
Audiences don't replace the send and batch endpoints — they sit alongside them. Transactional mail (receipts, resets, codes) is a per-message send keyed off your own data; a broadcast is for reaching a stored list at once. The same domains, suppression list, categories, and webhook events apply either way, so engagement and deliverability roll up across both.
Until these APIs ship, the way to reach many recipients from the API is the batch endpoint or fanning out over single sends from your own loop.
Next steps
- Bulk sending — batches and broadcasts, and what's available from the API today
- Categories — why broadcasts are marketing by default
- Unsubscribe links — the one-click headers Bird sets on broadcasts
- Suppressions — who Bird drops from an audience at send time