Idempotency

Network hiccups happen. The send endpoint accepts an idempotency key so a retried request returns the original result instead of sending again.

The Idempotency-Key header#

Send a unique Idempotency-Key header with your request. Reuse the exact same key when you retry. In the SDK, pass idempotencyKey.

curl -X POST https://app.getdeckle.com/api/v1/send \
  -H "Authorization: Bearer $DECKLE_API_KEY" \
  -H "Idempotency-Key: order_1234_receipt" \
  -H "Content-Type: application/json" \
  -d '{ "from": "Acme <hello@acme.com>", "to": "jane@example.com",
        "subject": "Receipt", "html": "<p>Thanks!</p>" }'

Behavior#

The first request with a given key sends the email and records the result. Any later request with the same key — for this project — skips sending and returns the original result with idempotent: true and a 200 status.

{
  "id": "email_9f2c1a8b",
  "status": "sent",
  "messageId": "0000018f-...-amazonses",
  "idempotent": true
}