SMS API Queue: How to Design for Rate Limits, Priority, and Retries

Every high-volume sender eventually hits the same wall: the application can create messages faster than carriers will accept them. An SMS API queue absorbs that gap. Designed well, it keeps OTPs fast, campaigns steady, and retries free of duplicates. Designed poorly, it lets a marketing blast delay every login code in the system.

What is an SMS API queue?

An SMS API queue is a buffer that holds outbound messages until workers can send them within provider rate limits. Two queues usually exist: one in the sender's application and one inside the SMS provider. The first controls pacing, priority, and retries. The second paces messages per sender number and drops them when they wait too long.

A reference architecture

A reliable setup has five stages:

1. The application writes each send request to a queue and returns immediately.
2. Workers pull messages at a rate below the provider's limit.
3. Each worker calls the SMS API with an idempotency key.
4. The provider queues messages per sender and forwards them to operators.
5. Delivery-report webhooks land in a second queue for processing.

The rule behind stage one is simple: never call the SMS API inside a user-facing request. A slow provider response then becomes a slow login page.

SMS rate limiting and validity periods

SMS rate limiting happens at several layers at once: the account, the sender number, and sometimes the destination country. The application queue should respect the tightest one.

Matching SMS throughput to provider limits

SMS throughput depends on the sender type. In the US, a long code may send one segment per second, while a short code can send over 100. Some countries allow far less.

Count segments, not messages. A 300-character Unicode message uses several segments and consumes several units of capacity. Workers should pace sends by segment count to stay under the SMS throughput the provider actually allows.

Setting validity by message type

Providers drop queued messages after a validity period, and the default is often measured in hours. That's far too long for time-sensitive traffic. We recommend setting validity per message type:

Default limits vary by provider and sometimes between versions of the same provider's docs. Check the current validity setting before relying on it.

Priority lanes: OTP, transactional, and bulk

Separate queues keep urgent traffic moving. A single shared queue behaves like one checkout lane at a supermarket: the customer buying milk waits behind a full trolley. Run at least three lanes:

• OTP, drained first, through a verification service such as an OTP verification API
• transactional alerts
• bulk campaigns, such as bulk SMS broadcasts

For multi-tenant platforms, add fair sharing inside each lane so one customer's campaign can't take over the capacity.

India's promotional send window

In India, promotional SMS reaches non-DND numbers only between 10 a.m. and 9 p.m. The promotional queue should hold messages outside that window instead of sending them to be rejected. OTP and transactional lanes run around the clock. Our guide to SMS API compliance in India covers the category rules in detail.

Retries without duplicates

Retries should fix temporary problems without creating new ones. Classify each failure first:

• Permanent failures (invalid number, opted out, rejected template): stop and flag.
• Temporary failures (timeouts, congestion, rate-limit responses): retry.

Exponential backoff with jitter

Exponential backoff spaces retries further apart each time, for example 2, 4, then 8 seconds. Adding random jitter stops thousands of workers from retrying at the same moment. Cap attempts, and for OTPs, cap total retry time at the code's expiry, since exponential backoff can easily outlast a short code.

Idempotency and dead-letter queues

An idempotency key tells the provider that a repeated request is the same message, not a new one. Without it, a timeout followed by a retry can send the customer two texts. Messages that exhaust their retries should move to a dead-letter queue for review, not disappear.

Monitoring, data, and cost

Track four numbers per lane:

• queue depth
• age of the oldest message
• send rate against the allowed rate
• dead-letter volume

A rising oldest-message age is the earliest warning of trouble.

Queued payloads contain phone numbers and message content. Encrypt them at rest, restrict access by role, and set short retention. OTP payloads should expire with the code.

Managed queues cost less to run than self-hosted clusters at moderate volume. Kafka pays off when delivery events also feed analytics. Legacy systems can publish to the queue through a lightweight adapter, without direct API changes.

Conclusion

A well-designed SMS API queue paces traffic to real provider limits, separates urgent messages from bulk, and retries without duplicates. Set validity by message type, watch the age of the oldest message, and hold promotional traffic for its allowed window. Helo.ai's SMS API supports high-throughput sending with delivery reports for every message.

Frequently asked questions

What does "queued" status mean for an SMS?

"Queued" means the provider has accepted the message but hasn't yet sent it to the operator. Messages usually stay queued when the sender's rate limit is reached. Long queue times signal a need for more throughput or better pacing.

How long can an SMS stay queued before it fails?

Each provider sets a maximum validity period, often several hours, after which queued messages fail. Senders can usually set a shorter validity per message. OTPs should use a validity equal to the code's expiry.

Which message queue is best for sending SMS?

Amazon SQS suits teams wanting a managed service with little upkeep. RabbitMQ handles priority queues well. Kafka fits high volumes where delivery events also feed analytics. Redis works for simpler setups with lower durability needs.

How to send bulk SMS without throttling?

Pace sends below the provider's rate limit, count segments rather than messages, and spread traffic across multiple senders where allowed. Hold promotional messages for permitted send windows instead of pushing them all at once.

Should OTPs have a separate queue?

Yes. A dedicated OTP queue keeps login and payment codes moving during large campaigns. Give it top priority, a short validity period, and retry limits capped at the code's expiry.