Preventing Duplicate Messages with Idempotency Keys

A request can time out after Blocx has accepted your message. If your application submits a fresh request, the recipient could receive the same message twice.

The optional Idempotency-Key header lets your application retry a submission while preserving its original message identity. Use it on POST /messaging/send for SMS, MMS, and sandbox messages. Email and 2FA verification requests do not currently support this header.

How it works

Give each message and recipient a unique key, then save that key alongside the request body before sending. Every retry of that message uses the same key and body.

Once a request completes, Blocx saves its HTTP status and response body. A retry returns that response with Idempotency-Replayed: true and the same message ID. It does not create another message, reserve funds again, or consume sending quotas again. Each HTTP attempt still gets its own X-Request-Id for troubleshooting.

For example, an order notification might use order-1042-dispatched-recipient-17. Retrying that notification keeps the key. A notification for another recipient, or a later event on the same order, gets a different key.

Choosing a key

Use a UUID generated when you create the sending job, or an identifier that combines the event and recipient. Follow these rules:

Records are retained for at least 90 days from the first request. Retrying does not extend that period. Never recycle an old key for a new message, or rely on deduplication after the retention window.

Sending a message with a key

Use your normal authentication headers and add Idempotency-Key:

curl -i https://api.otterblocx.com/messaging/send \
  -H "x-access-key-id: $BLOCX_ACCESS_KEY_ID" \
  -H "x-secret-access-key: $BLOCX_SECRET_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-dispatched-recipient-17' \
  -d '{
    "from": "+15551234567",
    "to": "+15557654321",
    "body": "Your order has shipped.",
    "type": "SMS"
  }'

Use a provisioned sender on your account, or follow the sandbox guide for a test send. Replace the example key for each new notification.

If the connection drops, repeat the request with the same key and body. When you receive 202 Accepted, save the returned messageId and stop submitting that message. Blocx processes it asynchronously; track delivery through webhooks or message history.

A replayed 202 remains the original acceptance receipt even if the message has since finished processing. Replaying a request does not fetch its latest delivery status.

Handling retries and errors

Read the response's code as well as its HTTP status. Several different situations return 409.

Response What to do
202 Accepted Save messageId and stop submitting. Follow delivery separately.
400 invalid_idempotency_key Correct the key format. This request did not start a send.
409 idempotency_conflict The key belongs to different content. Recover the original body to retry that message. Use a new key only for an intentional separate message.
409 idempotency_in_progress The first request is still preparing. Wait for the number of seconds in Retry-After, then retry the same key and body.
503 send_outcome_unknown, timeout, or connection loss The request may have been accepted. Retry only the same key and body, or look up its message ID.
409 send_outcome_unknown Preparation was interrupted and needs investigation. Contact support with the message ID and request ID; do not create a replacement send.
Definitive rejection before sending, such as 402 or 429 Fix the cause, then use a new key for the corrected attempt. The original key keeps replaying its rejection.

For instance, if a request is rejected for insufficient balance, topping up does not change the response saved under its key. After funding the account, create a new attempt with a new key. Only do this when the original request was definitively rejected. A timeout or 5xx response alone does not establish that nothing was sent.

Authentication and request-body validation happen before a key is claimed. Their failures are not saved as keyed responses.

Checking an uncertain send

If you have a message ID, check GET /messaging/sends/{messageId} with your normal authentication headers. The lookup requires the messages.send permission and remains available when billing prevents new sends.

curl "https://api.otterblocx.com/messaging/sends/$MESSAGE_ID" \
  -H "x-access-key-id: $BLOCX_ACCESS_KEY_ID" \
  -H "x-secret-access-key: $BLOCX_SECRET_ACCESS_KEY"

Set MESSAGE_ID to the value returned in the response body or X-Message-Id header. The lookup reports submission and processing state:

State Meaning
READY The message is prepared, but queue acceptance is unconfirmed. A retry with the same key can recover the submission.
QUEUED / SENDING The message is waiting for processing or has an active provider attempt.
ACCEPTED / REJECTED The provider outcome is recorded while message history is being updated.
SENT The provider accepted the message. Handset delivery is reported separately.
FAILED The provider definitively refused the send.
UNKNOWN The provider may have accepted it. Automatic resend is blocked while the outcome is investigated.

A 404 does not prove that a message was never sent: its record may be unavailable, expired, or from before this feature was introduced. For an unresolved outcome, retain the original job and contact support with the key, message ID, and request IDs. Request IDs can be traced in Developer → API Logs.

Requests without a key

The header is optional. Without it, each API submission is an independent send, even when the body is identical. Adding a key after an unkeyed request times out cannot deduplicate that earlier request. Include the key on the first attempt whenever your application may need to retry.

Related articles