Skip to content
SendSignal Docs

Idempotency keys

Pass an Idempotency-Key header on POST /emails to make retries safe; replaying the same key returns the original email instead of sending twice:

Terminal window
curl https://api.sendsignal.dev/emails \
  -H "Authorization: Bearer ss_..." \
  -H "Idempotency-Key: order-123-receipt" \
  -H "Content-Type: application/json" \
  -d '{"from":"Acme <hi@acme.com>","to":"user@example.com","subject":"Receipt","html":"<p>…</p>"}'

Keys are scoped to your team. Semantics:

  • First request with a key sends normally and records the resulting email.
  • Replays return the original email object: same id, no second send.
  • Concurrent duplicates don’t race: while the first request is still in flight, a second request with the same key gets a 409 idempotency_in_progress; retry it and you’ll receive the cached result.
  • If the first request fails, the key is released, so a retry with the same key can send.

Use a key that encodes the business action (“order-123-receipt”), not a random value per attempt.

POST /emails/batch does not support idempotency keys.