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 API stores the request and its response for 24 hours
• •If you send the same key again within 24 hours, you'll receive the cached response
• •The operation is only performed once, regardless of how many times you retry
• •After 24 hours, the idempotency key expires and a new request with the same key will be treated as a new operation

Example Usage

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

curl -X POST https://api.txtly.com.au/emails \
  -H "Authorization: Bearer tx_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: email_send_2024_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

Idempotency is supported on all state-changing endpoints (POST, PATCH, PUT requests). GET and DELETE requests do not support idempotency keys.