Update a domain

Change tracking, TLS, or the tracking subdomain.

PATCH /v1/domains/{id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The domain id.

Body parameters

Every field is optional; send only what you're changing.

Parameter	Type	Description
open_tracking	boolean	Whether to record opens.
click_tracking	boolean	Whether to record clicks.
tracking_subdomain	string	A bare label, e.g. links. Can be set or changed, but not removed — see below.
tls	string	opportunistic or enforced. See Create a domain.
capabilities	object	What the domain may do. receiving cannot be enabled — see below.

The domain name, region and custom_return_path are fixed once the domain exists — they are part of the sending identity. To change them, delete the domain and add it again.

Example

curl

curl -X PATCH "https://api.sendgrail.com/v1/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "open_tracking": true,
    "click_tracking": true,
    "tracking_subdomain": "links",
    "tls": "enforced"
  }'

Node.js

await fetch(`https://api.sendgrail.com/v1/domains/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    open_tracking: true,
    click_tracking: true,
    tracking_subdomain: 'links',
    tls: 'enforced',
  }),
});

Response

Just the id — fetch the full object with Retrieve a domain to see the updated settings and any new records.

{
  "object": "domain",
  "id": "5f1c3a9e-0d42-4b7c-9a63-2e8b41d7c015"
}

A tracking subdomain can be changed, not removed

Setting a new tracking_subdomain — or changing an existing one — adds a fresh Tracking CNAME record (in pending status until verified). But you cannot clear it: links already sent point at the old subdomain, so its record must stay live or those links break. Sending an empty value changes nothing; to point future links at a different host, set a new label.

Receiving cannot be enabled

capabilities.sending is always enabled and capabilities.receiving is always disabled — inbound email is a later release. Asking to enable receiving is rejected:

{
  "message": "Receiving (inbound email) is not available yet. Domains can send only.",
  "code": "receiving_unavailable",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

Errors

A domain belonging to another team answers 404. A Sending access key answers 403. See Errors.