Concepts

Idempotency

Retry sends safely — the same key never sends twice

Network timeouts happen. To retry POST /v1/emails without risking a duplicate send, pass an Idempotency-Key header — any unique string that identifies the operation (an order id, a job id):

$curl -X POST https://api.rray.app/v1/emails \
>  -H "Idempotency-Key: order-1042-receipt" \
>  ...

Semantics

  • The first request with a key performs the send; the response is stored for 24 hours (scoped to the workspace).
  • A retry with the same key and the same body replays the stored response — same email id, no second send.
  • A retry while the original is still in flight returns 409 idempotency.in_progress — wait briefly and retry.
  • The same key with a different body returns 409 idempotency.body_mismatch — keys identify one exact operation.

Practical guidance

  • Generate the key where the business operation is born (e.g. invoice-{id}-receipt), not per HTTP attempt — that’s the whole point.
  • Safe to adopt gradually: requests without the header behave exactly as before (each attempt sends).
  • If a sender crashes mid-request, the key unlocks automatically after ~60 seconds, so a stuck lock can’t block the operation forever.