A2P SMS DLR Integration Contract: Fields, Statuses, and Changes
A practical guide to agreeing on DLR formats between SMS providers, preserving original codes, correlating events, and testing changes without treating a report as automatic proof of delivery to a mobile phone.
Why DLR semantics can vary
A delivery report (DLR) is an event communicated by a system in the messaging chain. Its operational meaning depends on who generates it, which stage it represents, and how that provider defines its statuses. As a result, two systems may use similar labels without their reports constituting equivalent evidence.
Before integrating, identify each link involved—for example, the sending platform and the provider returning the report—and request its current technical documentation. Do not assume that a status, code, or timestamp means the same thing across all systems. The information available here does not support defining a universal list of statuses or their equivalents.
- Agree on the event each provider communicates and which stage of the journey it is intended to represent.
- Record the provider’s documented definition of each status, not just its label.
- Clarify what timestamps mean and which time zone they use.
Define a common schema before connecting systems
The data contract should distinguish required fields, optional fields, and fields conditional on provider availability. For each field, specify its name, type, format, meaning, rules for absence, and agreed examples. Do not turn a local convention into a universal requirement: validate each point with the integration participants.
As a basis for discussion, consider an event identifier, the message identifier known to the sender, the normalized status, the original code and text, the source system, and available timestamps. Add correlation identifiers when values are translated between systems. The available evidence does not establish that all these fields exist or follow a standard format in every DLR.
- Mark a field as required only if all participants can produce and validate it.
- Define whether an absent field is omitted, represented as null, or reported through another mechanism.
- Specify the format and time zone for each timestamp; do not infer receipt time from another timestamp without a documented rule.
- Include valid and invalid examples in the contract.
Preserve the normalized status and the original response
Normalization enables common processing, but it can hide important differences if it completely replaces the provider’s response. Store the internal normalized status separately from the status, code, and text originally received. Also retain the source system’s name or identifier and the version of the mapping applied.
Maintain an explicit mapping table reviewed with each provider. If a code is undocumented or cannot be mapped safely, classify it as unknown or pending review; do not automatically convert it to success or failure. Normalization should be operationally reversible: the team must be able to see which value arrived and which rule produced the classification.
- Do not discard the original code when calculating metrics or updating internal statuses.
- Document each equivalence, including its source, scope, and review date.
- Define an unknown category and a review path for new values.
- Avoid grouping distinct statuses unless the provider confirms that they represent the same condition.
Correlate each event with the correct message
A message identifier may differ between systems. The contract must explain which identifier each participant generates, where it is returned, and how it is linked to the identifier known to the application that sent the message. If translation is involved, record the relationship between the values rather than assuming they are interchangeable.
Define the key or combination of keys your integration will use to look up the associated message. Specify what happens if an identifier is missing, no match is found, or multiple matches appear. Do not attribute a DLR based only on a data similarity that has not been agreed as a valid matching criterion.
- Document how identifiers flow from sending through to the report.
- Test valid matches as well as missing, unknown, and repeated identifiers.
- Preserve the source and destination values for each translation.
- Send unmatched events to a queue or investigation process instead of assigning them arbitrarily.
Handle duplicates, delays, and unrecognized events
Agree on how to identify and handle repeated or late events, and events received in an unexpected order. The available technical evidence does not define a universal deduplication or sequencing rule for all providers. The contract must therefore specify what data can identify a duplicate, how long the necessary information is retained, and how contradictory events are resolved.
Do not overwrite an earlier status just because another event arrived later: receipt order may not reflect the order in which the events occurred. Determine with each provider which timestamps are relevant and what precedence, if any, is documented. If there is no verifiable rule, preserve the history and send ambiguous cases for review.
- Define the duplicate criterion and what happens when an event is received more than once.
- Record local receipt time separately from reported timestamps, if available.
- Specify how to handle late, unknown, contradictory, and unmatched statuses.
- Make update logic traceable and avoid deleting the original history.
Test the contract with agreed acceptance cases
Prepare joint tests using examples approved by the participants. The goal is to check the received format, field validation, status mapping, and correlation—not to prove by itself that a phone received the message. The list of codes and expected results should come from the documentation and technical agreement of the providers involved.
Run tests in an appropriate environment and record the input, expected result, observed result, and decision. If the actual format differs from the contract or a status is undocumented, pause acceptance of that variant until the discrepancy is resolved.
- Valid event with all agreed fields.
- Optional field missing and required field missing, each with its expected documented behavior.
- Known status with the original code preserved and the expected mapping applied.
- Unknown code or status, without automatic classification as success.
- Repeated, late, out-of-order, and uncorrelatable event.
- Format with fields added, omitted, renamed, or using a different type, within the limits of the contract.
Version the contract and control changes
Treat the format and mapping as a shared contract, not as an assumption embedded in code. Identify each version, retain the change history, and communicate which systems accept it. Before deploying a change, determine whether it affects the structure, a field’s type, the semantics of a status, or correlation.
Agree on a notification, review, and testing process with each participant. Do not declare a change compatible just because the message remains syntactically valid: an unchanged label can take on a different meaning, and an added field can affect consumers that validate the format strictly. Compatibility must be checked against the specific integration rules.
- Assign an identifiable version to the contract and mapping tables.
- Assess format changes and semantic changes separately.
- Run the agreed acceptance cases before activating a new version.
- Define how incompatible changes will be communicated, accepted, or rejected.
A reported DLR does not, by itself, prove receipt on the handset
Interpret a DLR within the scope documented by its sender. A status reported by one link indicates what that system reports; it should not automatically be presented as independent confirmation that the message appeared on or was received by the user’s handset. The available evidence does not support claiming that any specific status guarantees such receipt.
In operational reports, distinguish received events from any independent verification that may exist, and describe its limits. Do not use a DLR as proof of consent, identity, or message reading. If a business decision depends on actual receipt, define in advance what evidence is considered sufficient and consult the documented capabilities of the systems involved.
- Describe the status as reported by its source, without claiming more than the documentation supports.
- Separate DLR receipt, normalized status, and any available independent evidence.
- Show unknown or ambiguous cases in metrics and reports instead of forcing them into a conclusive category.
Frequently asked questions
Is there a universal list of DLR statuses that all providers must use?
The technical information available for this guide does not establish a universal list or equivalences between providers. Request each participant’s documentation and explicitly agree on the statuses and codes to be mapped.
Should I replace the original code with a normalized status?
No. Preserve the original code, text, and source alongside the normalized status and the mapping rule applied. This lets you investigate discrepancies and review the mapping when the documentation changes.
What should I do with a duplicate or unmatched DLR?
Define in the contract how duplicates are identified and recorded. For an unmatched event, preserve the received data and send it for investigation; do not assign it to a message based on an unagreed match.
Does a DLR confirm that the SMS reached the phone?
Not necessarily. A DLR communicates the status reported by a system in the chain, and its scope depends on the sender’s definition. Do not present it as independent proof of receipt on the handset without supporting documented evidence.
What should be tested before accepting a format change?
Check the agreed required and optional fields, types and formats, preservation of original values, status mapping, correlation, and handling of unknown, repeated, and late values. The participants should document the expected result.
Sources consulted
- SMPP v3.4 Issue 1.2SMPP Developers Forum
- HTTP Semantics (RFC 9110)IETF
- 3GPP specifications by series3GPP
- ITU-T Recommendation E.164International Telecommunication Union
- GSMA Networks resourcesGSMA