Queue outbound texts in your own app, don't call the SMS API from the request that triggers them. Write a row to a durable queue, let a worker drain it at a rate your campaign can actually deliver, and send each row with an idempotency key so a retry never double-sends. That one decision protects your web requests, your customers' opt-out rates and your carrier standing at the same time.

This post is for the engineer building texting into a platform that sends on behalf of many customers. We make Ready, so the API calls use its shapes, but the queue design applies to any provider. For the receiving side, see receiving texts with webhooks.

Why you need your own queue

A provider's API isn't a buffer. If your code sends a text inside a web request, three things go wrong:

  • A slow or failed call blocks the user. A timeout during a checkout or a form submit turns an SMS problem into a product outage.
  • A burst becomes a flood. One customer imports 20,000 contacts and triggers a welcome text for each. Every other customer's one-off reminders now wait behind them, or get refused.
  • A retry becomes a duplicate. The request times out, the framework retries, and a person gets the same text twice.

A queue separates "this text should be sent" from "this text is being sent right now". The first is a database insert that can't fail in a way the user sees. The second is a worker's job, and it can be slow, retried and paced.

The shape of the queue

Keep it boring. A table in your existing database is enough for most platforms, and it means the "should send" row can be written in the same transaction as the event that caused it.

A workable row holds:

ColumnWhy it exists
tenant_idWhich of your customers owns the text. Needed for fairness and metering.
to, bodyThe send payload, in E.164 for the number.
idempotency_keyA UUID created when the row is inserted and never changed.
statequeued, sending, sent, held, refused or failed.
not_beforeThe earliest time a worker may try it. Drives retries and quiet-hours holds.
attemptsA counter, so you can stop after a few tries and alert a human.

The key point is that the idempotency key is created with the row, not with the attempt. Every retry of that row sends the same Idempotency-Key header, and the API won't send the text twice. Idempotency keys and duplicate texts covers the failure cases.

Workers claim rows with a lock that skips rows other workers hold, such as SELECT ... FOR UPDATE SKIP LOCKED in Postgres, and move them to sending in the same statement. Without that, two workers can pick the same row.

Rate limiting: where the real limit lives

Your API key isn't the main limit. Carriers cap throughput per campaign, and the figures are approximations because carriers publish no official rate card. A fresh standard campaign with no vetting sends roughly 1 to 4 segments per second. Higher use-case tiers reach tens, roughly 10 to 75. T-Mobile also applies a daily brand cap by trust score, from about 2,000 up to about 200,000 messages a day. SMS API rate limits explains where each limit sits.

So your drain rate has to match the registered campaign, not your server's capacity. A worked example, with stated assumptions:

  • Assumption: a customer's campaign sends at 3 segments per second, and a promo text is 2 segments.
  • That customer's queue drains about 1.5 texts per second, or 90 texts a minute.
  • A 6,000-text campaign takes about 67 minutes, and that's the floor, not a bad day.

If your queue pushes faster than the campaign's rate, the extra texts don't arrive sooner. They get throttled or filtered downstream, and you lose the ability to say when a text was actually sent.

One queue per tenant, one fair scheduler

If every customer's texts share one first-in, first-out queue, the largest sender sets everyone's latency. Give each tenant its own logical queue and a pace that reflects that tenant's own registered campaign. A simple version:

  1. Each tenant has a token bucket sized to its assumed segments-per-second rate.
  2. The scheduler walks tenants round-robin and takes the next row from any tenant whose bucket has tokens.
  3. A text costs tokens equal to its segment count, so a long text with an emoji takes more than a short plain one.
  4. One-to-one transactional texts, such as a code or a reminder, go in a higher-priority lane than bulk. One customer's campaign must not delay another customer's appointment reminder.

This is where Ready's sub-accounts help. Each customer gets its own numbers and its own carrier registration, so a tenant's pace in your scheduler lines up with a real, separate sender on the other side. The multi-tenant SMS architecture post covers that isolation in more detail.

Count segments the way the bill does. A segment holds 160 GSM-7 characters, or 153 once a text runs longer. An emoji or other non-GSM character drops the limit to 70, and 67 on a longer text. Ready swaps curly quotes, long dashes and ellipses for plain ones before sending, so those never change the count.

Use bulk and schedule calls where they fit

Not everything needs a row-by-row send. Three other endpoints shorten the queue's work, and the queue design below is for one-to-one transactional texts:

  • Bulk: POST /v1/messages/bulk sends the same text to up to 100 numbers per call. Use it when a tenant's job is the same message to a list, and split bigger lists into batches. Give each batch its own idempotency key and store it before the call.
  • Schedule: POST /sms/schedule takes message, send_at (ISO 8601 with Z or an offset) and contact_id or to, for one text to one contact at a later time. Nothing is charged until it sends.
  • Campaigns: for a scheduled message to a list, call POST /campaigns with the audience and scheduled_at (see the campaigns API). Ready sends it over time at your account's sending speed, waits for sending hours and reports progress, so a list send needs no queue of your own.

The worker's send call for a single row stays small:

curl -X POST https://api.tryready.com/v1/messages \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Idempotency-Key: 7d1f0c1e-0e2c-4f6e-9a10-3f5b6c7d8e9f" \
  -H "Content-Type: application/json" \
  -d '{"to": "+12125550199", "body": "Your appointment is tomorrow at 3 PM.", "consent_attested": true}'

The key shown is a placeholder. In your worker it's the row's stored key, the same on attempt one and attempt four.

What the worker does with each answer

Decide the next state from the response, and write it down before you move on.

  • Accepted: mark the row sent. The text is charged when it goes out.
  • Timeout or dropped connection: leave the key unchanged and set not_before to a later time with exponential backoff and jitter. If you can't tell whether it went out, read GET /v1/messages before you give up.
  • 429: back off, and lower the tenant's token bucket rate for a while.
  • 409 QUIET_HOURS_BLOCK: an API text is held only if the window opens within 6 hours. Otherwise it isn't sent. Set the row to held, set not_before to when the window opens, and send it then. This is expected behavior, so don't count it as a failure or page anyone.
  • Refusal for an opted-out number, a Ban list number or a known landline: mark refused and stop. These aren't charged, and they never succeed on retry.
  • Any other 4xx: mark failed and surface the response body. A malformed payload won't fix itself.

The error reference has the exact codes.

Quiet hours deserve one more sentence. Campaigns, drip campaigns and automations inside Ready wait up to 24 hours for the window, but your own one-to-one API sends don't get that treatment, so point list and scheduled sends at the campaigns API. For the one-to-one queue, a queue that ignores recipient local time will fill with held rows at 9 PM. Check the window yourself before you claim a row, and you'll save the round trips.

Keep the queue honest

Three small habits stop a queue from becoming a liability:

  • Check opt-outs before enqueueing for older data. Ready refuses opted-out numbers up front, but when you migrate lists from another tool, check GET /v1/opt-outs/:phone first.
  • Cap age. A "your code is 4821" text that sat in a queue for ten minutes is worse than no text. Give each row an expiry and drop it when it passes.
  • Alert on depth and age, not just errors. A queue that's quietly growing is the earliest sign a tenant's pace is set too high.

Also keep PHI out of queued bodies. Ready isn't HIPAA compliant and doesn't sign BAAs, and a queue table is one more place sensitive text would sit.

The practical takeaway

Treat an outbound text as a row first and an API call second. Create the idempotency key with the row, pace each tenant to its own registered campaign instead of your server's speed, and give every answer from the API a defined next state, including the quiet-hours hold that isn't an error. When you want to try the sends, sign up, and read the messages reference for the full request and response shapes.