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

# List custom domains

`GET /domains`

## Request

- Base URL: `https://dash.mailsocket.app/api/v1`
- URL: `https://dash.mailsocket.app/api/v1/domains`
- Auth: HTTP bearer

Returns the caller's custom domains, newest first, with cursor
pagination. `403 byod_disabled` when custom domains are not enabled
for the account. Listing
is not plan-gated: an account on a plan without custom domains simply
gets an empty list (a downgraded account keeps read/list/delete on
domains it already owns). Creating one needs a Scale or Business
plan; see `POST /domains`.

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

A page of domains.

- object
  - `data` Domain[], required
    - `id` string, required: The domain public ID.
    - `name` string, required: The FQDN, stored lowercase. Immutable after create.
    - `status` 'pending_dns' | 'verified' | 'failed' | 'disabled', required
    - `verification_txt_host` string, required: The TXT record host to publish (`_mailsocket-verify.<name>`).
    - `verification_token` string, required: The TXT record value to publish at `verification_txt_host`.
    - `mx_target` string, required: The MX target that must be present once DNS is live (`mx.mailsocket.app`).
    - `last_checked_at` string, date-time, nullable, required
    - `last_error` string, required
    - `verified_at` string, date-time, nullable, required
    - `catch_all` boolean: True when unmatched local parts on this (verified) domain route to catch_all_inbox_id. Toggled via `PATCH /domains/{id}/catch_all`.
    - `catch_all_inbox_id` string, nullable: The catch-all inbox's public ID, or null when catch-all has never been configured.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `pagination` Pagination, required
    - `next_cursor` string, nullable, required: Opaque cursor for the next page, or null when there is none.
    - `has_more` boolean, required

## Other responses

- `401`: Missing or invalid API key.
- `403`: Account is not permitted to use the API, or BYOD is disabled (`byod_disabled`).
- `422`: `limit` is not an integer from 1 to 100, or `cursor` is invalid, tampered or expired (`validation_error`, details in `fields`).
- `429`: Rate limit exceeded.

---

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