---
title: "Re-check custom domain"
method: POST
path: "/v1/domains/{id}/verify"
tags: ["domains"]
---

# Re-check custom domain

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

## Request

- Base URL: `https://api.openmail.sh`
- URL: `https://api.openmail.sh/v1/domains/{id}/verify`
- Auth: HTTP bearer

Force an immediate DNS re-check of a custom domain, instead of waiting for the automatic background check. The domain verifies on its own within a couple of minutes of you publishing the records, so this is only needed to speed that up. An account-wide key may re-check any domain; a pod-scoped key may re-check only a domain scoped to its own pod, never an account-wide domain. Inbox-scoped keys cannot manage domains.

## Path parameters

- `id` string, required

## Response `200`

Re-checked; the returned domain reflects the latest status

- Domain
  - `id` string: OpenMail domain ID
  - `domain` string: The domain or subdomain, e.g. `example.com` or `agent-mail.example.com`.
  - `podId` string, nullable: Pod this domain is scoped to, so only inboxes in that pod can use it, or null for an account-wide domain.
  - `status` 'pending' | 'verifying' | 'verified' | 'failed' | 'under_review': `pending` — added, records not yet published. `verifying` — being checked. `verified` — sending and receiving enabled. `failed` — records missing or wrong; publishing them and calling verify again is the fix. `under_review` — flagged as suspicious; DNS setup is blocked until approved.
  - `records` DomainRecord[]: The DNS records to publish for this domain. Returned even where the values are the same for every customer, so sending infrastructure can change without breaking clients.
    - `type` 'TXT' | 'CNAME' | 'MX'
    - `name` string: The record's host, fully qualified, e.g. `_dmarc.agent-mail.example.com`.
    - `value` string: The record value to publish.
    - `priority` integer, nullable: MX records only.
    - `purpose` 'spf' | 'dkim' | 'dmarc' | 'mx' | 'return-path': What the record is for. Act on this rather than inferring from record shape: SPF must be merged into any the owner already has rather than replacing it, a DMARC policy at an apex can override the owner's own, and an apex MX takes over all their inbound mail.
    - `status` 'missing' | 'invalid' | 'valid': Whether this individual record is published and correct as of the last check. `missing` — not found yet. `invalid` — found but wrong. `valid` — published and correct. Shows which records are still outstanding, not only whether the whole domain passed.
  - `warnings` DomainWarning[]: Problems detected in the domain's DNS that do not block verification but do lose mail. Empty when none. Check this even when `status` is `verified` — every record can be correct and the zone still broken by something else in it.
    - `code` 'competing_mx': `competing_mx` — another MX record is published at the same or a more preferred priority than ours, so senders split the domain's inbound mail between us and a server that does not know its inboxes. Part of the mail bounces `550` while every record shows `valid`. Fix: remove the other MX, or give it a higher priority number than ours.
    - `message` string: Human-readable explanation and fix, safe to show to the domain owner.
    - `hosts` string[]: The competing MX hosts, lowercase, without trailing dot.
  - `verifiedAt` string, date-time, nullable
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `403`: The API key is scoped and cannot manage domains (`forbidden`)
- `404`: Not found
- `502`: The mail provider check failed (`provider_error`)

---

[API](https://skmtc.dev/openmail/apis/openmail-api.md) · [All operations](https://skmtc.dev/openmail/apis/openmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openmail/apis/openmail-api/revisions/b943eecca7e2?raw)