Map the source carefully.
Use contact properties for personalization and an audience for membership. Neither audience membership nor an imported email address proves permission for a particular campaign.
Manage contact identity ↗EmailAudiences
Know your audience.
Make the message matter.
Keep contact properties and audience membership ready for the next campaign. Give the team useful context while keeping permission and sending eligibility explicit.
One person. A more useful picture.
Bring contact details and audience membership together so your next campaign reaches the right people. Explore how a customer profile changes as your application learns more.
FICTIONAL CONTACTS
Typed properties.
Rejected: this value is not a number. Correct it and retry the same contact identity. Importing does not grant permission.
The numeric property is updated on the same fictional contact. Audience membership and permission have not changed.
con_alex_example
Alex Lee
- City
- London
- visits_count
- 3
- Source revision
- 12
This contact is outside the Studio audience.
Audience member, but missing marketing permission. Exclude from this sample campaign.
Included in this sample. Other preferences, suppressions and account policy can still exclude the address.
Source revision 12: membership true Duplicate revision 12: unchanged Late revision 11: ignored Contact: con_alex_example
This application-owned revision policy avoids duplicate contacts and late membership reversal. It is an illustrative synchronization design, not a Bird guarantee of source-version enforcement.
Companies that trust Bird across their communications.
Read Bird customer storiesKeep identity, membership and permission distinct.
Build an explicit synchronization.
Decide which system owns additions and removals. Reconcile the complete membership snapshot and preserve restrictions before a broadcast uses that audience.
Synchronize audience membership ↗One contact record. Attributes that don't drift.
A contact holds a person’s email address, phone number and properties. An audience groups those contacts for a campaign. Add someone to multiple audiences and their details stay together in one record. It is all part of the Bird Email platform.
Five things that keep your data clean.
The data model does the bookkeeping, so your lists don't rot.
One record per person.
A workspace contact can hold an email address, a phone number or both, plus names, an external ID and custom data.
Audiences are membership.
An audience is a set of contacts you add and remove freely. Attributes always live on the contact, never copied onto the list.
Typed property registry.
Define your custom fields up front: string, number, boolean, or datetime, with optional fallbacks. Unknown keys and wrong-typed values are rejected at write time.
Batch upsert up to 1,000.
Upsert up to 1,000 contacts in a single call, and join them to an audience in the same request.
Exact-match lookup.
Find a contact by exact email match, so your own systems can sync without scanning every record.
Get a whole list in with one call.
Batch imports match the identifiers each entry carries and report per-entry outcomes. Upsert up to 1,000 contacts and join them to an audience in one request. When identifiers point to different contacts, review the conflicting entry before retrying. Reconcile completed and failed entries when resuming an interrupted import.
import.ts
202
// Upsert up to 1,000 contacts and add them to an audience at once.
const result = await bird.contacts.batch({
audience_ids: ["adn_01krdgeqcxet5s7t44vh8rt9mg"],
contacts: [
{ email: "ada@example.com", first_name: "Ada", data: { plan: "growth" } },
{ email: "grace@example.com", first_name: "Grace", data: { plan: "free" } },
],
});
// Per-contact results come back in submission order.
for (const item of result.data) {
console.log(item.entry.email, item.status);
}
Synchronize audience membership with CLI or MCP, then list its contacts to check the result. Keep subscription and consent decisions with your contact records.
See the audiences behind your next campaign.
Import a spreadsheet, review its field mapping and organize contacts into reusable groups. Names and typed properties stay on the contact; membership determines which audience they belong to.
Product screenshot with example records. Review audience membership and deliverability before sending.
Shared customer data
Use the same contact foundation across your messaging workflow.
Keep an audience in sync
Work through additions, removals and an incomplete refresh before launching a campaign.
Contact identity and properties
Inspect identifiers, matching rules and the customer record behind a recipient.
Audience selection
Connect source rules, explicit membership and channel eligibility.
Keep a cohort in sync
Apply additions and removals from the source system that evaluates your selection.
Continue with the workflow you need
Choose the product or guide that matches the next job.
Import a spreadsheet
Upload CSV, TSV or Excel, review field mapping and assign an audience.
Manage membership
Add or remove contacts from a reusable list and inspect its deliverable count.
Create the campaign
Use the audience in a broadcast when its content and sender are ready.
Email guides and FAQs
Learn the contact model or find help with the next workflow.
Questions about contacts and audiences
Where do my contacts and audiences live?
Contacts belong to a workspace. A record can hold an email address, a phone number or both, plus an external ID and typed properties. Audiences reference those records, so updating a contact keeps its data consistent across the lists it belongs to.
How can I import a list?
Upload a CSV, TSV or Excel file in the dashboard and review the field mapping before importing. You can assign contacts to audiences during import. For application syncs, batch-upsert up to 1,000 contacts per request through the API or CLI.
Are audiences dynamic segments?
The documented audience workflow uses static membership: you add or remove contacts. A broadcast resolves the audience when sending begins. Use your application or import workflow to keep membership current.
What types of contact properties are supported?
Define text, number, boolean and datetime properties with optional fallback values. Use those properties for recipient personalization and keep the typed values consistent when importing or syncing contacts.
Put it into practice.
Continue with the documentation, guides and examples for this topic. Resources are in English.
Watch the guideManage your customers: contacts & audiencesFollow the learning pathBuild your first integration
Get an implementation briefUse your audience
Broadcasts
Marketing campaigns: draft, target an audience, schedule, and send.
Templates
Stored, versioned email templates, personalized per recipient at send.
Suppressions
Recipient suppressions and opt-out preferences checked before delivery.
Email API overview
The full Email API: sending, deliverability, IPs, suppression, analytics, and broadcasts.
Talk to our email team
Plan your contacts and audience setup.
Bring your contact sources, segmentation needs and consent requirements. We’ll help you connect them to your email campaigns.
Create your account, then add contacts and build your first audience.