Skip to content
Teamander Mail

Idempotency

Network failures leave you unsure whether a send succeeded. Retrying blindly risks sending the same email twice. Pass an Idempotency-Key header to make retries safe: a key that already produced a send returns the original result and never sends again.

Terminal window
curl https://mail.teamander.com/v1/emails/send \
  -H "Authorization: Bearer $TEAMANDER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-receipt" \
  -d '{ "to": "jane@example.com", "template_id": "receipt", "data": { "name": "Jane" } }'

How it works

Section titled “How it works”

  • Choose a key that is unique to the logical send — e.g. an order ID plus the email type (order-1234-receipt). Reusing a key for a genuinely different email returns the first email’s result, not the new one.

  • On a first request the send is queued and returns 201.

  • A repeat with the same key returns 200 with idempotent_replay: true and the original recipients — no new email is queued:

    {
      "queued": [
        { "id": "a1b2c3d4-...", "recipient": "jane@example.com", "status": "sent" }
      ],
      "idempotent_replay": true
    }

  • Idempotency is scoped per account and per recipient. Concurrent requests with the same key are safe — one wins and the others return its rows.