> ## 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.

# Creating Emails

> Reserve random or custom receiving addresses safely and idempotently.

`POST /v1/emails` creates one address with a 30-day receiving reservation. An API-created address receives independently from the website, dashboard, or an open browser.

## Let the service choose

```bash theme={null}
curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $TML_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: signup-check-20260802-0001" \
  --data '{}' \
  "$TML_API_BASE/v1/emails"
```

## Request a custom address

Provide `local_part`, `domain`, or both. Use a domain returned by `GET /v1/domains`.

```json theme={null}
{
  "local_part": "signup-check-42",
  "domain": "mail.example.com"
}
```

Custom local parts are lowercase, at most 64 characters, and may contain letters, digits, dots, underscores, and hyphens within the documented pattern. Reserved, invalid, unavailable, or previously issued names are rejected. An address is never assigned again after expiry.

<Warning>
  Generate one stable idempotency key for the logical creation attempt. Reuse it
  after an uncertain network result; do not generate a new key for the retry.
</Warning>