Idempotency
Networks fail. If your request times out, you do not know whether it arrived. An idempotency key lets you send it again without doing it twice.
How it works
Add an Idempotency-Key header with a value that is unique for each thing you want done: a UUID, or your own order id. Use 1 to 255 visible ASCII characters. No line breaks, tabs or accented letters.
curl -X POST "https://app.ezreach.in/api/v1/email/messages" \
-H "Authorization: Bearer $EZREACH_API_KEY" \
-H "Idempotency-Key: order-A-1042-confirmation" \
-H "Content-Type: application/json" \
-d '{
"to": "ananya@example.com",
"from": "orders@mail.example.com",
"subject": "Your order A-1042 is confirmed",
"text": "Thank you! Your order A-1042 is confirmed.",
"kind": "transactional"
}'These endpoints take the header. Others ignore it, and GET, PATCH and DELETE are safe to repeat anyway.
POST /contactsPOST /contacts/bulkPOST /messagesPOST /eventsPOST /email/messages
What you get back
- The first request runs. EzReach keeps its answer for 24 hours.
- The same key with the same request again gets that stored answer, byte for byte, with the header
Idempotent-Replayed: true. Nothing is sent or changed a second time. "Same request" means the same endpoint and the same JSON body. The order of the keys and the spaces do not matter. - The same key with a different request gets
409 IDEMPOTENCY_CONFLICT. Use a new key for a new request. - While the first request is still running, a second one gets
409 IDEMPOTENCY_IN_PROGRESS. Send it again a moment later. - If the first request was cut off (
details.interruptedis true), nobody knows whether it happened. The key stays blocked for its 24 hours. Check in the panel, and send again with a new key only if it did not happen.
Which answers are kept
Answers that mean nothing happened are not kept, so you can send the same key again straight away:
402,403,429and server errors (5xx), except502 SEND_OUTCOME_UNKNOWN.409 CONFLICT, and anything withdetails.retryable: true.- Refusals you fix first:
VALIDATION_ERROR,NO_CONSENT,NO_POSTAL_ADDRESS,FROM_NOT_ALLOWED,CONTENT_INVALIDand the like.
Every other answer is kept, including 502 SEND_OUTCOME_UNKNOWN and anything with details.retryable: false. That is on purpose: a repeat must never send twice.
Keys belong to your workspace
A key that is empty, longer than 255 characters or not plain ASCII gets 400 INVALID_IDEMPOTENCY_KEY.

