Skip to Content

Delivery Reports (DLR) Deep Dive

Architectural mechanics of telecommunication delivery receipts, intermediate vs. terminal states, status mapping, and message correlation.

View Markdown (.md)

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:

Delivery Reports DLR Routing Flow

  1. Your application receives 202 Accepted.
  2. The carrier later reports whether the handset received the message.
  3. SMS Pro matches that report to messageId, signs the body, and posts it to your webhook.

Delivery report path


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 StatusCarrier CodeState TypeTechnical Meaning
SENTENROUTE / ACCEPTDIntermediateMessage is queued at the carrier SMSC awaiting air interface transmission.
DELIVEREDDELIVRDTerminalHandset confirmed physical receipt. Message successfully landed on device.
UNDELIVEREDUNDELIVTerminalThe number could not be delivered.
EXPIREDEXPIREDTerminalThe handset stayed unreachable until the message expired.
BLOCKED_SPAMcontent filterTerminalThe message was blocked as spam.
FAILEDrouting failureTerminalThe 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:

  1. 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.
  2. Legacy Feature Phones: Older 2G handsets occasionally fail to return radio-layer acknowledgments during low-battery states.
  3. 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:

IdentifierSourcePurpose
clientReferenceYour ApplicationYour internal domain ID (e.g. order_89201, auth_attempt_482).
messageIdSMS Pro GatewayUUID returned in the 202 Accepted response. Identifies the specific recipient dispatch.
jobIdSMS Pro GatewayIdentifies the overall submission job (for bulk sends, one job encompasses many messages).

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';

On this page