Linking Bird as a source
Let AI connect your sources for you
Skip the manual setup — run this in your project and the wizard auto-detects your databases and APIs and connects them to PostHog.

The Bird connector syncs your Bird communication data into the PostHog data warehouse, so you can analyze contacts, audiences, email, SMS, and WhatsApp messages, broadcasts, templates, and daily sending stats alongside your product data.
Prerequisites
You need a Bird account with access to create API keys. Create one in your Bird dashboard under Platform tools > API keys.
Keys from the older Bird Engagement Platform (api.bird.com) or MessageBird don't work with this connector. You need a key from the current bird.com platform – these keys start with bk_.
Adding a data source
- In PostHog, go to the Sources tab of the data pipeline section.
- Click + New source and click Link next to this source.
- Enter your credentials (see Configuration below) and click Next.
- Select the tables you want to sync, choose a sync method and frequency, then click Import.
Once the syncs are complete, you can start querying this data in PostHog.
When linking Bird, you'll need:
- API key – Create an API key in your Bird dashboard under Platform tools > API keys. Keys start with
bk_followed by your region code (e.g.bk_us1_...orbk_eu1_...). Give the key read access to the scopes for the tables you want to sync, such asemails,email_marketing,email_management,sms,whatsapp, andnumbers.
Sync modes
Each table can be synced in one of several modes, depending on what the source supports:
- Webhook (when available) – the source pushes changes to PostHog in real time. Fastest freshness, lowest ongoing cost, and the only mode that reliably captures updates and deletes.
- Incremental – only new or updated rows are synced on each run, using a cursor field (such as an
updated_attimestamp). Cheaper than a full refresh, but deletes aren't captured. - Append only – new rows are appended using a cursor field; existing rows are never updated. Ideal for immutable, append-only tables like event logs.
- Full refresh – the whole table is reloaded on every sync. Use it when a table has no reliable cursor or when you need deletions reflected.
See sync methods for a full explanation of how each mode works and how to choose between them.
Most Bird tables are full refresh only. Message tables (email_messages, sms_messages, whatsapp_messages, email_broadcasts, whatsapp_conversations) don't support incremental sync because message status changes after creation and the Bird API only filters on creation time.
The one exception is email_inbound_messages, which syncs incrementally on received_at. Bird keeps inbound email for 30 days, so incremental sync is important to avoid losing older messages.
Daily stats tables (email_daily_stats, sms_daily_stats, whatsapp_daily_stats) return data for the last 365 days on each sync and are not paginated.
email_suppressions is replaced on each sync because removed suppressions disappear from Bird's listing.
Configuration
| Option | Type | Required |
|---|---|---|
API key | password | Yes |
Supported tables
| Table | Description | Sync method | Incremental field | Primary key |
|---|---|---|---|---|
contacts | People in the workspace that broadcasts and messages can address, identified by email address or phone number. | Full refresh | — | — |
contact_properties | Custom properties defined for contacts in the workspace. | Full refresh | — | — |
audiences | Named groups of contacts that email broadcasts are sent to. | Full refresh | — | — |
email_messages | Emails the workspace sent or scheduled, with their aggregate delivery status and per-state recipient counts. | Full refresh | — | — |
email_broadcasts | Email broadcasts sent to an audience, with their lifecycle status and delivery and engagement counts. | Full refresh | — | — |
email_templates | Email templates available to the workspace, both its own and Bird's built-in system templates. | Full refresh | — | — |
email_domains | Sending domains of the workspace, with their verification status and DNS records. | Full refresh | — | — |
email_suppressions | Email addresses that Bird blocks from receiving mail, with one record per suppression reason. | Full refresh | — | — |
email_inbound_messages | Emails the workspace received. Bird keeps received email for 30 days. | Incremental, Full refresh | received_at | — |
email_daily_stats | Aggregate email sending, delivery and engagement statistics, one row per UTC day for the last 365 days. | Full refresh | — | — |
sms_messages | SMS messages the workspace sent or received. Bird keeps SMS messages for 30 days. | Full refresh | — | — |
sms_templates | SMS templates available to the workspace, both its own and Bird's built-in system templates. | Full refresh | — | — |
sms_daily_stats | Outbound SMS lifecycle counts, one row per UTC day for the last 365 days, attributed to the day each message was accepted. | Full refresh | — | — |
whatsapp_messages | WhatsApp messages the workspace sent or received. | Full refresh | — | — |
whatsapp_conversations | WhatsApp conversation threads between a connected number and a contact or group. | Full refresh | — | — |
whatsapp_templates | WhatsApp message templates available to the workspace, both its own and Bird's built-in system templates. | Full refresh | — | — |
whatsapp_daily_stats | Outbound WhatsApp lifecycle counts, one row per UTC day for the last 365 days, attributed to the day each message was accepted. | Full refresh | — | — |
numbers | Phone numbers allocated to the workspace, dedicated or shared. | Full refresh | — | — |
Troubleshooting
Invalid API key format: Bird API keys start with
bk_followed by the region (e.g.bk_us1_orbk_eu1_). Copy the full key from your Bird dashboard under Platform tools > API keys.API key rejected or revoked: Check that your key hasn't been revoked or expired. Create a new key in your Bird dashboard if needed.
Permission error on a specific table: Your API key is missing the read scope required for that table. Add the scope in your Bird dashboard under Platform tools > API keys, or deselect that table from syncing.
Wrong region error: The region prefix in your key doesn't match where your Bird organization is hosted. Copy the complete key from your Bird dashboard – the region is embedded in the key automatically.
If your sync is failing or data looks wrong, see the Data warehouse troubleshooting guide. If that doesn't help, contact support – we're happy to help.





