---
title: "Idempotency"
description: "Making a retry safe."
url: "https://openemail.uk/docs/api/idempotency"
area: "API"
category: "Getting started"
---

# Idempotency

Making a retry safe.

## How it works

Send `Idempotency-Key` on `POST /emails`, `POST /emails/batch` or `POST /templates/{id}/send`. No other route reads it. The first call does the work, and a repeat with the same key returns the identical message. `POST /emails` also sets `Idempotency-Replayed: true`, while the batch reports `replayed` on each item and the template send reports it on the body and answers 200 instead of 202. The claim is taken as the database insert itself, so two requests racing with the same key cannot both win.

**Header**

```
Idempotency-Key: invoice-8812
```

Reusing a key with a different body is a `422 idempotency_key_reuse` rather than a silent replay. It almost always means the key was derived from something not unique enough, and replaying someone a message they did not send is worse than refusing.

> In a batch the key is extended per item, so one key on a hundred messages does not collapse them into the first one.