Synchronize audience membership
Use your warehouse, CRM or application to decide who belongs in a cohort, then apply that selection to a Bird audience. The published audience API stores static membership. This integration pattern keeps it aligned with the source that evaluates your conditions without inventing a second set of rules in the sending workflow.
Before you begin
You need a named Bird audience, the corresponding contact records and access to the documented audience operations. Establish which source owns the selection and who may change its conditions. Use a small test cohort before running the integration against a campaign audience.
Write down the inclusion conditions, exclusions and evaluation time. For a cohort of customers renewing next week, specify the time zone and what happens when the source records a completed renewal. The selection must be reproducible enough to investigate an unexpected member.
Resolve the selected records
- Obtain the source result and record its evaluation time or revision in your integration.
- Create or update the corresponding Bird contacts with the batch contact operation. Match with your source identifier deliberately.
- Inspect each entry's outcome. Keep its source ID and resulting Bird contact ID in the integration's reconciliation record.
- Resolve identifier conflicts before treating that person as synchronized. A request containing successful entries can still contain failed entries.
The contact batch accepts audience_ids when adding records to known audiences. Use that for additions where it fits; removals still require a separate membership decision. An import that omits a person is not an instruction to remove or delete them.
Reconcile additions and removals
Read the existing membership using List an audience's contacts and follow its pagination. Compare Bird contact IDs with the resolved source selection.
| Difference | Action |
|---|---|
| Selected in the source, absent in the audience | Add the contact to the audience |
| Present in the audience, absent in the source | Remove membership if the source owns that audience |
| Present in both | Keep membership |
| Source record failed to resolve | Investigate before completing the refresh |
Apply changes through Add contacts to an audience and Remove contacts from an audience. Follow the current batch limits in those references.
Do not remove someone just because a source export was incomplete. Confirm that you have a complete source selection, including its final page, before calculating removals. Also avoid sharing an integration-owned audience with unrelated manual membership edits unless you have an explicit policy for preserving them.
Complete the refresh
After applying the differences, inspect failed operations and re-read the affected membership. Mark the refresh complete when it matches the intended source selection. Store the result in your integration so the next run can distinguish a finished refresh from an interrupted one.
If the process stops partway through, resume from the recorded work or recompute the difference from the current audience. Adding an existing member leaves membership intact; removing a member changes that audience's membership, not the contact record or consent.
Recheck the operation's current idempotency and response contract before automatically replaying a request whose result is uncertain. Treat request acceptance, per-entry outcomes and final reconciliation as distinct observations.
Connect the audience to sending
Use the completed selection in the relevant campaign workflow. Record when the audience was last refreshed and inspect the broadcast's current estimate before dispatch. Contact details, preferences and suppressions can change after the membership refresh.
For an Email broadcast, the estimate narrows from total members to addressable and sendable members. The eventual delivery result is a separate observation. Keep the source cohort, dispatch context and business outcome definition together when analyzing results.
Troubleshooting
- Unexpected removals: check for an incomplete source export or a second writer changing the same audience.
- The same failed contact returns each run: resolve the source identifier conflict or invalid property rather than silently skipping it forever.
- People remain after leaving the segment: verify that your integration applies removals as well as additions.
- The sendable count is smaller: inspect addresses, preferences and suppressions rather than adding people again.
Next steps
Related resources
Continue with the documentation, guides and examples for this topic. Resources are in English.
Watch the guideGetting started with emailExplore the capabilityEmailFollow the learning pathBuild your first integrationImplementation guideSend your first email
Try the practice and get an implementation brief