Domain verification
POST /v1/domains/{domain}/verify
Required scope: domains:write
What the responses mean
200 with "verified": true |
Done |
200 with "verified": false |
The record was not found. Not an error, just not there yet |
404 |
No such domain on your account |
502 DNS lookup failed |
We could not query DNS at all. A real failure, worth retrying |
The second row is the one to handle deliberately. A failed verification is
still a 200, carrying the current state so you can poll. If your code
treats any 200 as success it will think the domain is verified when it is
not; read the verified field.
Polling without wasting your time
DNS takes minutes, occasionally longer. A reasonable loop is every 30 seconds for a few minutes, then back off.
But understand what you are waiting for. POST /verify reads through a
caching resolver, so a just-published record can be invisible for up to
its TTL even though it is live at your provider. Calling verify in a tight
loop does not make it appear sooner, and it is the most common wasted action
here: the ticket that prompted a round of wording changes had somebody press
Verify nine times in 23 minutes against a domain that did not exist.
Before you retry more than a few times, check:
- Does the domain resolve at all?
dig yourcompany.comreturning NXDOMAIN means it is not registered, and no amount of verifying will help. - Is the record at the right name?
_lockally-verify.yourcompany.com, not the apex. See the record. - Is the value the bare token? Not
lockally-verify=<token>. - Is it live at your authoritative server?
dig TXT _lockally-verify.yourcompany.com @<your-nameserver>bypasses every cache between you and the truth.
Step 4 is the one that settles arguments. If the authoritative server has it and we do not see it, you are waiting on a cache. If the authoritative server does not have it, your provider has not saved what you think it saved.
Verification is permanent and monotonic
Once verified, a domain stays verified. Nothing re-checks the token, nothing
un-verifies on a DNS blip, and /recheck explicitly never reverses it.
You may remove the verification TXT record afterwards. There is no reason to, and leaving it is simpler.
What happens the moment it succeeds
Three things, all idempotent:
- your DKIM key is pushed to the mail server so outbound mail is signed
- a
dmarc@<yourdomain>mailbox is provisioned to receive DMARC reports - a webhook fires and the account admin is emailed, once
Because they are idempotent and also run on later verify calls, a domain whose
initial setup partly failed self-heals the next time anything calls
/verify. That is why calling it against an already-verified domain is cheap
and harmless.
Then what
Verification unlocks sending as that domain, under the rules in
Sender identity. Note that verification does not
inherit: verifying example.com does not authorise mail.example.com, which
must be added and verified separately.