Verify a domain claim

Check the ownership TXT record. On success the placeholder becomes your sending identity.

POST /v1/domains/{id}/claim/verify

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The placeholder domain's id — the domain_id returned by Claim a domain.

Example

curl

curl -X POST "https://api.sendgrail.com/v1/domains/$DOMAIN_ID/claim/verify" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

const res = await fetch(
  `https://api.sendgrail.com/v1/domains/${domainId}/claim/verify`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
  },
);

const claim = await res.json();

Response

The claim, with its status updated to reflect the check.

{
  "object": "domain_claim",
  "id": "9a3c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31",
  "name": "example.com",
  "status": "verified",
  "domain_id": "5f1c3a9e-0d42-4b7c-9a63-2e8b41d7c015",
  "region": "us-east-1",
  "record": {
    "type": "TXT",
    "name": "example.com",
    "value": "sendgrail-domain-verification=6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c",
    "ttl": "Auto"
  },
  "blocked_reason": null,
  "failure_reason": null,
  "created_at": "2026-07-14T19:44:32+00:00",
  "expires_at": "2026-07-21T19:44:32+00:00"
}

What the check does

• Record found → verified. Ownership is proven. The placeholder domain is provisioned as your own sending identity, with its own DKIM, and failure_reason is cleared.

• Record not found yet → stays pending. The TXT record hasn't propagated (or isn't published). failure_reason explains it — try again once DNS has caught up:

  {
    "status": "pending",
    "failure_reason": "The verification TXT record was not found. It may not have propagated yet."
  }

• Claim expired → failed. Past expires_at (7 days), the claim can no longer be verified; failure_reason is The claim has expired. Open a new claim with Claim a domain.

The call is safe to repeat while the claim is pending.

After a successful claim

verified here means ownership is proven — not that the domain can send yet. Your new identity has its own DKIM records to publish:

1. Retrieve the domain (using domain_id) to get its fresh records.
2. Add them at your DNS provider.
3. Run Verify a domain to move the domain itself to verified, after which you can send from it.

No claim on this domain — 404

{
  "message": "This domain has no claim.",
  "code": "not_found",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

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