GEgetsitecontrol
Email domains

Verify a sending domain

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.

post/v1/sites/{site_id}/email-domains/{domain_id}/verify

Request

  • Base URL
    https://api.getsitecontrol.com
  • Auth
    HTTP bearer

Path parameters

site_idinteger required
domain_idinteger required

Domain id from list_email_domains

Headers

Idempotency-Keystring

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

Successful Response

idinteger required
domainstring required

Domain the site's emails are sent from, e.g. mail.example.com

is_verifiedboolean 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.

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_hintstring required

One sentence on the next step, ready to show the user

created_atstring date-time required

When the domain was added

last_checked_atstring date-time nullable

When the DNS records were last checked; null when never

Changes

No recorded changes to this operation across all 1 revision of this API.