123eworld Knowledge Hub → Transactional SMS API → Page 258
Transactional SMS API Delivery Guarantees: At-Least-Once Processing, Duplicates and Reconciliation
A practical developer reference focused on solving real implementation and production problems around transactional sms api delivery guarantees: at-least-once processing, duplicates and reconciliation.
What delivery guarantees mean
Distributed messaging cannot honestly promise handset delivery from an API acceptance alone. The platform should define guarantees separately for API acceptance, logical message creation, provider submission, delivery-status processing and webhook delivery.
At-least-once processing
Queues and workers commonly use at-least-once processing because durable retry is more important than pretending duplicates cannot occur. The system must therefore make operations idempotent where duplicate processing is possible.
Duplicate submissions
A worker can crash after provider submission but before recording the result. A restart may attempt the same message again. Provider-level idempotency, message correlation or reconciliation can reduce this risk.
Duplicate webhooks
Network retries can cause the same delivery event to reach a customer more than once. Event IDs allow consumers to deduplicate safely.
Exactly-once limitations
Exactly-once end-to-end delivery is difficult because the platform, provider network, handset and customer webhook system are separate failure domains. State the strongest guarantee that can actually be enforced.
Reconciliation
When local and provider state disagree, reconciliation compares message IDs, provider IDs, attempts and delivery reports. It should resolve uncertain outcomes without blindly creating new messages.
State machine
Use explicit states such as accepted, queued, submitted, delivered, failed and unknown. State transitions should be monotonic where possible and should tolerate duplicate events.
Business consequences
For payments, alerts and orders, duplicate SMS can confuse users. The application should therefore generate one logical notification and let the messaging layer track attempts separately.
Observability
Measure duplicate processing, uncertain outcomes, reconciliation cases and late delivery reports. These are reliability indicators, not merely exceptions.
Testing
Test worker crashes, duplicate queue deliveries, duplicate DLRs, webhook retries and provider responses that arrive after local timeouts.
Documentation
Explain what each API response means and what customers should do after timeout, retryable error or duplicate webhook.
Reference principle
Guarantee logical identity strongly; process distributed work safely; reconcile uncertain downstream outcomes; never claim guarantees the architecture cannot enforce.
Production architecture
A reliable transactional SMS API separates synchronous API admission from asynchronous delivery processing. The API validates input, authenticates the tenant, applies quotas and creates a durable logical message. Queue workers then perform provider interaction, retries and status processing. This separation keeps customer HTTP requests fast while allowing downstream work to recover from temporary failures.
Security and tenant isolation
Every operation should remain scoped to the authenticated tenant. API credentials, templates, sender identities, message records, webhooks and reporting data must not cross tenant boundaries. Logs and support tools should expose only the minimum information needed for diagnosis.
Observability
Use request IDs, message IDs, provider attempt IDs and event IDs to connect the lifecycle. Monitor latency, queue age, provider errors, retry counts, delivery outcomes and resource saturation. Good observability should answer what happened, where it happened and what the system will do next.
Failure handling
Design for timeouts, duplicate requests, duplicate callbacks, provider outages, worker restarts and partial failures. Idempotency and reconciliation are essential because distributed systems cannot always know whether a remote operation completed before a local failure.
Developer experience
Documentation should provide request examples, response schemas, error codes, retry guidance, limits and production checklists. Developers should understand the difference between API acceptance, provider submission and final handset delivery.
Testing and release
Use unit, contract, integration, load, security, failure-injection and end-to-end tests. Include realistic edge cases and turn production incidents into regression tests. A feature should not be considered complete until its failure behaviour is documented and tested.
Practical checklist
Before production, verify authentication, authorization, rate limits, idempotency, queue durability, provider routing, timeout policy, observability, data retention, reconciliation, backup and recovery procedures. Test both normal traffic and realistic dependency failures.
Knowledge-base connection
This guide is part of the 123eworld developer knowledge base. Continue through the 123eworld Knowledge Hub for related SMS API, gateway, security, reliability and integration topics.
Acceptance versus delivery
The first guarantee customers usually need is that an accepted API request has a durable logical message identity. That is different from guaranteeing that a handset will receive the SMS. The knowledge-base documentation should make this distinction prominent.
At-least-once workers
At-least-once queue processing is a practical reliability model. Workers may process the same job after a crash or lease timeout, so provider adapters and message state must tolerate repeated attempts.
Deduplication windows
Where a provider offers message deduplication, understand the scope and retention of that mechanism. Do not assume a provider's deduplication covers every possible retry interval.
Reconciliation schedule
Unknown outcomes should enter a reconciliation workflow. Reconciliation can query provider status, process delayed delivery receipts and resolve local records that were left uncertain by a timeout.
Customer webhooks
Webhook consumers should store event IDs before acknowledging events when duplicate business processing would be harmful. The platform should document that duplicate callbacks can occur.
Guarantee language
Use precise phrases such as durable acceptance, at-least-once processing and best-effort downstream delivery where appropriate. Avoid marketing language that creates an impossible technical promise.
Reliability evidence
Track duplicate prevention, uncertain outcomes, reconciliation success and late callbacks. These metrics show whether the guarantee model is working in production.
Consumer contract
Document duplicate-handling requirements for customer webhook consumers. A customer can persist event IDs with a uniqueness constraint so the same logical delivery event does not trigger a second business action.
Reconciliation safety
Reconciliation should never convert an uncertain message into a new message automatically unless the business policy explicitly allows it. Its primary purpose is to determine what happened to the existing logical operation.
Monitoring guarantee health
Alert on unusual growth in unknown states, duplicate provider attempts, reconciliation backlog and duplicate webhook events. These indicators can reveal a dependency problem before customers notice inconsistent statuses.
Reference documentation
Include a lifecycle diagram in the developer documentation showing the difference between request acceptance, queue processing, provider attempts, delivery receipts and customer webhook delivery.
Production implementation guidance
The strongest practical delivery architecture is built around explicit boundaries: durable logical message creation, at-least-once internal processing, controlled provider attempts, asynchronous delivery receipts and idempotent customer webhook consumption. Each boundary has a different failure model. A queue may redeliver a job; a provider may accept a submission before the client times out; a delivery receipt may arrive late; and a webhook may be delivered twice. Trying to hide these realities behind a single 'delivered' Boolean creates fragile integrations. Instead, the platform should expose stable IDs and well-defined state transitions and provide reconciliation for uncertain outcomes. Customers should use idempotency when retrying requests and event IDs when processing callbacks. Operational teams should monitor unknown states and duplicate events because they are signals of distributed-system pressure. This model is both more honest and more resilient than promising an impossible exactly-once end-to-end guarantee.
Final production checklist
Before release, verify logical message identity, duplicate queue processing, provider timeout handling, duplicate delivery receipts, webhook deduplication, reconciliation and documented guarantee language. Test every uncertain-outcome path so the platform never creates a duplicate merely because a remote response was lost.
Operational runbook guidance
A useful guarantee runbook should explain how operators handle an unknown provider outcome, how reconciliation is triggered, how duplicate callbacks are recognized and how customers are informed. It should explicitly prohibit manual resubmission of an uncertain message until the existing logical operation has been investigated.
Design review note
Guarantees should be reviewed whenever the queue technology, provider adapter or webhook architecture changes. A new component can introduce a new duplicate or uncertainty path. Update both documentation and failure tests when the guarantee model changes.
Architecture review
A delivery guarantee should have a corresponding test scenario. If the platform claims duplicate logical messages are prevented, test concurrent retries. If it claims delivery receipts are processed reliably, test duplicates and late events. If it offers webhook retries, test customer endpoint failure and replay. Linking each guarantee to an executable test prevents documentation from drifting away from actual system behaviour.
Final review
The final production review should verify that every asynchronous boundary has a stable identifier and a recovery path. Logical message ID, provider attempt ID and event ID should remain available long enough to reconcile delayed evidence and diagnose duplicates.