123eworld Knowledge Hub → Transactional SMS → Page 161
Transactional SMS API Delivery Receipts: DLR Processing, Normalization, Reconciliation and Status Accuracy
A production guide to SMS delivery receipts, provider callbacks, status normalization, duplicate events, delayed reports and reconciliation.
What a delivery receipt means
A delivery receipt is evidence from a provider or downstream network about message processing. It is not necessarily identical to handset behaviour. The platform should normalize provider-specific reports into a stable customer-facing status model while retaining raw evidence internally.
Provider callback ingestion
Receive callbacks through authenticated endpoints, validate signatures where supported and persist the event before performing complex processing. This protects against lost events when a worker crashes during callback handling.
Status normalization
Providers may use different values for accepted, submitted, delivered, expired, rejected and unknown. Define a normalized state machine and a mapping table. Do not allow one provider's vocabulary to become the public API contract.
Duplicate receipts
Providers can resend the same receipt. Store provider event IDs where available and use a deduplication strategy. Duplicate events should not produce repeated customer webhooks or billing actions.
Out-of-order receipts
A delivered event should not normally be overwritten by an older submitted or pending event. Use event timestamps, sequence information or terminal-state rules to prevent status regression.
Delayed receipts
Delivery reports can arrive much later than submission. The platform should represent reporting delay honestly rather than converting missing evidence into a failure. A separate reconciliation or freshness metric can identify routes with stale reports.
Reconciliation
Periodically compare provider-side evidence with internal message state where provider APIs permit it. Reconciliation can detect missed callbacks, processing failures and mismatched statuses.
Billing relationship
If billing depends on submission, accepted delivery, segment count or another event, define the rule explicitly. Do not let duplicate callbacks create duplicate charges.
Webhooks to customers
Once a normalized status changes, generate the customer webhook from the durable internal event rather than directly inside the provider callback handler. This separates provider ingestion from customer notification.
Observability
Track callback volume, processing delay, duplicate rate, unknown statuses and reconciliation mismatches by provider.
Testing
Replay provider callbacks, send duplicates, reorder events and delay delivery reports. Verify that final message status remains correct.
Production checklist
Define callback authentication, durable ingestion, status mapping, deduplication, ordering, reconciliation, billing semantics and customer notification.
Developer takeaway
DLR processing is a data-normalization and reliability problem. Preserve provider evidence while giving customers one predictable lifecycle model.
Implementation architecture
Implement DLR ingestion as a durable event-processing pipeline. Authenticate the provider callback, persist the raw event or required evidence, deduplicate it and map it to a normalized state. Only then update the logical message and generate customer-facing webhooks. This design prevents a callback-processing crash from losing the evidence needed to reconcile the message later.
Operational reference
Provider callbacks should be treated as untrusted external input. Validate the provider identity, signature where available, message reference and allowed status transition before changing internal state.
Operational reference
Unknown DLR values should be retained as raw evidence and mapped to a safe normalized state such as unknown or pending. Do not silently treat every unfamiliar provider code as delivered or failed.
Operational reference
Reconciliation jobs should be idempotent. Running the same reconciliation twice should not create duplicate customer events or billing records.
Production checklist
Production check: verify duplicate DLRs, out-of-order receipts, delayed callbacks, unknown provider states, reconciliation and customer webhook generation.
Additional implementation guidance
DLR ingestion should validate that a provider event refers to a known logical message or a recognized provider mapping. Unknown references should be quarantined for investigation rather than silently creating arbitrary message records.
Additional implementation guidance
Status transitions should be monotonic where the business state machine requires it. A terminal delivered state should not normally return to pending because a delayed provider event arrived later.
Additional implementation guidance
Provider callback timestamps and platform ingestion timestamps should both be stored. The difference between them identifies provider-side delay separately from platform processing delay.
Additional implementation guidance
Unknown provider statuses should be retained as raw evidence. A mapping table can later be updated and historical events can be reprocessed if the provider introduces a new status.
Additional implementation guidance
Reconciliation should compare more than counts. Match message IDs, provider references, timestamps and terminal states where the provider exposes those fields.
Additional implementation guidance
Customer-facing delivery status should remain stable even when provider integrations are replaced. The normalized model belongs to the platform, not to one vendor.
Additional implementation guidance
DLR processing should be idempotent. Reprocessing the same provider event must not create duplicate customer webhooks or duplicate billing entries.
Reference architecture note
Delivery receipt reconciliation should have a controlled schedule and concurrency limit. Running too many reconciliation jobs can overload provider APIs or the internal database. Prioritize messages that are old enough to be operationally significant or belong to routes with known reporting gaps. Reconciliation should update only the fields supported by provider evidence and should not overwrite stronger internal evidence without an explicit rule. Keep a reconciliation audit record so repeated jobs remain understandable.
Advanced production guidance
DLR mappings should be reviewed when providers introduce new codes. Keep mapping tables versioned so a change can be traced to the deployment or configuration revision that introduced it.
Advanced production guidance
Receipt processing should not depend on the provider callback endpoint being continuously available. A durable ingestion layer allows short outages to recover without losing events.
Advanced production guidance
Customers should receive a normalized status model with clear terminal states. Avoid exposing provider terminology that may change without notice.
Advanced production guidance
Delivery-report freshness should be monitored separately from delivery success. A route can have good eventual delivery but still provide reports too slowly for customer workflows.
Engineering reference
When a provider sends a receipt for an unknown message reference, retain it in a quarantine area rather than discarding it. Later reconciliation may reveal that the internal message was delayed or restored from backup.
Engineering reference
Terminal statuses should have clear business semantics. For example, 'delivered' and 'accepted by provider' should not be treated as interchangeable if the customer expects proof of delivery.
Engineering reference
DLR processing should be observable per provider. A sudden drop in callback volume can indicate a provider integration problem even if message submission remains healthy.
Final engineering guidance
When a provider changes its DLR format, deploy mapping changes safely and retain the previous mapping during a compatibility window if needed. This avoids misclassifying events while multiple provider versions coexist.
Final engineering guidance
Reconciliation should be prioritized for messages near terminal-state deadlines or with unusual status gaps. This gives operational teams a focused recovery strategy instead of scanning every historical message.
Final acceptance test
The final acceptance test should replay duplicate and out-of-order provider receipts and verify that the normalized message state remains correct and customer webhooks are not duplicated.
Additional reference
Provider status mappings should be tested with recorded real-world samples where permitted. Synthetic tests alone may miss formatting changes or unusual status combinations.
Additional reference
Delivery receipt processing should remain operational during customer webhook outages. Provider evidence belongs in the platform even when downstream customer notification is temporarily unavailable.
Closing reference
The final status model should make uncertainty explicit. If provider evidence is unavailable, use a state that means exactly that rather than guessing. This prevents customers from making irreversible business decisions from incomplete delivery information.
Final knowledge-base note
Reconciliation results should be retained as operational evidence. If a message was corrected from pending to delivered after a provider lookup, the platform should record the source and time of that correction so support can explain the change later.
Final implementation rule
Keep the normalized state machine documented beside the provider mapping table. This prevents integration changes from silently altering customer-visible status semantics.
Final reference rule
Status normalization should remain independent from provider adapter implementation. That separation lets the platform replace providers without forcing customers to rewrite status handling.
Completion rule
Keep receipt ingestion durable before downstream notification.
Final quality assurance
Store both provider event time and platform ingestion time.
Continue through the 123eworld Knowledge Hub
Explore the complete 123eworld Knowledge Hub for practical SMS API, transactional messaging, queue, security and developer architecture guides.
Visit 123eworld.com for messaging and digital communication services.