Verify a domain

Trigger a DNS re-check so a pending domain can become verified.

POST /v1/domains/{id}/verify

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The domain id.

Example

curl

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

Node.js

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

const { id: domainId } = await res.json();

Response

Just the id. The check runs against the mail provider asynchronously, so the response does not carry the outcome — retrieve the domain to read the new status.

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

The verify-then-poll flow

Verification is a request to check, not a promise that the domain is now live:

1. Publish the records from Create a domain or Retrieve a domain at your registrar.
2. Call this endpoint. It kicks off an asynchronous DNS re-check of your DKIM, Return-Path and (if set) tracking records against the mail provider.
3. Retrieve the domain and read status. It moves to verified once the checks pass, stays pending while DNS is still propagating, or goes failed if a record is missing or wrong.

DNS changes take time to propagate — from minutes to hours. If status is still pending, give it a little longer and verify again; the call is safe to repeat.

If the provider can't be reached

If the mail provider can't be reached to run the check, the call answers 503 and nothing changes — try again shortly:

{
  "message": "Could not reach the mail provider to verify the domain. Try again shortly.",
  "code": "verification_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.