domains

Update a sending domain

Updates settings and configuration on a sending domain. settings changes apply immediately. Changes to return_path, tracking, or dkim on a verified capability are staged: the current configuration keeps serving until the new one's DNS records verify, then the change is promoted automatically. Staged values are visible under capabilities.*.pending. The records to publish appear in dns_records with state: pending.

Invalid combinations are rejected. Enabling tracking toggles without a tracking domain, or removing the tracking domain while a toggle is on, returns 409. Enabling inbound receiving has verification prerequisites that return 422. When receiving has an assigned workspace, disabling it from a sibling returns 403. Read receiving.managed_elsewhere before changing receiving and receiving.state to follow a turn-off request. Each rule is detailed on its field.

patch/v1/email/domains/{domain_id}

Request

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

Path parameters

domain_idstring required
Example:dom_01krdgeqcxet5s7t44vh8rt9mg

ID of the domain to update.

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.

Request body

Example request

{
  "settings": {
    "click_tracking": true,
    "open_tracking": true
  },
  "tracking": {
    "name": "links"
  }
}

Response

Domain updated.

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 2 revisions of this API.