---
title: "Get custom domain"
method: GET
path: "/v1/domains/{id}"
tags: ["domains"]
---

# Get custom domain

`GET /v1/domains/{id}`

## Request

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

Retrieve a single custom domain by its ID, including its verification `status` and the DNS records to publish. Poll this after adding a domain to watch it flip to `verified`.

## Path parameters

- `id` string, required

## Response `200`

Custom domain details

- 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

- `404`: Not found

---

[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)