Skip to content

Retrieve a domain ​

Fetch one domain by its id — including its DNS records and their current status.

http
GET /v1/domains/{id}

Requires a Full access API key.

Path parameters ​

ParameterTypeRequiredDescription
idstringYesThe domain id.

Example ​

bash
curl "https://api.sendgrail.com/v1/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"
js
const res = await fetch(`https://api.sendgrail.com/v1/domains/${id}`, {
  headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
});

const domain = await res.json();

Response ​

json
{
  "object": "domain",
  "id": "5f1c3a9e-0d42-4b7c-9a63-2e8b41d7c015",
  "name": "example.com",
  "status": "verified",
  "created_at": "2026-07-14T19:44:32+00:00",
  "region": "us-east-1",
  "capabilities": {
    "sending": "enabled",
    "receiving": "disabled"
  },
  "open_tracking": true,
  "click_tracking": true,
  "tracking_subdomain": "links",
  "tls": "opportunistic",
  "records": [
    {
      "record": "DKIM",
      "name": "sendgrail._domainkey",
      "type": "TXT",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ...",
      "ttl": "Auto",
      "status": "verified"
    },
    {
      "record": "SPF",
      "name": "send",
      "type": "MX",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "ttl": "Auto",
      "status": "verified",
      "priority": 10
    },
    {
      "record": "SPF",
      "name": "send",
      "type": "TXT",
      "value": "v=spf1 include:amazonses.com ~all",
      "ttl": "Auto",
      "status": "verified"
    },
    {
      "record": "DMARC",
      "name": "_dmarc",
      "type": "TXT",
      "value": "v=DMARC1; p=none;",
      "ttl": "Auto",
      "status": "verified"
    },
    {
      "record": "Tracking",
      "name": "links.example.com",
      "type": "CNAME",
      "value": "track.sendgrail.com",
      "ttl": "Auto",
      "status": "verified"
    }
  ]
}
FieldDescription
objectAlways domain.
idThe domain id.
nameThe domain itself, e.g. example.com.
statuspending, verified or failed. See below.
created_atISO 8601 time the domain was added.
regionWhere the sending identity lives: us-east-1, eu-west-1, sa-east-1 or ap-northeast-1.
capabilitiessending is always enabled; receiving is always disabled (inbound email is a later release).
open_trackingWhether opens are recorded.
click_trackingWhether clicks are recorded.
tracking_subdomainThe bare tracking label, e.g. links, or null when none is set.
tlsopportunistic or enforced. See Create a domain.
recordsThe DNS entries to add at your registrar. See below.

Status ​

statusMeaning
pendingThe domain is added but its DNS isn't verified yet. It cannot send.
verifiedDNS checks passed. The domain can send.
failedA check failed — usually a missing or wrong record. Fix the records and verify again.

Verification is not automatic. Add the records, then call Verify a domain to run the check, and retrieve to see the result.

The records array ​

Each entry is one DNS record you add at your registrar:

FieldDescription
recordWhat the record is for: DKIM, SPF, DMARC or Tracking.
nameThe host, relative to the zone apex — @ is the apex. Most providers append the apex for you.
typeTXT, MX or CNAME.
valueThe record value, copied verbatim.
ttlAlways Auto — any low TTL your provider offers is fine.
statusMirrors the domain status. A record isn't checked individually; a verified domain has verified records.
priorityPresent only on the MX record (10). Absent on the others.

DKIM proves the mail is signed by you; the SPF MX and TXT records set up the custom Return-Path; DMARC states your alignment policy; the TrackingCNAME appears only when a tracking_subdomain is configured.

A domain that isn't yours answers 404 ​

A domain belonging to another team answers 404, not 403 — an id that isn't yours is an id that doesn't exist, as far as your key is concerned.

json
{
  "message": "No domain with the id 5f1c3a9e-0d42-4b7c-9a63-2e8b41d7c015.",
  "code": "not_found",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

A Sending access key is a different failure: a real key that isn't allowed here, so it answers 403. See Errors.

Transactional email on your own domain.