Retries and idempotency

Networks time out. If your request times out, you do not know whether the email was sent. Retrying blindly can send it twice. An idempotency key solves that.

Add an Idempotency-Key header: 1 to 128 characters, letters, numbers and . _ : -.

curl -X POST https://app.emitemail.com/api/v1/emails \
  -H "Authorization: Bearer $EMIT_API_KEY" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -H "Content-Type: application/json" \
  -d '{"from":"Shop <orders@shop.com>","to":"ana@example.com","subject":"Order 1042","text":"Thanks!"}'

How it behaves#

For 24 hours:

• The same key with the same message returns the first answer, with "replayed": true. Nothing is sent and nothing counts toward your cap.
• The same key with a different message is refused (422 idempotency_key_reuse).
• A request that was refused for a cap or an unverified domain does not use up the key, so you can retry once the cause is fixed.
• Two requests with the same key at the same moment send once. The second gets 409 idempotency_in_progress and can retry shortly.

What to retry#

Retry network errors, timeouts and 5xx responses, with the same key and a short growing delay. Do not retry other 4xx errors except 409. On 429, stop: the cap or daily limit was reached, and retrying will not help until it resets.