123eworld Knowledge Hub → Transactional SMS → Page 130
Transactional SMS API Delivery Reports: DLR Processing, Provider Mapping, Status Codes and Reconciliation
A detailed developer guide to Delivery Reports (DLRs) for transactional SMS, including provider status mapping, duplicate reports, delayed delivery evidence, country-specific behaviour, normalized status codes and reconciliation.
What a DLR represents
A delivery report is provider evidence about the downstream message lifecycle. It should be associated with the platform's logical message ID and provider reference rather than treated as an independent message record.
Provider-specific statuses
Providers can use different terminology for delivered, rejected, expired, unreachable or unknown outcomes. The platform should maintain a mapping layer rather than exposing provider strings as the primary API contract.
Normalized statuses
A normalized model might contain delivered, failed, expired, pending and unknown categories, with a separate provider reason field for diagnostics.
Duplicate DLRs
Providers may send the same delivery report more than once. Store a provider event identifier where available and make state updates idempotent.
Delayed DLRs
Delivery evidence can arrive long after submission. The system should support late events and retain the logical message record for at least the required reconciliation period.
Unknown status
Unknown should not automatically mean failed. It can represent insufficient provider evidence, a temporary integration issue or an unsupported provider status.
DLR ingestion pipeline
Separate provider-facing callback ingestion from business processing. Persist the raw event safely, acknowledge the provider quickly and process normalization asynchronously.
Reconciliation
Compare internal message states with provider reports and identify messages that remain pending beyond expected delivery windows.
Country and route differences
Delivery semantics can differ by destination network and route. The provider adapter should preserve route metadata while exposing a stable customer-facing status model.
Reporting
Reports should distinguish accepted, submitted and delivered metrics so customers do not mistake API acceptance for handset delivery.
Testing
Use provider test events for each supported outcome and verify duplicate, delayed and out-of-order behaviour.
Implementation checklist
Define provider mapping, normalized statuses, raw-event storage, idempotency, retention, reconciliation, reporting and route-specific diagnostics.
DLR normalization architecture
The provider adapter should first validate the incoming report, persist a safe raw representation and then translate the provider status into the platform's normalized model. This separation preserves provider evidence without making customer APIs dependent on provider terminology.
Reason-code mapping
Maintain a controlled mapping table from provider reason codes to internal categories. Store both values so the customer receives a stable status while support teams can still investigate the original provider response.
Late DLR handling
A delivery report can arrive after a customer has already queried the message status. The status API should update consistently and expose the latest authoritative state rather than creating a second message record.
DLR reconciliation job
A scheduled reconciliation process can identify messages with no delivery evidence after an expected interval. Depending on provider capability, it can query status, request a report or mark the message as unknown rather than incorrectly failed.
Metrics by outcome
Separate API acceptance, provider submission, delivery and final failure metrics. A platform can have excellent API availability while delivery quality is degraded, so these metrics must not be combined into one success rate.
Developer reference rule
DLR processing should preserve raw provider evidence, expose stable normalized states and support late, duplicate and out-of-order reports without corrupting message history.
Provider DLR adapter
Each provider adapter should translate external DLR fields into a common event structure containing logical message ID, provider reference, normalized outcome, provider reason, event time and route information. This makes downstream processing independent of provider-specific schemas.
DLR duplicate control
Use provider event IDs where available. If no stable event ID exists, create a carefully defined fingerprint from provider reference, status, timestamp bucket and other safe fields. The goal is to avoid repeated side effects without incorrectly discarding legitimate status changes.
DLR security
Authenticate provider callbacks before accepting status changes. A forged delivery report could cause the platform to show a failed transaction as delivered or trigger a business workflow based on false evidence.
Reconciliation thresholds
Different message types can require different reconciliation windows. OTP messages may become operationally irrelevant quickly, while financial notifications may require longer evidence collection. Define thresholds according to business value.
Provider outage handling
If a provider's DLR system is delayed, avoid marking every message failed simply because evidence is missing. A temporary evidence gap is different from a confirmed delivery failure.
Practical scenario
A provider delivers an SMS successfully but its DLR callback arrives 20 minutes late. The platform keeps the message in pending or provider-submitted state until the configured evidence window, then transitions it to delivered when the authenticated DLR arrives.
Failure scenario
A provider changes the meaning of one status code. The adapter mapping is updated to the new normalized category while raw provider evidence remains stored for historical investigation. Customer applications continue receiving the same stable API status model.
Operational checklist
Verify provider authentication, DLR validation, normalized mapping, duplicate handling, late events, reconciliation, route metadata, reporting and raw-event retention.
Developer takeaway
DLR processing is a translation and evidence problem. Preserve provider truth while giving customers a stable interface.
Design review
Review DLR mappings whenever provider contracts change. Mapping changes should be versioned and tested against historical examples so a new interpretation does not silently alter reporting for old events.
Reference note
Keep raw provider references long enough to investigate delivery disputes and reconcile delayed events.
Final standard
DLR processing must preserve evidence while presenting stable, understandable status categories.
Implementation example
Provider A reports DELIVRD while Provider B reports DELIVERED. Both map to the normalized delivered state, while the original provider status remains available for diagnostics. Customer reporting therefore stays consistent across routes.
Testing standard
Replay each provider's representative status set, including unknown and delayed values, and confirm normalized mappings remain stable after adapter changes.
Final checklist
Confirm DLR authentication, mapping versioning, duplicate handling and reconciliation are tested independently of customer reporting.
Capacity example
A campaign can produce a large number of DLRs shortly after provider submission. DLR ingestion therefore needs independent scaling from outbound message workers so a callback burst cannot block new API requests.
Support guidance
When delivery reports are missing, determine whether the provider itself is delayed before changing internal message status. Missing evidence is not equivalent to confirmed failure.
Reference rule
Separate provider evidence ingestion from customer-facing status projection.
Production readiness
Test authenticated DLR ingestion with duplicates, delays and provider status changes. Verify that normalized status and raw provider evidence remain consistent after repeated events.
Documentation requirement
Explain the difference between API acceptance, provider submission and delivery reports. Customers should be able to reconcile their own message records with the platform's status model.
Long-term maintenance
Review provider mappings whenever route contracts change and keep historical test fixtures so mapping changes do not silently break old status interpretation.
Architecture review
Separate raw DLR ingestion from normalized status processing so provider callback bursts can be absorbed without blocking customer API traffic. The raw event can then be replayed if the mapping logic is corrected later.
Final implementation note
Treat provider status mappings as versioned configuration or code and test every supported outcome before deployment.
Final production rule
Do not equate missing delivery evidence with confirmed delivery failure.
Reference summary
DLR normalization protects customers from provider-specific terminology while preserving the evidence required for operational reconciliation.
Developer implementation detail
Keep DLR processing independent from customer report generation. The ingestion worker should persist authenticated provider evidence first, while a separate projection updates status queries and reports. This allows the platform to rebuild customer-facing projections if mapping logic changes without asking providers to resend historical reports.
Final check
Confirm provider DLR evidence can be replayed without creating duplicate message records or billing events.
Quality standard
Keep normalized delivery status stable even when provider terminology changes.
Final reference point
A delivery report is evidence about a message attempt, not a new message. Keep that distinction throughout ingestion, state management, reporting and billing.
Closing note
Keep DLR evidence immutable enough for later reconciliation and support investigations.
Check
Verify DLR retention.
Need transactional SMS integration?
123eworld.com provides Bulk SMS and API-based business communication solutions for enterprises and software applications.