Transactional SMS API Delivery Receipts: DLR Processing, Status Mapping and Reconciliation

What a delivery receipt represents

A delivery receipt is evidence from a messaging provider or downstream network about the state of a submitted SMS. It is different from the API response that confirms the platform accepted a request.

The two events can occur at very different times.

Common delivery states

A normalized model may include accepted, submitted, delivered, failed, expired and unknown. Providers can use different names and additional intermediate states.

The internal model should remain stable while retaining the original provider status.

Provider message identity

Store the provider's message reference alongside the internal message ID. This allows callbacks to be correlated even when the provider does not know the application's business reference.

Duplicate DLRs

Providers may retry callbacks. Delivery receipt processing must be idempotent so duplicate receipts do not create duplicate history or billing events.

Out-of-order DLRs

Receipts can arrive out of order. A late submitted event should not overwrite a previously established delivered state unless the provider's semantics explicitly require such behaviour.

Failure reasons

Store normalized failure category and original provider reason. A failed destination, expired message, sender problem and provider outage require different operational responses.

Reconciliation

If callbacks are missing, the platform can periodically query provider status where supported. Reconciliation should be bounded and should not create duplicate delivery events.

DLR retention

Delivery evidence may be needed for support, billing or compliance. Define retention according to business requirements and privacy rules.

Delivery analytics

Calculate delivery rate, failure rate, expiration rate and time-to-delivery from DLR data. Segment analytics by provider, route, destination and message type where useful.

Unknown status

Never force an unknown provider status into a known state merely to make reporting convenient. Quarantine or map it to an explicit unknown category until its meaning is understood.

Testing

Test duplicate receipts, delayed receipts, missing receipts, out-of-order states, unknown codes and reconciliation responses.

Implementation checklist

Store provider references, normalize statuses, protect state transitions, deduplicate receipts, reconcile missing events and build delivery analytics.

DLR state machine

Define valid status transitions explicitly. For example, ACCEPTED may move to SUBMITTED, FAILED or EXPIRED; SUBMITTED may move to DELIVERED, FAILED or EXPIRED. A terminal DELIVERED state should normally not move backward.

The exact states depend on provider semantics, but the transition rules should be deterministic.

Provider code mapping

Maintain a mapping table from provider status and reason codes to internal categories. Store the mapping version so historical interpretations can be explained if provider semantics change.

DLR security

Validate callback authentication before accepting provider delivery data. A forged callback that marks every message DELIVERED can corrupt operational reporting and billing.

Missing receipts

A message without a receipt is not necessarily failed. It may be delayed, the provider may have lost the callback or the destination network may not have returned a final state.

Use reconciliation and explicit UNKNOWN or PENDING states rather than inventing a failure.

DLR reconciliation schedule

Reconciliation can focus on messages whose provider state remains unresolved beyond a reasonable window. Avoid querying every historical message continuously.

Delivery-time measurement

Store provider event timestamps when available. Compare submission and delivery timestamps to calculate time-to-delivery while recognizing that provider clocks and network conditions can introduce differences.

Analytics quality

Separate API acceptance, provider submission and delivery success. A high API acceptance rate does not mean high delivery performance.

Operational scenario

A message is submitted successfully but no DLR arrives within the normal window. Reconciliation queries the provider and finds DELIVERED. The platform records the reconciled result and marks the source as provider reconciliation rather than pretending the original callback arrived.

Final implementation checklist

Define status transitions, provider mappings, callback authentication, missing-receipt policy, reconciliation windows, timestamps and delivery analytics.

DLR storage model

A delivery-event table can contain internal message ID, provider message ID, provider event ID, provider status, normalized status, reason code, event timestamp, received timestamp and processing result. This separates what the provider reported from how the platform interpreted it.

Terminal-state protection

A terminal state such as DELIVERED should be protected against accidental regression. If a later event conflicts with the terminal state, record the event but do not blindly change the customer-facing status.

Provider polling versus callbacks

Callbacks are generally more efficient for asynchronous delivery information, while polling can help reconcile missing events. Do not poll aggressively for every message because it can create unnecessary provider load.

DLR billing relationship

If delivery status affects commercial reporting, keep billing events separate from raw DLR events. A duplicate DLR should never create duplicate billing. A corrected interpretation should produce an auditable adjustment.

DLR troubleshooting

When a customer says an SMS was not received, support can inspect submission status, provider message reference, final DLR, reason code and timestamps. This is more useful than relying on a single “sent” flag.

Final architecture example

Message M800 is submitted with provider reference P900. Two DELIVERED callbacks arrive with different transport request IDs but the same provider event ID. The first creates the delivery event; the second is recognized as a duplicate. The message remains delivered and analytics count one delivery.

DLR event immutability

Raw delivery events should normally be treated as append-only evidence. If the normalized status logic changes later, the platform can recalculate derived state without losing the original provider observation.

DLR provider migration

During provider migration, store provider identity with each DLR. This prevents callbacks from different providers from being confused when internal message IDs remain stable.

DLR recovery

If callback processing fails after the provider has acknowledged the webhook, replay the same event ID through the normal idempotent processor. Do not create a manually edited delivery record.

Developer takeaway

Delivery receipts are evidence, not just flags. Preserve provider identity, event identity and original status while deriving a stable internal delivery state.

Practical production scenario

A provider reports DELIVERED, then later sends an older SUBMITTED event because of delayed processing. The state machine keeps DELIVERED as the current customer-facing state while retaining the late event as evidence. Analytics count one delivery and support can see both provider observations.

Final production test

Send duplicate, delayed, missing and out-of-order DLR events. Verify event deduplication, state protection, reconciliation and accurate delivery reporting.

DLR reconciliation controls

Reconciliation should be rate-limited and restricted to unresolved messages. Record when a reconciliation query was attempted and whether the result came from a provider callback or a provider status lookup.

DLR auditability

Keep raw provider status, normalized status and reason code separately. This allows the platform to improve its mapping logic later without losing historical evidence.

Final rule

Treat delivery receipts as external evidence that must be authenticated, correlated, deduplicated and interpreted through an explicit state model.

DLR acceptance test

Verify that one logical message remains one delivery result when the provider sends repeated callbacks, and that a missing callback can be resolved through controlled reconciliation.

DLR data quality

Provider DLR data should be treated as external input and validated for expected types, timestamps and message references. Malformed events should be quarantined rather than allowed to corrupt the message state.

DLR operational review

Compare provider-reported delivery outcomes with internal analytics regularly. Unexpected divergence can indicate callback loss, mapping errors or provider reporting changes and should trigger investigation before financial reports are finalized.

Final implementation note

Keep raw DLR evidence separate from derived delivery state.

Final quality check

Test malformed and duplicate DLRs as well as missing callback reconciliation.

Acceptance summary

Confirm DLR authentication, deduplication, state protection and reconciliation.

Operational lesson

When delivery evidence is incomplete, preserve uncertainty and reconcile it instead of guessing a final status.

Closing note

A clear DLR model makes delivery support, analytics, billing reconciliation and provider troubleshooting substantially more reliable.

Final check

Verify every delivery result remains traceable to the provider evidence and internal message.

Final check

Verify reconciliation never creates duplicate delivery outcomes.

Final rule

Keep DLR reconciliation idempotent.