domains

Release link tracking configuration

Removes the link tracking configuration from this domain and releases the claim on its tracking subdomain, so another organization can configure the same hostname. Click and open tracking are switched off as part of the release. Tracking links in previously delivered messages stop resolving once no other domain in your organization uses the same tracking hostname.

This is the hard removal. To swap or remove tracking while keeping previously sent links working, use Update a sending domain instead, which retires the old records gradually. A domain with no tracking configured returns 422.

post/v1/email/domains/{domain_id}/tracking/release

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/domains/{domain_id}/tracking/release
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

domain_idstring required
Example:dom_01krdgeqcxet5s7t44vh8rt9mg

ID of the domain to release tracking for.

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

Updated domain after tracking release.

idstring required
workspace_idstring required
domainstring required

The sending domain name. Set at creation and immutable.

vendor'other' | 'cloudflare' | 'route53' | 'godaddy' | 'namecheap' | 'google' | 'azure' | 'digitalocean' | 'squarespace' required

The DNS provider hosting this domain's nameservers, so you know which provider's dashboard to manage the required DNS records in. Returns other when the provider has not been detected or is not recognized.

status'pending' | 'verified' | 'failed' | 'temporary_failure' | 'rejected' required

Domain ownership verification, proven by the DKIM record. Readiness to send or track is reported separately per capability under capabilities.*.status.

  • pending: the DKIM record has not been published yet.
  • verified: the DKIM record is in place; ownership is confirmed.
  • failed: a DKIM record exists but does not match the expected value (for example a stale record from an earlier setup), or a previously verified record was removed. Correct the record to recover.
  • temporary_failure: DNS resolution failed transiently, such as from a timeout or unreachable nameserver. Verification retries automatically; do not change the DNS records unless they are incorrect.
  • rejected: the domain was refused for policy reasons and cannot be used for sending. Contact support if you believe this is an error.
last_checked_atstring date-time nullable

When we last checked this domain's DNS records, whether or not the outcome changed. Updated on every verification: your manual refresh and the periodic automatic re-checks alike. null if the domain has never been checked.

verified_atstring date-time nullable

When the domain's ownership was confirmed: the moment status became verified via the DKIM record. Unchanged by later re-checks while it stays verified. null if the domain has never been verified.

created_atstring date-time required

When the domain was added.

updated_atstring date-time required

When the domain's configuration was last changed (such as a settings or return-path change). Verification re-checks do not change this; see last_checked_at and verified_at for verification timing.

Example response

{
  "id": "dom_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "domain": "mail.acme.com",
  "dkim": {
    "selector": "bird1",
    "key_size": 2048
  },
  "capabilities": {
    "sending": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "return_path": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "dmarc": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "tracking": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    },
    "inbound": {
      "status": "verified",
      "pending": {
        "domain": "rp.mail.acme.com",
        "status": "pending"
      }
    }
  }
}

Changes

No recorded changes to this operation across all 3 revisions of this API.