Skip to content

Idempotency

Retry a send without fear of messaging the same person twice.

How it works

Add an Idempotency-Key header — any unique string up to 255 characters, typically a UUID — to a send request. Engage stores the successful result of the first request with that key for 24 hours. Repeating the request with the same key and the same body returns the original response without sending again.

The header is honoured on the three endpoints that send messages:

  • POST /v1/messages
  • POST /v1/messages/bulk
  • POST /v1/conversations/{id}/messages

Other endpoints ignore it. Creating a contact twice returns 409 conflict, so those calls are already safe to retry.

Request
curl https://engage.swastik.ai/v1/messages \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Idempotency-Key: 5d2c8f0e-4b6a-4f7e-9c1d-2a3b4c5d6e7f" \
  -H "Content-Type: application/json" \
  -d '{"to":"+14155550101","type":"text","text":{"body":"Your OTP is 482913"}}'

Rules

  • Keys are scoped to the API key that sent them — two different API keys can use the same value without clashing.
  • Reusing a key with a different request body returns 422 validation_failed.
  • If the first request is still in progress, a concurrent retry receives 409 conflict; retry shortly after.
  • Only successful responses are stored. If the first attempt fails (any 4xx or 5xx), the key is released — fix the request if needed and retry with the same key.
  • Keys longer than 255 characters are rejected with 422.

Client references

Messages also accept a client_ref field — your own identifier (for example an order id). Up to 128 characters. It is stored on the message and returned by GET /v1/messages/{id}. Status webhooks identify the message by its Engage id, so keep the id from the send response next to your own reference.

Tip
Derive the idempotency key from your own data — e.g. order-48213-shipped — so retries after a process crash still deduplicate.
Something unclear or missing on this page? Tell us at contact@swastik.ai