---
title: "Update a domain"
method: PATCH
path: "/email/domains/{id}"
tags: ["Domains"]
---

# Update a domain

`PATCH /email/domains/{id}`

## Request

- Base URL: `https://www.unitpost.com/api/v1`
- URL: `https://www.unitpost.com/api/v1/email/domains/{id}`
- Auth: HTTP bearer

Update a domain's sending options: open/click tracking defaults, TLS enforcement, and the tracking subdomain. These act as the domain-level defaults that individual emails and campaigns can override (see [Update a campaign](#patch-email-campaigns-id)). A `tracking_subdomain` can be set at any time, so you can publish its CNAME along with the domain's other records. It is only checked once the domain is verified, and tracked links switch to it once its CNAME is published and it answers over HTTPS; until then they use the default tracking host. After a change, links keep using the previous subdomain until the new one answers over HTTPS (keep the previous CNAME in place). Changing it is limited to a few times an hour per domain, and to a few new subdomains a day per workspace. Requires the `domains:write` capability.

## Request body

- DomainUpdate
  - `open_tracking` boolean, nullable
  - `click_tracking` boolean, nullable
  - `tls` 'opportunistic' | 'enforced'
  - `tracking_subdomain` string, nullable

## Response `200`

The updated domain.

- Domain
  - `object` 'domain', required
  - `id` string, required
  - `name` string, required
  - `status` 'pending' | 'verifying' | 'verified' | 'degraded' | 'failed', required
  - `records` object[], nullable, required
    - `type` string, required
    - `name` string, required
    - `value` string, required
    - `priority` number
  - `dkim_selector` string, nullable, required
  - `open_tracking` boolean, nullable, required
  - `click_tracking` boolean, nullable, required
  - `tls` 'opportunistic' | 'enforced', required
  - `tracking_subdomain` string, nullable, required
  - `tracking_verified_at` string, nullable, required: When tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
  - `verified_at` string, nullable, required
  - `created_at` string, required
  - `updated_at` string, required

## Other responses

- `401`: Missing or invalid API key.
- `404`: Domain not found.
- `422`: Invalid request body.
- `429`: `rate_limit_exceeded`: the tracking subdomain was changed too often, or the workspace set up too many new tracking subdomains today. Includes a `Retry-After` header with the seconds to wait.

---

[API](https://skmtc.dev/unitpost/apis/unitpost-api.md) · [All operations](https://skmtc.dev/unitpost/apis/unitpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unitpost/apis/unitpost-api/revisions/86ff7c890967?raw)