123eworld Knowledge Hub → Transactional SMS → Page 134
Transactional SMS API Message Queue Architecture: Producers, Consumers, Priorities, Backpressure and Dead Letters
A developer architecture guide to message queues in transactional SMS systems, covering producers, consumers, partitions, priorities, backpressure, retries, dead letters, ordering, visibility timeouts and operational capacity.
Why queues are central
Queues separate fast API acceptance from slower provider submission. They absorb short traffic bursts and allow workers to process messages according to available downstream capacity.
Producer responsibilities
The API should validate and persist the logical message before publishing work. An outbox pattern can ensure database state and queue publication remain consistent.
Consumer responsibilities
Workers should claim work, submit through the provider adapter, record the attempt and acknowledge the queue only when the processing contract has been satisfied.
Concurrency
Worker concurrency should be limited by provider capacity, database connections and tenant fairness rather than simply maximizing CPU usage.
Backpressure
When downstream capacity falls, the queue should grow in a controlled way while admission controls prevent unlimited accumulation. Queue age is often the most useful backpressure signal.
Priorities
Critical OTP or security messages may need priority over bulk notifications. Priority should be implemented fairly so lower-priority traffic does not become permanently starved.
Ordering
Some business workflows require ordering by customer or transaction. Partitioning or per-key sequencing can preserve required order while allowing unrelated messages to process concurrently.
Retries
Retry logic should classify provider responses and use bounded backoff. Queue-level retries must work with message-level idempotency.
Dead letters
Messages that cannot be processed safely should move to a dead-letter queue with enough metadata for investigation and controlled replay.
Visibility timeout
If the queue uses a visibility timeout, it must exceed normal processing time or support renewal. Otherwise slow workers can cause the same message to be processed concurrently.
Capacity planning
Measure arrival rate, processing rate, queue age and maximum safe backlog. Capacity should be expressed in customer-visible delay, not only worker count.
Implementation checklist
Define durability, producer transaction boundaries, consumer acknowledgement, concurrency, priorities, ordering, backpressure, retries, dead letters and capacity monitoring.
Transactional outbox
If the message database and queue are separate systems, the API can first persist a message and an outbox event in one transaction. A publisher then safely transfers the outbox event to the queue. This prevents a successful database commit from being lost because queue publication failed immediately afterward.
Consumer acknowledgement
A worker should acknowledge queue work only after the processing contract is satisfied. Acknowledging before provider submission or attempt persistence can cause permanent message loss if the process crashes.
Fair scheduling
Use tenant-aware scheduling so one customer cannot fill all worker capacity. Priority should be combined with fairness controls to prevent either large tenants or high-priority traffic from monopolizing the system.
Queue partitioning
Partition by a stable key when ordering is required, such as tenant plus business entity. Avoid partitions that create extreme hotspots for large customers.
Backlog estimation
A queue of 100,000 messages means little without processing rate. If workers process 10,000 per minute, the backlog is manageable; if they process 500 per minute, customer delay may become unacceptable. Track queue age and estimated drain time.
Developer reference rule
A queue should absorb temporary demand differences without becoming a permanent hiding place for insufficient downstream capacity.
Outbox consistency
The transactional outbox pattern is particularly valuable when message acceptance and queue publication involve different infrastructure. The database transaction records both the message and the intention to publish. A background publisher retries publication until the queue confirms receipt.
Exactly-once misconception
Queues generally provide at-least-once processing more readily than true exactly-once business execution. The application should therefore combine durable logical IDs, idempotent processing and safe acknowledgement rather than relying on an assumption of exactly-once delivery.
Queue priority starvation
If high-priority messages can consume unlimited workers, normal notifications may starve. Implement quotas or weighted scheduling so critical traffic receives preference without making every lower-priority message wait indefinitely.
Queue visibility recovery
Workers that exceed the queue visibility timeout can cause duplicate delivery. Either renew the visibility lease or set a timeout based on measured processing time with a safe margin.
Queue capacity alarm
Alert on oldest-message age and estimated drain time, not only queue depth. A queue of 10,000 messages can be healthy at one processing rate and critical at another.
Practical scenario
A campaign creates a burst of 500,000 messages. The API remains responsive because work enters a durable queue, workers process at provider-safe concurrency, OTP traffic receives priority and queue-age monitoring prevents the backlog from becoming invisible.
Failure scenario
The database transaction succeeds but queue publication fails. An outbox publisher later sees the pending event and publishes it safely. Without the outbox, the accepted message could remain permanently unsent even though the API returned success.
Operational checklist
Verify durable queue configuration, outbox consistency, acknowledgement timing, worker concurrency, fairness, priority, ordering, visibility timeout, backpressure and queue-age alerts.
Developer takeaway
A queue architecture should make failure recoverable at every boundary between persistence and processing.
Design review
Review queue architecture when throughput, priority classes or provider capacity changes. Worker concurrency should be recalculated from downstream limits rather than increased automatically.
Reference note
Use queue age and drain time as customer-impact metrics. Queue depth alone does not describe whether a backlog is safe.
Final standard
Queues should absorb temporary pressure while preserving fairness, durability and controlled recovery.
Implementation example
The API writes a message and outbox record in one database transaction. A publisher transfers the outbox record to the queue. Workers then process the message at provider-safe concurrency. If publication fails, the outbox remains pending and is retried without losing the accepted message.
Testing standard
Kill the publisher after database commit, kill workers before acknowledgement, exceed visibility timeout and create a large burst. Verify no accepted message disappears and duplicate processing remains safe.
Final checklist
Confirm queue durability, producer consistency, consumer acknowledgement and backpressure behaviour under failure.
Capacity example
If provider throughput is 10,000 messages per second, increasing workers beyond the point where that rate is saturated does not improve delivery. It only increases contention, retries or provider throttling.
Support guidance
When queue depth grows, compare arrival rate with processing rate and provider capacity. Adding workers blindly can make the backlog worse if the provider is already saturated.
Reference rule
Scale workers according to downstream capacity and queue age.
Production readiness
Run a burst test while simultaneously reducing provider capacity. Confirm that queue growth remains controlled, OTP or priority traffic is protected and workers do not overwhelm the provider.
Documentation requirement
Document queue semantics, acknowledgement rules, retry behaviour, visibility timeout and priority policy. Developers should understand when an accepted message can still be waiting in the queue.
Long-term maintenance
Review worker concurrency against current provider limits, database capacity and tenant traffic. Queue tuning should be based on measurements rather than static worker counts.
Architecture review
Keep queue publishing, worker processing and provider submission observable as separate stages. This makes it possible to identify whether backlog is caused by API demand, worker capacity or provider limitations.
Final implementation note
Use durable logical message identity across queue retries and worker restarts so at-least-once delivery does not become duplicate business execution.
Final production rule
Do not acknowledge queue work before the durable processing contract has been satisfied.
Reference summary
A durable queue is a reliability boundary only when persistence, acknowledgement, retries, backpressure and worker capacity are designed together.
Developer implementation detail
Use a durable message ID as the key that follows the work through the queue, worker, provider adapter and delivery lifecycle. Queue delivery IDs can change on retries, but the logical message identity must remain stable for idempotency, billing and customer reporting.
Final check
Confirm queue acknowledgement occurs only after durable processing and that worker restarts cannot silently lose accepted messages.
Quality standard
Keep queue backlog measurable through age, processing rate and estimated drain time.
Final reference point
The queue should provide a durable boundary between acceptance and processing while making overload visible early enough for admission control and capacity adjustments.
Final rule
Protect queue durability and acknowledgement boundaries.
Need transactional SMS integration?
123eworld.com provides Bulk SMS and API-based business communication solutions for enterprises and software applications.