Documentation
Sign inGet started
Commencer
Guides
Référence API
SDK et CLI
Base de connaissances
Changelog

Tracking domain

A tracking domain is a branded hostname on your sending domain that serves open and click tracking. With it in place, the links Bird rewrites for click tracking point at your own hostname over HTTPS instead of a generic Bird domain: better-looking to recipients, and it keeps link reputation tied to your brand. Unlike the bounce domain, it's optional. It gates branded tracking, never sending.

The record

The tracking domain is a CNAME under your sending domain that resolves to Bird's tracking infrastructure in your region:
TypeHostValue
CNAMElinks.example.com<region>.links.bird.com
The value is region-specific (us1.links.bird.com or eu1.links.bird.com); copy it from your domain's detail page (open it from the Domains page) or the domain resource. The host defaults to links. under your sending domain.

Customizing the hostname

Choose the label when you register the domain by passing tracking.name; Bird composes the full hostname:
Exemple de code
curl -s https://us1.platform.bird.com/v1/email/domains \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mail.acme.com",
    "tracking": { "name": "click" }
  }'
That registers click.mail.acme.com as the tracking host instead of the default links.mail.acme.com. Like the return-path, it's a per-workspace choice.

It doesn't gate sending

A domain with verified DKIM, return-path, and DMARC can send even with no tracking record at all; capabilities.tracking is reported separately from capabilities.sending. Until the tracking CNAME verifies, opens and clicks aren't tracked through your branded host, and nothing about delivery changes.
Tracking is the AND of three things, so a verified tracking domain alone doesn't turn tracking on:
  • The per-send flag: track_opens / track_clicks on the message (both default true).
  • The domain setting: settings.open_tracking / settings.click_tracking (both default off; enabling one with no tracking domain configured returns 409). You can flip these on before the CNAME verifies; they take effect once it does.
  • A verified tracking CNAME.
So opens and clicks start flowing only once you've configured and verified a tracking domain and flipped the domain setting on. See Email metrics for what each flag does to a message.

Changing it later

Tracking-hostname changes are staged the same way return-path changes are: a hostname that's already verified is never replaced by an unverified one. Bird verifies the new tracking CNAME alongside the active one and promotes it only once the new record checks out, so branded tracking never breaks mid-change. After a swap, the old records are reported as deprecated, and tracked links in previously sent email keep resolving.

Removing it

Two paths remove it, with different blast radius:
  • Remove tracking from the domain by updating it with tracking: null. Both tracking settings must be off first; the update returns 409 otherwise. Sending is unaffected, new sends stop using branded tracking, and links in previously sent email keep resolving while the old records are reported as deprecated.
  • Release the hostname with the release endpoint when you want to free it for reuse. A tracking hostname is claimed by one organization per region, so another organization can't register it while you hold it. Releasing removes the tracking configuration, switches both tracking settings off, and drops your claim. This is the hard removal: tracked links in previously delivered messages stop resolving once no other domain in your organization uses the same hostname.
If you're migrating to a new hostname, stage the change instead of releasing: swap via update, let the new CNAME verify, and old links keep working.

Next steps