Delivery receipt: definition and how it works
Published and updated
A delivery receipt is the network's report that an SMS reached the recipient's handset, or failed to, surfaced by a gateway as a status on the message.
How it works
An SMS goes through several hands: your gateway, the sending network, sometimes an intermediary, the recipient's network, and finally the handset. A delivery receipt is the message that travels back along that chain when the last hop succeeds or fails. Gateways expose it as a status: queued or pending, sent when the carrier accepted the message, delivered when the handset confirmed it, failed with a reason when it did not.
Receipts are useful but imprecise. Delivered means the destination network reported delivery to the device, not that anyone read the message. Sent without a later delivered can mean the phone is off, out of coverage, or that the network does not return receipts for that route. Some carriers and some countries return receipts unreliably or not at all, and a few report delivered as soon as they accept the message. Treat delivered as strong evidence and sent as unknown, and design flows, such as OTP resends, around timeouts rather than around a missing receipt.
Failure reasons are the actionable part. An invalid number, a blocked destination or a filtered message each need a different response, and a gateway that passes the carrier's reason code through saves you guessing.
For high-value messages, store the status with the message and let the user trigger a resend rather than resending automatically on a missing receipt, which doubles the cost when the first one was simply slow.
How this applies with textbee
A textbee message moves from pending to sent when the phone hands it to the network, then to delivered when the carrier confirms it, or failed with an error. You see the status on GET /gateway/messages and as MESSAGE_SENT, MESSAGE_DELIVERED and MESSAGE_FAILED webhook events. Delivery confirmation depends on the recipient's carrier returning it.
Related terms
- Webhook: A webhook is an HTTP request a service sends to a URL you own when something happens, so your code learns about an inbound SMS or a delivery event the moment it occurs instead of polling for it.
- SMS API: An SMS API is a programmatic interface, almost always HTTP, that lets software send text messages, read the ones that arrive, and check what happened to each one.
- OTP: An OTP (one time password) is a short code valid for a single login or action and a short time, most often delivered by SMS to prove the user holds the phone number on the account.