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

# Inboxes

> Create random or custom temporary email addresses.

`POST /v1/emails` reserves one receiving address for 30 days. If you send an empty JSON object, the API chooses both the local part and domain.

```bash theme={null}
curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: YOUR_UNIQUE_KEY_16_CHARS_OR_MORE" \
  --data '{}' \
  https://api.tempmaillab.com/v1/emails
```

## Custom addresses

List the domains available to your account:

```bash theme={null}
curl --fail-with-body \
  --header "Authorization: Bearer YOUR_API_KEY" \
  https://api.tempmaillab.com/v1/domains
```

Then pass `local_part`, `domain`, or both when creating the inbox:

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

Local parts are lowercase, up to 64 characters, and may contain letters, numbers, dots, underscores, and hyphens. Use a domain returned by `/v1/domains` with creation and receiving enabled.

## Idempotency and lifetime

`Idempotency-Key` is required. Repeating the same key and body returns the original inbox; using the same key with a different body returns `409`.

Use the returned `eml_*` ID in API paths. The address receives until `expires_at` and is never allocated again after expiry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.