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.
Idempotency-Key: invoice-8812Reusing 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.