To show SMS delivery status in your app, store the message id from each send, update one status field from your provider's delivery webhooks, and map the provider's many statuses to a small set of labels your users understand. The hard part isn't the plumbing. It's the wording, because carriers don't always tell you what happened, and a UI that says "Delivered" or "Failed" when the truth is "we don't know" will cost you support tickets.

This guide is for developers building texting into a product for their own customers. It sticks to what's true of Ready's API and points to the docs for exact event names and fields, which we don't invent here.

Decide on the states your users need

Providers report many statuses. Your users need a handful of words, not twenty. A workable set:

User-facing labelWhat it meansTypical source
SendingAccepted by the platform, not yet handed offSend response, early webhook
SentHanded to the carrier networkWebhook
DeliveredThe carrier confirmed it reached the handset networkFinal delivery webhook
Not deliveredThe send failed after leavingFailure webhook plus error code
BlockedRefused before sendingSend-time refusal
Opted outThe contact asked to stopOpt-out check or inbound STOP
UnknownNo final report arrivedAbsence of a report

Resist adding more. Each label should lead to a different action for the user. If two statuses lead to the same next step, merge them.

Map webhooks to one ordered status

Your provider's webhooks are the source of truth after the initial send. Treat the status as a ladder that only moves forward: sending, sent, then delivered or not delivered. Never let an earlier report overwrite a later one, because events can arrive out of order or twice. Our posts on SMS webhook delivery reports and out-of-order webhooks cover the handler. On Ready, failed isn't always final: Ready resends some failures itself under the same message id, so let a later delivered replace failed (see Failures Ready resends for you). In short:

  1. Verify and store the raw payload.
  2. Look up the message by its id.
  3. Compare the new status rank with the stored one, and update only if it moves forward.
  4. Return a fast 200 and do slow work in a background job.

Use an Idempotency-Key header on each send (POST /v1/messages) so a retried request doesn't create a second text and a second status row. The webhook setup is in the API quickstart.

Blocked is not failed

Some texts never leave. Ready refuses them up front, and a refused text isn't charged. That includes:

  • Numbers that opted out, and numbers on the account's Ban list.
  • A number Ready's own sends have already seen as a landline.
  • Sends during the recipient's quiet hours. An API text is held only if the window opens within 6 hours. Otherwise it isn't sent, and the API answers 409 QUIET_HOURS_BLOCK so your code can tell the user to resend once the window opens. A request with hold_until_allowed set to true holds it up to 24 hours like a campaign text.

Show these as Blocked with the reason in plain words: "Not sent. This contact asked us to stop texting." That's different from a text that left and failed, and users act on them differently. A blocked text needs a changed situation. A failed one might need a corrected number. The error list in the errors docs is the place to map codes to messages, and our post on pre-send refusal UX goes deeper on copy.

Opted out deserves its own state

Don't bury an opt-out inside Failed. When a contact replies STOP, Ready honors it, and clear phrases like "please stop texting me" are caught too. In your UI, show Opted out on the contact and on any message you tried to send afterward, and remove the send button for that contact. Users who see only "Failed" will try again and again.

For a full picture before you send from another tool or after a provider migration, check GET /v1/opt-outs/:phone for the number, since the plain list GET /v1/opt-outs covers only opted-out contacts on that account. See the opt-outs docs.

Honest wording for unknown

Carriers don't always return a delivery report. A text can arrive and still sit at sent forever. So "no report" has to be a first-class state, not a silent fallback to Delivered or Failed.

Good wording:

  • "Sent. The carrier hasn't confirmed delivery yet."
  • After a long wait: "No delivery confirmation. Many carriers don't send one, so this text may still have arrived."

Bad wording: "Delivered" with a green check when you only know it was sent, or "Failed" when you simply never heard back.

Decide the wait yourself. A reasonable pattern is to keep Sent for a window you choose (an assumption, tune it to your traffic), then flip the label to the unknown wording rather than to Failed. Offer a neutral next step: check whether the contact replied, or send a follow-up through another channel. Our post on the delivery receipt versus read gap explains why even Delivered doesn't mean read.

What Delivered should and shouldn't claim

Delivered means a carrier confirmed it reached the handset network. It doesn't mean the person saw it. Keep the label modest: a check mark and the word Delivered is fine, but don't add "Read" or "Seen" for plain SMS. A reply is the real signal of engagement, so show replies in the same thread, and let users filter by "no reply".

Failure messages that help

When a failure webhook arrives, translate the code instead of showing it raw. Group codes into a few causes: bad number, carrier filtering, refused before sending, and temporary trouble. Give each a one-line action.

  • Bad number: "This number may be a landline or out of service. Check it and try again."
  • Carrier filtering: "The carrier didn't accept this message. Contact support." Unregistered traffic is a common cause, which is why registration status belongs in your admin view.
  • Temporary: "We'll show an update if this changes."

Don't promise a retry you don't perform, and don't retry a text that failed because the contact opted out. Our guide for support teams triaging delivery failures is a good companion to hand to your own support staff.

Frequently asked questions

Can I show a read receipt for SMS?

No, not for plain SMS. Carriers don't return read receipts for most texts. Show Delivered at most, and treat replies as your engagement signal.

Why does my message stay at sent?

Some carriers and destination types don't return a final report. The text may have arrived. Show it as sent or unknown, not as failed, and judge by replies.

Should I poll instead of using webhooks?

Use webhooks as the main path because they give timing without extra load. Keep a slow poll only as a backstop for messages that never received a final report.

Where to go next

Start with the seven labels above, one ordered status field and the unknown wording. Add reason text for Blocked and Opted out next, since those cut the most tickets. When you're ready to wire it up, the API quickstart shows the key, a first send and the webhook, and you can create an account to test the whole flow with your own number.