---
title: "List custom domains"
method: GET
path: "/v1/domains"
tags: ["domains"]
---

# List custom domains

`GET /v1/domains`

## Request

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

List the custom domains on your account. A pod-scoped key sees only its pod's domains plus account-wide ones.

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

List of custom domains

- object: List of custom domains
  - `data` 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
  - `total` integer

## Other responses

- `401`: Missing, invalid, or expired API key

---

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