SMS delivery reports (DLR): what each status really means

An SMS delivery report (DLR, also called a delivery receipt) is the status the SMS centre sends back after it has concluded what happened to a message: delivered to the phone, expired, rejected or undeliverable. "Delivered" means the network handed the text to the handset, or at least reported doing so. It never means the person read it. Reports are optional for operators and vary by route, so a missing or odd status is common and should be treated as "unknown", not as success or failure.

#What is an SMS delivery report?

An SMS delivery report is a short status message about a text you sent, generated by the SMS centre (SMSC) that handled it. On a phone, it shows up as a "Delivered" label under a sent message. In business messaging, it arrives at your server as a callback or over an SMPP connection, linked to the message ID you got when you submitted the text. Our delivery receipt glossary entry has the short definition.

The mobile SMS standard, 3GPP TS 23.040, describes the mechanism as the SMS centre "returning a status report TPDU (SMS-STATUS-REPORT) to the originating MS when the SC has concluded the status of the short message". It also says: "The status report capabilities of the SMS are optional, i.e. the choice of whether to offer status report or not is left to the SC operator" (3GPP TS 23.040). That one sentence explains much of the confusion around DLRs.

#What does "Get SMS delivery reports" mean on a phone?

Many messaging apps have a setting called "Get SMS delivery reports" or "Delivery reports". Switching it on sets a flag in each text you send asking for a status report. In TS 23.040 this flag is the TP-Status-Report-Request (TP-SRR), "indicating if the MS is requesting a status report" (3GPP TS 23.040).

When the operator supports it, your phone receives a small hidden status message and the app marks your text as delivered. When it doesn't, or when the recipient is abroad or on a route that drops reports, you see nothing or a vague status. The setting doesn't affect whether your text is delivered, only whether you hear about it.

#How do business delivery reports work?

For businesses, the report travels back along the same chain the message took: from the recipient's network, through any aggregators, to your messaging provider and then to your application. There are two distinct events, and confusing them is the most common mistake:

Most providers' APIs and dashboards show their own status words (for example queued, sent, delivered, undelivered, failed). Underneath, many routes still carry the SMPP format. SMPP v3.4 lets the sender request reports with the registered_delivery parameter, including an option for a receipt only "where the final delivery outcome is delivery failure" (SMPP v3.4). If your platform requests failure-only receipts, silence is the normal success case.

#What does each DLR status mean?

SMPP v3.4 gives a "typical example" of a receipt carried in the message text, and notes that the exact format depends on the SMSC implementation (SMPP v3.4):

id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD err:E Text:...

The stat field carries the final state. These are the SMPP definitions, with what each one means in practice:

SMPP also defines an ENROUTE state for messages still in transit, returned when you query a message's state (SMPP v3.4). It is not final.

The err field "may hold a Network specific error code or an SMSC error code", and SMPP notes these "are Network or SMSC specific" (SMPP v3.4). The same number can mean different things on different routes, so map error codes per provider. Our guide to SMS delivery receipts vs HLR lookup covers the common network error causes, such as an absent subscriber or an unknown subscriber.

#What does "delivered" really mean?

It means the network says the message reached the handset. It doesn't mean:

• Read. SMS has no read receipts. Only richer channels such as RCS report reads.
• Seen by the right person. After a SIM swap or a number reassignment, the message reaches whoever holds the number now.
• Shown to the user. A phone may file a message into a spam folder or a filtered inbox after delivery.
• Always confirmed. TS 23.040 even defines a status for "Short message forwarded by the SC to the SME but the SC is unable to confirm delivery" (3GPP TS 23.040). Whether that becomes "delivered" or "unknown" in your dashboard depends on the route.

For one-time passcodes, the honest delivery metric is conversion: the share of codes that are entered. Track it per country and per route next to your delivery reports: when the two diverge, the reports are wrong or the messages are being filtered on the phone.

#Why are delivery reports missing or wrong?

Practical rules: set a timeout after which a message without a final report counts as unknown; never count unknown as delivered; alert on sudden changes in delivery or conversion per country and per route rather than on single failures; and keep the provider's message ID, the raw status and the err code for every send.

Here is a small parser for SMPP-style receipt text, useful when your provider passes the raw receipt through:

import re

FINAL = {"DELIVRD": "delivered", "UNDELIV": "failed", "REJECTD": "failed",
         "EXPIRED": "expired", "DELETED": "failed", "ACCEPTD": "unknown", "UNKNOWN": "unknown"}

def parse_dlr(text: str) -> dict:
    fields = dict(re.findall(r"(id|sub|dlvrd|stat|err):(\S+)", text))
    return {"message_id": fields.get("id"), "raw_stat": fields.get("stat"),
            "outcome": FINAL.get(fields.get("stat", ""), "unknown"), "err": fields.get("err")}

parse_dlr("id:7f3a91 sub:001 dlvrd:001 submit date:2610011200 done date:2610011201 stat:DELIVRD err:000 Text:Your code")
# {'message_id': '7f3a91', 'raw_stat': 'DELIVRD', 'outcome': 'delivered', 'err': '000'}

#How do pre-send checks reduce failed deliveries?

A delivery report tells you what went wrong after you paid for the message. A pre-send check catches the predictable failures before you send.

For a one-time passcode, a fresh HLR check right before sending is the most useful. With a test key, +447700900002 returns unreachable (see test mode):

curl https://api.mobilevalidate.com/v1/lookup \
  -H "Authorization: Bearer $MOBILEVALIDATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+447700900002"], "checks": ["hlr"], "max_age": 0, "wait": 5}'

If checks["number.hlr"].attributes.status is unreachable, offer e-mail, voice or an authenticator app straight away instead of waiting for an SMS that will expire. If it's invalid, ask the user to correct the number. An HLR lookup costs $0.005 per number at the time of writing, and unknown answers, such as after a network timeout, are free (pricing). For lists, a carrier lookup in a bulk job at $0.001 per number removes landlines and other non-SMS lines before a campaign. The SMS cost reduction use case shows the full workflow, and why SMS messages aren't delivered walks through every failure cause.

#Key takeaways

• An SMS delivery report is the SMS centre's status for a message you sent: delivered, undeliverable, expired, rejected, deleted or unknown.
• On phones, "Get SMS delivery reports" only asks for a status report; operators decide whether to provide one.
• In SMPP receipts, stat:DELIVRD means delivered to the destination, UNDELIV a permanent failure, EXPIRED a phone that stayed unreachable, and REJECTD a refusal, often for sender or content reasons.
• "Delivered" isn't "read", and some routes report delivery they can't confirm. Use OTP conversion as the real success metric.
• Missing reports are normal on some routes. Time out to unknown, never to "delivered".
• Pre-send line type, reachability and porting checks prevent the predictable failures before you pay for them. Unknown answers from MobileValidate are never charged.