A delivery report is a message your SMS provider sends to your server, usually as a webhook, to say what happened to a text after you sent it. "Delivered" means the destination carrier accepted the message. It doesn't mean the person saw it.
That gap is where most bad assumptions start. This guide explains the statuses you'll meet across SMS APIs, what each one tells you, and how to build a callback handler that survives retries, late arrivals and out-of-order events. Ready has webhooks built in, but the exact event names and fields live in the docs, so we don't invent them here.
Why a send response isn't a delivery report
The response to your send call only says the provider accepted your request. It's a receipt for the handoff, not for the trip.
After that, the message moves through the provider, onto a carrier network and toward a handset. Each hop can succeed or fail on its own schedule. A webhook is how you hear about the later hops without polling. If you only read the send response, a text that a carrier filtered an hour later still looks fine in your database.
Treat the send response as step one and store the message ID you get back. Every later report is matched to it.
The statuses you'll see
Names vary between providers, but most SMS APIs report some version of these stages:
| Stage | Plain meaning | What to do |
|---|---|---|
| Queued or accepted | The provider has your request and hasn't sent it yet | Nothing, wait |
| Sent | The provider handed it to a carrier | Nothing, wait |
| Delivered | The carrier confirmed it reached the handset network | Mark it done |
| Failed or undelivered | The message didn't arrive | Read the error code, decide on a retry |
Check your provider's docs for its exact status list. For Ready, start with the API quickstart for the webhook setup, and keep the error codes reference open when you're reading failures.
What delivered means, and what it doesn't
Delivered is a carrier-level signal. It says the carrier took the message for that number. It doesn't say the person opened it, read it or acted on it, and SMS has no read receipt for most traffic.
Two cautions follow. First, some carriers and some destination types don't return a final report at all, so a message can sit at sent forever and still have arrived. Second, a delivered report doesn't prove the number was the right person. A reassigned number can receive a text meant for its previous owner, and that's a compliance problem you handle with scrubbing and opt-out checks, not with delivery status.
Use delivered as a floor for "no technical problem found." Use replies, clicks and opt-outs as the real signals of engagement.
Why texts fail
A failed report usually points to one of a few causes. The number may be a landline or no longer in service. The carrier may have filtered the content, which is common for unregistered traffic. The recipient may have opted out. Or the send may have been refused before it left, for example during quiet hours.
Ready refuses opt-outs and numbers on your Ban list up front without a charge, and it holds or refuses texts outside the recipient's quiet hours. A text refused this way never goes out to a carrier. Our error codes and troubleshooting guide walks through reading these failures, and 10DLC registration explains why unregistered traffic gets filtered.
Handling the callback safely
Your endpoint is a public URL, and providers retry when you don't answer fast. Build it with that in mind.
- Answer quickly. Return a 200 as soon as you've stored the payload, then do the slow work in a background job. A handler that takes ten seconds invites a retry storm.
- Expect duplicates. The same report can arrive more than once. Key your updates on the message ID plus the status, so a repeat changes nothing.
- Expect disorder. A delivered report can arrive before a sent report. Never let an earlier stage overwrite a later one. Rank the stages and only move forward.
- Verify the sender. Check any signature or shared secret your provider documents before you trust the body. Don't act on an unverified POST.
- Log the raw payload. When a customer asks why a text never landed, the raw report is your evidence.
Duplicates also apply on the way out. Send an Idempotency-Key header with each POST /v1/messages so a retried request never sends twice. The idempotency guide covers that side in detail.
Closing the loop in your product
A delivery report is most useful when it changes what a user sees. Show the stage in your own UI, and let a failed status trigger a sensible next step: tell the user the number looks bad, or stop retrying a number that failed for a permanent reason.
Don't retry blindly. On Ready, failed isn't always final: Ready resends some failures itself under the same message_id, so wait for its resend window before you resend (see Failures Ready resends for you). A message that failed because the recipient opted out should stay failed. If you receive inbound replies on the same endpoint, route them separately from delivery reports. The post on inbound SMS webhooks shows how to keep the two paths apart.
Frequently asked questions
Does delivered mean the person read the text? No. It means the carrier accepted it for that number. Plain SMS has no reliable read receipt.
Why is a message stuck at sent? Some carriers don't return a final report. The text may have arrived, so treat sent as unknown, not as failed, and judge it by replies.
Should I poll instead of using webhooks? Webhooks are better for timing and load. Keep a slow poll as a backstop only for messages that never got a final report.
What to build first
Store the message ID from every send, accept callbacks fast, make updates safe to repeat and never move a status backward. Then read your provider's status list and map it to three states your users understand: pending, delivered and failed. If you're evaluating Ready, create an account and walk the quickstart to see the webhook setup yourself.