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

# Idempotency

> Retry a send after a timeout without emailing anyone twice.

A request can time out after PulseSend has already accepted it. Retrying blindly would send the email twice. To retry safely, add an `Idempotency-Key` header:

```bash theme={null}
curl https://pulse-send.jiordiviera.me/api/v1/emails \
  -H "Authorization: Bearer $PULSESEND_API_KEY" \
  -H "Idempotency-Key: signup-otp-8f3a2c" \
  -H "Content-Type: application/json" \
  -d '{ "from": "...", "to": "...", "subject": "...", "html": "..." }'
```

## How it works

* The first request with a given key runs normally.
* Any repeat within 24 hours returns the original response, with the header `Idempotent-Replayed: true`. Nothing is sent again.
* Keys are scoped to the API key that sent them.

Pick a key that identifies the *intent*, not the attempt: an order ID, a user ID plus a purpose, or a UUID you generate once and reuse on retries.

## Conflicts

| Situation | Response |
| - | - |
| Same key, different body | `409` `idempotency_key_reused` |
| Same key while the first request is still running | `409` `idempotency_in_progress`. Wait and retry. |
| Key longer than 255 characters | `422` `idempotency_key_too_long` |

Responses with a `5xx` status aren't stored, so retrying them with the same key runs the request again.


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