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.

Learn more
PostHog Wizard hedgehog

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

  1. In PostHog, go to the Sources tab of the data pipeline section.
  2. Click + New source and click Link next to this source.
  3. Enter your credentials (see Configuration below) and click Next.
  4. 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_... or bk_eu1_...). Give the key read access to the scopes for the tables you want to sync, such as emails, email_marketing, email_management, sms, whatsapp, and numbers.

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_at timestamp). 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

OptionTypeRequired
API keypasswordYes

Supported tables

TableDescriptionSync methodIncremental fieldPrimary 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 refreshreceived_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_ or bk_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.

Still have questions?

Was this page useful?