SMPP Delivery Receipts: deliver_sm Format, Statuses and How to Test Them
How SMPP delivery receipts (DLRs) are built, what each stat value means and how to test every outcome with an SMSC simulator.
Real networks fail rarely and unpredictably, which is exactly what makes failure handling hard to test. A sandbox turns that around: you choose how often and how late things go wrong.
Statuses worth handling
| Outcome | Receipt stat | What your code should usually do |
|---|---|---|
| Delivered | DELIVRD | Mark done |
| Not delivered | UNDELIV | Report failure, maybe try another route or channel |
| Expired | EXPIRED | Treat as failed after the validity period |
| Rejected | REJECTD | Do not retry the same content blindly |
| Pending / unknown | ACCEPTD / UNKNOWN | Wait, then time out |
The exact receipt text differs between providers, so map by status and keep the raw text in your logs.
Rules to verify
- Retry policy. A failed delivery should not trigger an unbounded retry loop. Cap attempts and back off.
- Idempotency. A retry after an ambiguous result must not send the same SMS twice if the first one eventually arrived.
- Timeouts. If no final report arrives within your limit, the message must move to a defined state instead of waiting forever.
- Out-of-order reports. Reports can arrive in a different order than the submissions.
- Metrics and alerts. A rising failure rate should be visible to you before customers complain.
Scripting failures with a delivery scheme
For each client account in the Maxi panel, a scheme defines the delay before the report is sent and the share of messages ending in each status. Some useful setups:
- 100% Not Delivered: test fallback and user-facing errors.
- High delay: test timeouts and the "resend" behaviour.
- 50% Delivered, 50% Not Delivered: check statistics, dashboards and alerting thresholds.
- Mostly Pending or Expired: test the code path for missing final reports.
Combined with the live queue and statistics in the panel, you can compare what the sandbox did with what your application believes happened.
Want to try this against a real SMPP endpoint? Register for the sandbox and use it free for 3 days, or tell us about your scenario.