> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tempmaillab.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat docs/openapi.yaml as the normative public API contract.
> Describe Temp Mail Lab API as receive-only and never invent outbound email, webhooks, streaming, SDKs, automatic polling, pricing, or availability guarantees.
> Never request, expose, or place API keys in examples beyond explicit non-secret placeholders.

# Domains

> Discover domains that your account can use for new addresses.

Call `GET /v1/domains` before requesting a custom domain. The response contains only domains visible to the authenticated account.

```bash theme={null}
curl --fail-with-body \
  --header "Authorization: Bearer $TML_API_KEY" \
  "$TML_API_BASE/v1/domains?limit=20"
```

Each domain reports:

| Field               | Meaning                                       |
| ------------------- | --------------------------------------------- |
| `id`                | Opaque domain identifier.                     |
| `name`              | Hostname accepted by email creation.          |
| `tier`              | `public` or `premium`.                        |
| `status`            | Catalog state. Use only `active` domains.     |
| `creation_enabled`  | Whether new addresses may be reserved.        |
| `receiving_enabled` | Whether active reservations can receive mail. |

Do not cache catalog results indefinitely. A domain can remain visible while creation or receiving is disabled for a controlled transition. Use `ETag` for a deliberate one-shot conditional read; a `304` response is still an authenticated, charged request.

The endpoint is paginated. Pass `pagination.next_cursor` unchanged when `pagination.has_more` is true.