Idempotency

Retry safely: the same request with the same key never sends or charges twice.

Why it matters

A network can fail after your request reached Sendd. Retrying with the same X-Idempotency-Key returns the first answer instead of creating a second message or charge.

The rules

X-Idempotency-Key is required on POST /v1/messages, POST /v1/campaigns, POST /v1/campaigns/{id}/quote, POST /v1/campaigns/{id}/launch and POST /v1/wallet/top-ups.
A key is 1 to 255 printable ASCII characters and may not start with campaign:.
Keys are scoped to your organization, the operation and the request body.
Same key, same body: the original response, with the header X-Idempotent-Replay: true.
Same key, different body: 409 idempotency_conflict.

Choosing keys

Derive the key from your own record (for example the order id and the event), or generate a UUID and save it with the record before you send, so a retry after a crash reuses it.

Example · shell

curl -X POST "$SENDD_API_URL/v1/messages" \
  -H "Authorization: Bearer $SENDD_API_KEY" \
  -H "X-Idempotency-Key: order-1042-ready" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+255712345678",
    "from": "SENDD",
    "body": "Your order #1042 is ready for pickup.",
    "client_ref": "order-1042-ready"
  }'

Next: Quickstart