Guide

Use idempotency keys

Idempotency keys let you retry send-creating requests safely after a timeout or lost response. Use one stable key per logical send request.

Where keys are required

The public transport requires Idempotency-Key only for these send-creating operations:

Example

curl -X POST "https://api.ctct.dev/v1/emails" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-1042" \
  -d '{
    "from": "noreply@constantcontact.com",
    "to": ["ada@example.com"],
    "subject": "Receipt AB-1042",
    "html": "<p>Thanks for your order.</p>"
  }'

Retry rules

• Reuse the same key when retrying the same request body after a network timeout, connection reset, or unknown response.
• Use a new key when any send intent changes, including recipient, subject, content, schedule, or tags.
• Keep keys unique enough for your own system, such as receipt-<ORDER_ID> or a generated UUID.

Common error