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, broadcast, or batch 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

Important: Only successful sends consume the idempotency key. If a send fails (network error, insufficient credits, compliance rejection, etc.), the key remains available and the request can be safely retried with the same key.

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.

Dedup window

Idempotency keys are tracked for 48 hours from the time the message is successfully sent. After 48 hours, the same key can be reused to send a new message. This applies to all levels: single message keys, broadcast/batch-level keys, and per-recipient keys.

Broadcast & batch idempotency

Both broadcast and batch requests support two levels of idempotency:

• Request-level key: An idempotencyKey on the request prevents the entire broadcast or batch from being submitted twice. If not provided, a unique key is auto-generated (no dedup protection without an explicit key).
• Per-recipient key: An idempotencyKey on individual recipients prevents duplicate messages to specific recipients across retries.

Broadcast example

{
  "from": "+18005559876",
  "body": "Flash sale! 20% off today only.",
  "idempotencyKey": "promo-campaign-2026-05",
  "recipients": [
    {"to": "+18005551001", "idempotencyKey": "promo-user-1001"},
    {"to": "+18005551002", "idempotencyKey": "promo-user-1002"}
  ]
}

Batch example

{
  "from": "+18005559876",
  "idempotencyKey": "order-batch-2026-05-01",
  "recipients": [
    {"to": "+18005551001", "body": "Hi Alice, order shipped!", "idempotencyKey": "order-1001"},
    {"to": "+18005551002", "body": "Hi Bob, order ready.", "idempotencyKey": "order-1002"}
  ]
}