Browse the docs

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
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 /contacts
  • POST /contacts/bulk
  • POST /messages
  • POST /events
  • POST /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.interrupted is 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, 429 and server errors (5xx), except 502 SEND_OUTCOME_UNKNOWN.
  • 409 CONFLICT, and anything with details.retryable: true.
  • Refusals you fix first: VALIDATION_ERROR, NO_CONSENT, NO_POSTAL_ADDRESS, FROM_NOT_ALLOWED, CONTENT_INVALID and 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.