---
title: "Verify a sending domain"
method: POST
path: "/v1/sites/{site_id}/email-domains/{domain_id}/verify"
tags: ["Email domains"]
---

# Verify a sending domain

`POST /v1/sites/{site_id}/email-domains/{domain_id}/verify`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/email-domains/{domain_id}/verify`
- Auth: HTTP bearer

Checks a sending domain's DNS records with the e-mail provider now, as the
Verify button in the admin does, and returns the domain with its new state,
records and next action. Call it when the user says they published or fixed
the DNS records, instead of waiting for the automatic checks; it needs the
right to edit e-mails, as the button does. A domain that was set up with a
provider no longer in use is returned unchanged.

## Path parameters

- `site_id` integer, required
- `domain_id` integer, required: Domain id from `list_email_domains`

## Headers

- `Idempotency-Key` string: Makes a retry of a POST safe: a repeat with the same key, body and GSC-Version returns the stored response with `Idempotency-Replayed: true` instead of running again. The key protects against repeated execution while the key store works. Saving the change and storing the response under the key are not atomic: if the process or the key store fails between them, the change is kept, the key is released after 15 minutes and a retry runs the request again. After a timeout or a 5xx, read the resource to check the result before retrying. 5xx and 429 responses and responses over 256 KB are not stored, so a repeat runs the request again. A key is kept for 24 hours. The same key with another body or version is 422; a repeat while the first request runs is 409.

## Response `200`

Successful Response

- EmailDomain
  - `id` integer, required
  - `domain` string, required: Domain the site's emails are sent from, e.g. mail.example.com
  - `is_verified` boolean, required: true: the DNS records were found and emails go out from this domain; false: not verified yet
  - `state` 'verified' | 'not_started' | 'pending' | 'recheck_required', required: Where verification of the domain stands. `verified`: the records were found and emails go out from the domain. `not_started`: the domain has no records to publish yet, verification was never started. `pending`: the records are known but not found yet, either not published or not seen yet, and are checked again automatically. `recheck_required`: automatic checks gave up, two weeks after the domain was added.
  - `required_dns` DnsRecord[], required: DNS records the domain needs, to be published at its DNS provider; empty until verification has been started
    - `purpose` 'spf' | 'dkim' | 'dmarc' | 'verification' | 'tracking', required: What the record proves. `spf`: lets our servers send for the domain. `dkim`: lets them sign its mail. `dmarc`: sets the domain's policy for mail that fails both. `verification`: proves the domain is yours. `tracking`: serves the click and open links from it.
    - `type` 'TXT' | 'CNAME', required: DNS record type to create: `TXT` a text record, `CNAME` an alias.
    - `name` string, required: Record name relative to the sending domain, as most DNS providers ask for it; `@` is the domain itself
    - `host` string, required: Full host name of the record
    - `value` string, required: Exact value to publish
  - `verification_error` 'record_missing' | 'record_wrong' | 'temporary': Why the e-mail provider last failed the domain's check; with `record_missing` or `record_wrong` the provider has stopped checking. `record_missing`: a required record was not found at the domain's DNS; fix the records, then verify the domain. `record_wrong`: a record was found with a different value; fix the records, then verify the domain. `temporary`: the check could not be completed and is tried again.
  - `next_action` 'nothing' | 'add_domain' | 'start_verification' | 'publish_dns' | 'request_recheck', required: What the user does next. `nothing`: the domain is verified. `add_domain`: the site has no sending domain yet. `start_verification`: the domain has no records yet, verifying it gives them. `publish_dns`: add the records of `required_dns` at the domain's DNS provider; they are checked automatically after verification starts, verify again only to check now. `request_recheck`: checks stopped (two weeks passed, or the provider found a record missing or wrong); check the records and verify again.
  - `next_action_hint` string, required: One sentence on the next step, ready to show the user
  - `created_at` string, date-time, required: When the domain was added
  - `last_checked_at` string, date-time, nullable: When the DNS records were last checked; null when never

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: `site_not_found`: no such site in your account; `email_domain_not_found`: the site has no domain with this id
- `409`: Conflict
- `413`: Request body too large
- `422`: Validation failed
- `429`: Rate limited
- `503`: Temporarily unavailable; retry later

---

[API](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api.md) - [All operations](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/revisions/084fcad80e75?raw)