Audiences
An audience is a named list of contacts. Build one once and reuse it, so reaching the same group again means naming the list instead of assembling the addresses. A contact can belong to many audiences, and you add or remove members as people join and leave.
Manage audiences under Contacts → Audiences in the dashboard, with bird audiences from the terminal, through the audiences API, or with any of the SDKs.
The Audiences page
The Audiences page lists your audiences by name, creation date, and type. Type reads Static for a list whose members you add and remove yourself. Viewing the page needs the email_marketing read permission, and creating or editing an audience needs write.
Creating one takes a name and, optionally, a description of who is in it. Open the audience afterwards to manage its members.
Members
Open an audience to see its members, listed most recently added first. Each row shows:
- The contact's name and email address.
- The channels the contact can be reached on.
- Every audience the contact belongs to, including this one.
- When the contact joined this audience.
Search the list by email address to find one member, and click a row to open the contact itself.
Two cards sit above the list. Members counts everyone in the audience, and Email counts how many of them have an address, with the number still deliverable after suppressions shown beside it. That deliverable number is what a broadcast to this audience actually reaches.
There are two ways to add people:
- Paste email addresses onto the audience, one per line, up to 1,000 at a time. We match each address to an existing contact, or create one if none matches, and then add all of them to the audience in a single step.
- Assign at import time by dropping contacts into audiences as you import or upsert them. The batch endpoint and bird contacts batch take an audience_ids list, up to 10 audiences per request, alongside the contacts. Every audience you name has to exist, or the whole request fails and nothing is written.
Adding is idempotent, so a contact that is already a member stays put and keeps its original join date. Removing a member takes the contact out of that one audience only: the contact itself stays in your workspace and in every other audience it belongs to. Remove one member from its row, or select several and remove them together.
From the CLI, use bird audiences add-contacts <audience-id> to add contacts and bird audiences remove-contacts <audience-id> to take them out again. Both commands take contact IDs, so you need to know the ID of every contact you are adding or removing. If all you have is a list of email addresses, use bird contacts batch with audience_ids instead. That command looks up each address, creates a contact for any address it does not recognize, and adds all of them to the audience in one call.
Sending to an audience
Sending one message to a whole audience is a broadcast. Pick the audience, and we resolve its members into the recipient list when the send starts, so the broadcast reaches whoever is a member of the audience at that moment. Broadcasts run from the dashboard, the API, or the bird email broadcasts commands.
For a one-off recipient list that is not worth storing as an audience, send a batch instead.
Next steps
- Contacts: the recipient records and typed properties an audience is built from
- Broadcasts: send one message to this audience
- Batch sending: an alternative to broadcasts for a one-off list, up to 100 messages per request
- Suppressions: the workspace list of addresses we will not deliver to
- API reference: full request and response schemas