Idempotency

Txtly supports idempotent requests to prevent duplicate operations. This is especially useful when dealing with network retries or uncertain request states.

Idempotency Key

To make a request idempotent, include an Idempotency-Key header with a unique identifier:

How It Works

When you send a request with an Idempotency-Key:

• •The key is stored on the created resource (scoped to your team)
• •If you send the same key again, you'll receive the existing resource back instead of a duplicate being created
• •The operation is only performed once, regardless of how many times you retry
• •Keys do not expire — reuse a key only when you intend to reference the same logical operation

Example Usage

Here's how to use idempotency keys to safely retry email sends:

curl -X POST https://api.txtly.com.au/v1/emails \
  -H "Authorization: Bearer tx_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: email_send_2026_03_21_12345" \
  -d '{
    "to": ["user@example.com"],
    "from": "noreply@yourdomain.com",
    "subject": "Welcome to Txtly",
    "html": "<p>Hello! This is your first email.</p>"
  }'

If the request times out or fails, you can safely retry with the same Idempotency-Key header. The API will return the same response and won't send the email twice.

Generating Keys

Use a unique, deterministic value for each operation. Good strategies include:

• •UUIDs: Generate a v4 UUID for each operation
• •Request hashes: Hash the request body to create a deterministic key
• •Business logic IDs: Use domain-specific identifiers like order IDs or user+timestamp combinations

Supported Endpoints

The Idempotency-Key header is supported on the send endpoints: POST /v1/emails, POST /v1/sms, and POST /v1/whatsapp/messages. Other endpoints ignore the header.