# Delivery Reports (DLR) Deep Dive
URL: /docs/guides/delivery-reports-dlr

> 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 [#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](/images/dlr-delivery-flow.svg)

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](/images/dlr-delivery-flow.svg)

---

## 2. DLR Status Mapping [#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. |

<Callout type="warn" title="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.
</Callout>

---

## 3. Understanding Delivery Report Latency [#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 [#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 [#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 [#recommended-database-schema]
When dispatching an SMS, store the `messageId` alongside your domain entity:

```sql
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:

```sql
UPDATE outgoing_sms
SET status = 'DELIVERED', delivered_at = NOW()
WHERE message_id = 'c7a8b9e0-1234-5678-9abc-def012345678'
  AND status != 'DELIVERED';
```

---

## Related Documentation [#related-documentation]
- 📖 [Webhooks & Event Notifications](/docs/guides/webhooks-and-dlr)
- ⚡ [Recipe: Verify Inbound Webhooks](/docs/recipes/verify-webhooks)
- 🔌 [API Reference: Query Message Statuses](/docs/api-reference/transactional-sms/queryMessageStatuses)