Delivery Reports (DLR) Deep Dive
Architectural mechanics of telecommunication delivery receipts, intermediate vs. terminal states, status mapping, and message correlation.
In telecommunications, a Delivery Report (DLR) is an out-of-band network packet generated by the recipient's mobile operator when a short message reaches a terminal state. For developers, DLRs provide the definitive audit trail proving whether an SMS physically reached a subscriber's device.
1. How Delivery Reporting Works
When your application calls the SMS Pro API, you receive an immediate acknowledgment (202 Accepted). However, confirmation of whether the message was actually displayed on the recipient's screen arrives later via the DLR lifecycle:
- Your application receives
202 Accepted. - The carrier later reports whether the handset received the message.
- SMS Pro matches that report to
messageId, signs the body, and posts it to your webhook.
2. DLR Status Mapping
Telecom carriers across West Africa (MTN, Telecel, AT) emit vendor-specific status codes (e.g. DELIVRD, UNDELIV, EXPIRED, REJECTD). SMS Pro normalizes these into consistent platform statuses:
| SMS Pro Status | Carrier Code | State Type | Technical Meaning |
|---|---|---|---|
SENT | ENROUTE / ACCEPTD | Intermediate | Message is queued at the carrier SMSC awaiting air interface transmission. |
DELIVERED | DELIVRD | Terminal | Handset confirmed physical receipt. Message successfully landed on device. |
UNDELIVERED | UNDELIV | Terminal | The number could not be delivered. |
EXPIRED | EXPIRED | Terminal | The handset stayed unreachable until the message expired. |
BLOCKED_SPAM | content filter | Terminal | The message was blocked as spam. |
FAILED | routing failure | Terminal | The message was not delivered. |
Billing on Terminal Outcomes
Telecommunication carriers can charge once a message is accepted for delivery. A later UNDELIVERED or EXPIRED status does not always return the unit.
3. Understanding Delivery Report Latency
DLR delivery is not instantaneous. Typical latency distributions:
- Immediate Delivery (70-85% of traffic): Reaches handset within 1 to 5 seconds.
- Transient Network Delays (10-15%): Reaches handset within 10 to 60 seconds due to radio interference, tower handover, or localized network congestion.
- Extended Delay (3-5%): Takes minutes to hours if the subscriber's phone is in airplane mode, driving through a coverage dead zone, or powered off.
When Delivery Reports Are Missing
In rare scenarios, a message may be delivered to a handset, but the developer never receives a DELIVERED DLR:
- International Roaming: When a subscriber roams onto a foreign network, the foreign carrier's visited SMSC may not support reciprocal DLR signaling back to the home network.
- Legacy Feature Phones: Older 2G handsets occasionally fail to return radio-layer acknowledgments during low-battery states.
- SMSC Buffer Flush: During rare carrier disaster recovery events, unacknowledged receipts in transit may be purged.
Recommendation: Do not hold critical user workflows in a blocking state waiting for terminal DLRs. Treat DLRs as asynchronous telemetry.
4. Message Correlation Architecture
To track messages across their lifecycle, your application must correlate three identifiers:
| Identifier | Source | Purpose |
|---|---|---|
clientReference | Your Application | Your internal domain ID (e.g. order_89201, auth_attempt_482). |
messageId | SMS Pro Gateway | UUID returned in the 202 Accepted response. Identifies the specific recipient dispatch. |
jobId | SMS Pro Gateway | Identifies the overall submission job (for bulk sends, one job encompasses many messages). |
Recommended Database Schema
When dispatching an SMS, store the messageId alongside your domain entity:
CREATE TABLE outgoing_sms (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
order_id UUID REFERENCES orders(id),
recipient_phone VARCHAR(20) NOT NULL,
message_id UUID UNIQUE, -- Returned by SMS Pro 202 response
status VARCHAR(32) DEFAULT 'QUEUED', -- ACCEPTED, SENT, DELIVERED, FAILED
delivered_at TIMESTAMPTZ,
created_at TIMESTAMPTZ DEFAULT NOW()
);When an inbound webhook arrives containing messageId, execute an idempotent update:
UPDATE outgoing_sms
SET status = 'DELIVERED', delivered_at = NOW()
WHERE message_id = 'c7a8b9e0-1234-5678-9abc-def012345678'
AND status != 'DELIVERED';