Retry failed SMS campaign items without double-delivering

Retrying failed SMS dispatches requires strict reconciliation of delivery receipts to prevent double billing. A delayed webhook often masks successful delivery as a timeout error. Always verify DLR ledger states and use idempotency keys before re-triggering the JIT dispatch pipeline.

Anatomy of a failed SMS item

When running white-label prepaid CPaaS campaigns, network drops and carrier timeouts cause certain items to fail. Operators need a clear view of dispatch states before triggering any retry logic. A failed item might return an upstream error or time out entirely while queued in the JIT dispatch pipeline. Before taking any action, systems must reconcile delivery receipts (DLR) to ensure you do not confuse delayed carrier feedback with a permanent failure.

The danger of double delivery and double billing

The most critical risk in manual or automated campaign retries is sending the exact same text twice and triggering a double charge. If a webhook reports a timeout, the carrier might still deliver the message minutes later. Blindly pushing the entire batch through a requeue script will instantly bill your client twice for the same content. Protecting against this requires checking ledger states and idempotency keys before dispatch.

Reconciling DLR lag versus actual delivery states

Network congestion often leads to delayed status reports, making it look like a message failed when it was merely stuck in queue. Understanding the gap discussed in DLR lag vs API accepted: stop burning prepaid on late receipts is vital for retry safety. If an aggregator accepts an API request but delays the final status callback, treating it as a failure too early will trigger duplicate sends. Operators must implement a grace period where pending states are held.

Safe payload hashing and idempotency keys

To prevent duplicate execution at the network level, every outbound SMS request requires a unique idempotency key. When a campaign item fails and enters the retry queue, the system generates a salted hash combining the recipient E.164 number, campaign ID, and timestamp. If a duplicate webhook arrives with the exact same hash, the billing engine drops it instantly, preventing secondary ledger debits. This pattern mirrors protections outlined in Duplicate webhook must not create a second debit.

Handling partial batch failures during failover

When a primary route degrades, traffic shifts to a backup route, often resulting in mixed batch results where half the messages succeed and the other half stall. Managing these fragmented runs safely requires isolating the failed subset without disrupting the active pipeline.

Start with IOSOR

Open the IOSOR console and enable payload idempotency hashing across your campaign retry pipelines to block duplicate dispatches automatically. Set a compulsory DLR reconciliation hold period before any message is flagged as permanently failed for requeueing. Isolate partial batch failures directly from the dispatch queue logs so only unconfirmed E.164 destinations are reprocessed.

IOSOR takeaway

Retrying failed campaign items without strict idempotency and DLR lag reconciliation directly leads to duplicate message delivery and wasted prepaid funds. Blindly re-executing entire batches during route failovers creates overlapping traffic that degrades carrier trust and alienates recipients with duplicate texts.

Do implement salted idempotency keys combining recipient numbers and campaign identifiers to drop duplicate dispatches at the gateway level. Don't trigger automated requeue scripts immediately upon API timeouts without checking delayed delivery receipts or isolating exact failed sub-batches.