Idempotency

Use idempotency keys to safely retry requests without the risk of sending duplicate messages.

How it works

Include an idempotencyKey field in your send or broadcast request. If the API receives a second request with the same key, it returns the original response instead of creating a new message.

{
  "to": "+18005551234",
  "from": "+18005559876",
  "body": "Your order has shipped!",
  "idempotencyKey": "order-12345-shipped"
}

Key format

Idempotency keys must:

Be 2 to 100 characters long
Contain only: letters (A-Z, a-z), digits (0-9), and special characters : @ - _ ) (

Behavior

Scenario	Result
First request with a key	Message is created and sent normally
Repeat request with the same key	Original response is returned; no duplicate message is sent
Request without a key	Message is always created (no idempotency protection)

Best practices

Use meaningful keys that tie back to your business logic, such as order-12345-confirmation or appointment-reminder-2026-03-13.
Don't reuse keys across unrelated messages. Each key should represent one specific send intent.
Always include a key when retrying failed requests due to network timeouts or 5xx errors. This ensures the message isn't sent twice if the first request actually succeeded.

Example: safe retry

# First attempt — might timeout
curl -X POST https://platform.textingline.com/api/v1/messaging/message \
  -u "your_key_id:your_key_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+18005551234",
    "from": "+18005559876",
    "body": "Your code is 482910",
    "idempotencyKey": "verify-user-789-attempt-1"
  }'

# Safe retry — same key, same result, no duplicate
curl -X POST https://platform.textingline.com/api/v1/messaging/message \
  -u "your_key_id:your_key_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+18005551234",
    "from": "+18005559876",
    "body": "Your code is 482910",
    "idempotencyKey": "verify-user-789-attempt-1"
  }'

Both requests return the same msg_ ID.