Update a domain

Update a domain

PATCH/api/v1/email/domains/{id}

PATCH /email/domains/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/domains/dom_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "click_tracking": true,
    "open_tracking": true
  }'
Response · 200
{
  "object": "domain",
  "id": "id_123",
  "name": "Example",
  "status": "pending",
  "records": [
    {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    }
  ],
  "dkim_selector": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "tracking_subdomain": "string",
  "tracking_verified_at": "2026-01-01T00:00:00.000Z",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving": {
    "status": "disabled",
    "record": {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    },
    "checks": {
      "mx_found": false,
      "mx_lowest_priority": false,
      "other_mx_found": false
    },
    "checked_at": "2026-01-01T00:00:00.000Z"
  },
  "verified_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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). 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. **Receiving.** capabilities.receiving: "enabled" receives mail sent to any address at the domain: each message is stored and fires the email.received webhook. The domain must be verified (or degraded), else 409 and nothing in the request is applied. Then publish receiving.record (an MX record at the domain's own name) and call Verify a domain: receiving.status turns verified once the record wins and mail is accepted. An MX record takes ALL mail for the name, so if receiving.checks.other_mx_found is true the name already gets mail elsewhere: receive on a subdomain instead (add it as its own domain). "disabled" stops receiving and is always allowed. Turning it on is limited to a few times an hour per domain; sending "enabled" again while it's on doesn't count. Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body5 fields
FieldTypeDescription
open_trackingboolean | null—
click_trackingboolean | null—
tlsenumopportunistic | enforced—
tracking_subdomainstring | null—
capabilitiesobjectTurn receiving on or off: `{ "receiving": "enabled" }` or `{ "receiving": "disabled" }`.
Response · 200 fields16 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen 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.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422429

Search docs and guides

Search the docs and product guides.