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

# List domains

`GET /api/v1/domains`

## Request

- Base URL: `https://supermailos.com`
- URL: `https://supermailos.com/api/v1/domains`
- Auth: HTTP bearer

The workspace's domains with their status and what's wrong with their DNS, plus how many the plan allows. A workspace owner's or admin's key; an agent's own key gets `403`.

## Response `200`

Domains.

- object
  - `domains` DomainSummary[], required
    - `id` string, required
    - `domain` string, required
    - `kind` 'custom' | 'instant', required: `instant`: the workspace's free subdomain of ours, with nothing to set up.
    - `status` 'pending' | 'verifying' | 'verified' | 'failed', required
    - `canSend` boolean, required: Mail can be sent from it (it's verified).
    - `createdAt` string, date-time, required
    - `verifiedAt` string, date-time, nullable, required
    - `lastCheckedAt` string, date-time, nullable, required
    - `nextCheckAt` string, date-time, nullable, required: The next scheduled check, while it isn't verified.
    - `problems` string[], required: What's wrong, one line per failing required record.
  - `allowance` object, required
    - `used` integer: Custom domains in the workspace.
    - `limit` integer, nullable: `null`: unlimited.

## Other responses

- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks the scope (`missing_scope`) or the access (`forbidden`).
- `404`: Not found — or not reachable with this key.
- `429`: Too many requests.

---

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