---
search:
  tags:
    - Domains
    - PATCH
seo:
  description: >-
    Update a domain. Reference for the PATCH /domains/{id} endpoint in the
    BillionSend API.
sidebar:
  label: Update a domain
  badge: PATCH
title: Update a domain
type: openapi-operation
---
`PATCH /domains/{id}`

**Request body** (`application/json`)

- `click_tracking` (boolean) — Rewrite links to redirect through the tracking host and record email.clicked events. Off by default.
- `open_tracking` (boolean) — Inject a tracking pixel served from the tracking host and record email.opened events. Off by default.
- `tracking_subdomain` (string | null) — DNS label of the domain's own tracking host, e.g. "links" for links.\<domain\>. Optional: without one, tracked links use the shared tracking host. Setting it adds a Tracking CNAME to records\[\] (point it at the given value, DNS only); its certificate is issued automatically once it resolves, the Tracking record then reads verified, and links go through it from then on. A subdomain that does not activate within 72 hours reads failed; send the same tracking\_subdomain again to retry. Empty string or null clears it.
- `unsubscribe_subdomain` (string | null) — BillionSend extension: DNS label of the domain's own unsubscribe host, e.g. "unsubscribe" for unsubscribe.\<domain\>. Optional: without one, unsubscribe links (and the List-Unsubscribe header) use the shared unsubscribe host. Setting it adds an Unsubscribe CNAME to records\[\] (point it at the given value, DNS only); its certificate is issued automatically once it resolves, the Unsubscribe record then reads verified, and unsubscribe links go through it from then on. The same label as tracking\_subdomain is allowed: one host then serves both and records\[\] shows one row. A subdomain that does not activate within 72 hours reads failed; send the same unsubscribe\_subdomain again to retry. Kept apart from tracking\_subdomain because ad blockers filter tracking hosts by name. Empty string or null clears it.
- `unsubscribe_page` (object) — BillionSend extension: this domain's own look for its unsubscribe pages. Fields not sent keep their value; null clears one, and a cleared field falls back to the team's default page. logo\_url is read-only here: the logo is uploaded in the dashboard.
- `tls` (any)
- `capabilities` (object) — What the domain is used for (sending, receiving); omitted fields keep their value.
- `receiving_catch_all` (boolean) — BillionSend extension: store mail to addresses without an inbox (true) or refuse it at RCPT (false). Turning it on needs receiving enabled and, on BillionSend Cloud, a paid plan.

Request body example:

```json
{
  "click_tracking": true,
  "open_tracking": true,
  "tracking_subdomain": "string",
  "unsubscribe_subdomain": "string",
  "unsubscribe_page": {
    "brand_name": "string",
    "message": "string",
    "success_message": "string",
    "redirect_url": "string",
    "background_color": "string",
    "text_color": "string",
    "accent_color": "string",
    "logo_radius": "square"
  },
  "tls": null,
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving_catch_all": true
}
```

**Responses**

- `200` — Domain updated; full object with records
- `401` — Missing, malformed, unknown or revoked API key
- `403` — Catch-all receiving or an own tracking / unsubscribe subdomain needs a paid plan, or the team's subdomain of the shared domain, which is read-only
- `404` — Not found, or a domain other than the one the calling key is held to
- `409` — Another team receives mail for this domain
- `422` — Validation error
- `429` — Over the rate limit (rate\_limit\_exceeded, with Retry-After)

Response example, 200:

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "status": "string",
  "created_at": "string",
  "region": "string",
  "open_tracking": true,
  "click_tracking": true,
  "tracking_subdomain": "string",
  "tracking_status": "pending",
  "tracking_error": "string",
  "unsubscribe_subdomain": "string",
  "unsubscribe_status": "pending",
  "unsubscribe_error": "string",
  "unsubscribe_page": {
    "brand_name": "string",
    "message": "string",
    "success_message": "string",
    "redirect_url": "string",
    "background_color": "string",
    "text_color": "string",
    "accent_color": "string",
    "logo_radius": "square",
    "logo_url": "string"
  },
  "capabilities": {
    "sending": "string",
    "receiving": "string"
  },
  "receiving_catch_all": true,
  "shared": true,
  "sending_mode": "open",
  "sending_mode_reason": "plan",
  "object": "domain",
  "records": [
    {
      "record": "string",
      "name": "string",
      "type": "string",
      "ttl": "string",
      "status": "string",
      "value": "string",
      "priority": 0,
      "live": "found",
      "detail": "string",
      "inherited_from": "string",
      "policy": "none"
    }
  ]
}
```
