Release link tracking configuration

POST

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

curl -X POST "https://us1.platform.bird.com/v1/email/domains/{domain_id}/tracking/release" \
  -H "Authorization: Bearer $TOKEN"

响应200

{
  "id": "dom_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "domain": "mail.acme.com",
  "vendor": "other",
  "status": "pending",
  "next": [
    {
      "kind": "operation"
    }
  ],
  "dkim": {
    "mode": "txt",
    "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"
      }
    }
  },
  "dns_records": [
    {
      "type": "TXT",
      "purpose": "dkim",
      "state": "active",
      "status": "pending"
    }
  ]
}

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.

参数

domain_idstring

ID of the domain to release tracking for.

响应载荷

id

string

必填

workspace_id

string

必填

domain

string

必填

The sending domain name. Set at creation and immutable.

vendor

string

必填

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.

Possible values: other, cloudflare, route53, godaddy, namecheap, google, azure, digitalocean, squarespace

status

string

必填

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.

Possible values: pending, verified, failed, temporary_failure, rejected

settings

object

必填

Per-domain behavior toggles. Changes apply immediately to new sends.

显示子属性

next

array of object

What to do next about this domain, given the state it is in. Each entry names one action and says why it is worth taking, so you can act on this response without working out the order yourself. Present on reads that compute it: an empty list means there is nothing to do, and the field is absent entirely on responses that do not report next actions.

This answers whether you own the domain, which is what status reports. What each capability still needs before it can send or receive is reported separately under capabilities, so an empty list here does not on its own mean the domain is ready.

显示子属性

next.kind

string

必填

What you do about this step.

operation: call the operation named in operation, then read again.
external: act somewhere this API does not reach, then read again.
wait: nothing is asked of you, so read again later.
terminal: nothing you do resolves this, so stop retrying.

Tolerate a value you do not recognize: show the description and offer no action.

Possible values (may grow over time): operation, external, wait, terminal

next.description

string

必填

A short, human-readable label for the step, suitable for display.

next.operation

string

The operationId to call. Present only when kind is operation. The operation's own schema says how to call it; this says only which one, and what to address it with.

next.params

object

The parameters that address the operation, by name: {"sender_id": "…"} for an operation on /v1/sms/senders/{sender_id}/requirements. A parameter the operation takes in its query string is given the same way, so an operation addressed as ?subject_id= carries {"subject_id": "…"}. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when kind is operation and the operation names a subject. A request body, when the operation takes one, is described by the operation's own schema and never appears here.

next.url

string

A URL to open. Present only when kind is external, and only when the step has one. An external step whose description says to go and do something with no URL to open is normal.

dkim

object

必填

Active DKIM signing configuration for the domain.

显示子属性

capabilities

object

必填

显示子属性

dns_records

array of object

必填

The domain's DNS records and their individual verification state, returned in full on both the list and single-domain responses. This is the complete set to publish across DKIM, return-path, DMARC, tracking, and inbound; records for a staged change carry state: pending. Inbound MX records are always included as a regional reference, even while receiving is off and capabilities.inbound.status is not_configured. Their presence alone does not mean receiving is enabled; see DomainUpdate.inbound.

显示子属性

last_checked_at

nullable string

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_at

nullable string

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_at

string

必填

When the domain was added.

updated_at

string

必填

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.

继续查看此主题的文档、指南和示例。

获取实施简报

curl -X POST "https://us1.platform.bird.com/v1/email/domains/{domain_id}/tracking/release" \
  -H "Authorization: Bearer $TOKEN"

响应200

{
  "id": "dom_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "domain": "mail.acme.com",
  "vendor": "other",
  "status": "pending",
  "next": [
    {
      "kind": "operation"
    }
  ],
  "dkim": {
    "mode": "txt",
    "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"
      }
    }
  },
  "dns_records": [
    {
      "type": "TXT",
      "purpose": "dkim",
      "state": "active",
      "status": "pending"
    }
  ]
}

Release link tracking configuration

参数

响应载荷

相关资源