# Tracking domain

A **tracking domain** is a branded hostname on your [sending domain](/docs/guides/email/sending-domains) that serves open and click tracking. With it in place, the links Bird rewrites for [click tracking](/docs/guides/email/tracking-and-metrics) 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](/docs/guides/email/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:

| Type  | Host                | Value                     |
| ----- | ------------------- | ------------------------- |
| CNAME | `links.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**](https://bird.com/dashboard/w/email/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:

```bash
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](/docs/guides/email/tracking-and-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](/docs/api/reference/release-tracking-domain) 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

- [Email metrics](/docs/guides/email/tracking-and-metrics): what open and click tracking record, and the per-send flags
- [Sending domains](/docs/guides/email/sending-domains): registering a domain and the verification lifecycle
- [Bounce domain](/docs/guides/email/bounce-domain): the required return-path hostname
- [DKIM, SPF & DMARC](/docs/guides/email/dkim-spf-dmarc): every record on the domain and what it proves