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

# Idempotency

> Retry email creation without creating duplicate reservations.

`POST /v1/emails` requires an `Idempotency-Key` header. Generate a unique, unpredictable value for each logical create operation and store it until the outcome is certain.

```http theme={null}
Idempotency-Key: signup-check-20260802-0001
```

Keys are scoped to the authenticated account and operation:

* The first successful request returns `201` and creates one reservation.
* Replaying the same key with an equivalent body returns the original resource, sets `Idempotency-Replayed: true`, and is not charged again.
* Reusing the key with a different body returns `409`.
* A transient network or `5xx` result should be retried with the same key.

Do not use a timestamp alone when multiple workers can create concurrently, and do not generate a new key merely because the original response was lost. Idempotency protects API-level retries; it is not a replacement for storing your own workflow state.