123eworld Knowledge Hub → SMS API → Page 314
SMS API Queue Architecture: Designing Reliable SMS Processing Workers
A practical developer reference designed to solve real implementation and production problems around sms api queue architecture: designing reliable sms processing workers.
Why queues are central
Queues decouple API request processing from provider latency. They absorb bursts and allow workers to control downstream throughput.
Queue selection
Choose a queue technology based on durability, ordering, throughput, retry and operational requirements. Avoid selecting purely on benchmark throughput.
Message envelope
A queue item should contain logical message ID, attempt context, tenant/application scope, priority, configuration version and retry metadata.
Visibility and acknowledgement
Workers should acknowledge queue items only after the necessary state is durably recorded. If a worker crashes, the item should become available for safe recovery.
Retry queues
Use bounded retry schedules and dead-letter handling. Do not allow poison messages to cycle indefinitely.
Concurrency
Worker concurrency should respect provider and tenant limits.
Priority
Separate or priority-aware queues can protect transactional traffic from campaign traffic.
Ordering
Do not promise global ordering unless the architecture can truly provide it. Per-tenant or per-conversation ordering may be a more practical requirement.
Idempotency
Workers must tolerate duplicate queue delivery because many queue systems provide at-least-once processing.
Monitoring
Measure queue age, throughput, retry volume and worker utilization.
Graceful shutdown
Workers should stop accepting new work and finish or safely release current work during deployment.
Reference architecture
API → durable queue → worker pool → routing → provider adapter → result event → state update.
Practical implementation guidance
Design the public API around a stable logical message ID and keep provider-specific complexity behind internal adapters. Every asynchronous step should be durable, observable and safe to retry.
Security and privacy
Treat phone numbers, message content, credentials and delivery evidence as sensitive. Apply tenant authorization before data access and avoid unnecessary values in logs, traces and reports.
Developer-first principle
A useful reference page should tell developers not only what a feature is, but how to implement it safely, how to troubleshoot it and what failure cases to expect.
Related 123eworld guides
Explore the 123eworld SMS & WhatsApp Knowledge Hub for related API, routing, reliability and developer guides.
Queue semantics
Choose at-least-once processing when reliability is more important than strict exactly-once claims. Design workers to be idempotent instead of assuming the queue will deliver each item once.
Visibility timeout
A worker should receive a lease or visibility window long enough for normal processing. If the worker crashes, the item should become available again. The timeout should be based on observed provider latency rather than an arbitrary short value.
Poison messages
Malformed or permanently invalid queue items should be isolated after bounded attempts. Otherwise one bad item can consume worker capacity repeatedly.
Worker scaling
Scale workers based on queue age and processing latency, not queue depth alone. A queue with millions of quickly processed items may be healthier than a small queue containing stalled work.
Priority queues
Protect OTP and transactional traffic with separate queues or explicit priority scheduling. Test starvation so bulk traffic still makes progress.
Provider backpressure
Workers should reduce concurrency when providers throttle or slow down. Queue systems are buffers, not permission to exceed downstream limits indefinitely.
Graceful deployment
Workers should stop taking new work, finish safe operations or release leased items and then exit. This reduces duplicate processing during deployments.
Dead letters
Dead-letter queues should retain the original message ID, failure reason and attempt history. Reprocessing should be controlled and auditable.
Ordering
If ordering is required for a specific business key, use partitioning or keyed queues rather than promising global ordering.
Monitoring
Track queue age, throughput, retry count, dead letters, worker utilization and provider response time.
Exactly-once illusion
Trying to guarantee exactly-once processing across queues, databases and providers can create unrealistic complexity. A more practical design is durable at-least-once delivery plus idempotent state transitions and provider reconciliation.
Worker leases
Set lease duration based on real processing time. If provider calls can occasionally take longer, use lease extension or safe timeout handling rather than allowing the same item to be processed concurrently.
Backpressure signals
Workers should observe provider throttling and queue age. If downstream capacity drops, worker concurrency should reduce automatically or according to controlled configuration.
Queue partitioning
Partition by tenant, priority or routing domain when needed. Partitioning can improve isolation, but too many partitions can create uneven utilization and operational complexity.
Worker idempotency
A worker should mark processing state carefully. If it submits to a provider and crashes before recording the result, the next worker must detect the uncertain attempt through reconciliation rather than automatically creating a second provider submission.
Queue priority fairness
Priority scheduling should include safeguards so low-priority traffic is not starved forever. Weighted fairness or reserved capacity can provide both urgency and predictable progress.
Deployment drain
During deployment, stop fetching new queue items first. Allow safe operations to finish and release any uncertain items back to the queue. This reduces duplicates caused by abrupt worker termination.
Queue recovery drill
Periodically test restoring or recovering queue consumers from a controlled failure. Confirm that no accepted message disappears and that duplicate processing remains safe.
Queue checklist
Test duplicate delivery, worker crash, provider timeout, poison messages, retry exhaustion, graceful shutdown and queue recovery. Measure oldest message age during every significant load test.
Reference principle
A queue is a reliability boundary. It should absorb bursts, enforce controlled downstream pressure and preserve accepted work through ordinary worker failures.
Advanced production guidance
Queue workers should treat every provider call as a potentially uncertain distributed operation. A successful HTTP response can be recorded, but a timeout does not prove that the provider rejected the message. If the worker crashes after the request reaches the provider, the queue may redeliver the item. The worker therefore needs an attempt record and reconciliation logic before deciding to submit again. This design is more important than choosing a particular queue product. Durable storage, idempotent processing, bounded retries and clear attempt state are the foundations that make any queue architecture safe for SMS delivery.
Reference architecture detail
Queue capacity should be planned from downstream throughput rather than HTTP request volume alone. A single API request can contain many messages, and a single logical message can contain several SMS segments. Workers must therefore control physical submission volume as well as request count. Provider throttling, tenant limits and segment count can all affect effective throughput. Queue metrics should show both logical messages and useful workload indicators so capacity decisions are based on actual processing effort.
Final production checklist
Queue recovery should be part of normal operational testing. Confirm that a worker restart, deployment or temporary provider outage does not lose accepted work. The recovery procedure should be deterministic enough that an on-call engineer can execute it without manually reconstructing message state.
Advanced reference note
A queue architecture should also protect against a slow downstream provider. If provider calls begin taking much longer, worker threads can become occupied even when request volume is unchanged. Timeouts, concurrency limits and circuit-like controls prevent one provider from consuming every worker. The remaining capacity can continue processing eligible routes or other message classes. This is an important form of backpressure: the queue absorbs work temporarily, but the worker system still respects the real capacity of downstream dependencies.
Final reference guidance
Measure queue processing in both logical messages and physical workload. Segment-heavy SMS can consume more provider capacity even when logical message counts remain constant. Capacity dashboards should therefore reflect the actual work being performed.
Implementation safeguard
When a queue item becomes permanently invalid, record the reason before moving it to a dead-letter state. This makes later investigation and controlled replay possible without reconstructing the original failure from incomplete logs.
Operational control
Queue retry policies should include an upper bound on attempts and a maximum age. A message that remains retryable forever can consume capacity long after its business value has disappeared. Dead-letter handling should preserve evidence while removing the item from the active processing path.
Final control
Monitor dead-letter volume as a first-class reliability metric, not only as an engineering log.