A delivery report (DLR, delivery receipt) is the mobile network's status for one specific message: whether it was delivered to the handset, failed, or was rejected. It is matched to the message by the message ID the gateway returned when you sent it. Every message through Ontech BulkSMS gets one.
Why delivery reports matter
Without a report, "sent" only means "handed to the network". With one, you know per recipient whether the OTP arrived, whether the fee reminder reached the parent, whether a campaign's list is full of dead numbers. Reports are how you answer a customer who says they never got the message, and how you spot a network problem before your customers do.
The delivery states
| State | Meaning | What to do |
|---|---|---|
| delivered | The network confirmed delivery to the handset. | Done. |
| failed | The network could not deliver within its retry period — handset off, out of coverage, number inactive. | Retry later, or use another channel; clean inactive numbers from your list. |
| rejected | The network refused the message — for example an invalid or barred number, or content the network blocks. | Check the number and the message; contact support if it recurs. |
| queued | Accepted by the platform and waiting in the outbox to be submitted to the carrier. | Normal for a few seconds; longer during a large send. |
| submitted | The carrier accepted the message; no final report yet. | Wait. Handsets that are off can take minutes to hours to resolve. |
| unknown | No record for that message ID (status endpoint only). | Check the ID; it must belong to your account. |
Over SMPP the same states arrive in the receipt's stat field using the protocol's codes — DELIVRD, UNDELIV, REJECTD, EXPIRED and so on.
Why reports lag the send
The report comes from the network, not from the gateway. The network tries to deliver; if the handset is off or unreachable it retries for a validity period before giving up and reporting failed. Some networks forward receipts promptly; others batch them. So a report can arrive seconds after the send or, for an unreachable phone, much later. Design integrations to treat submitted as "in progress", not as an error.
Four ways to get delivery reports
1. In the dashboard
Reports and Outbox show the state of every message with the recipient, sender ID, time and cost; usage reports summarise sent, delivered and failed counts and can be exported to CSV or Excel. Campaigns show delivered counts per variant.
2. Poll the status endpoint
curl "https://bulksms.ontech.co.zm/smsservice/status?api_key=YOUR_ACCESS_ID&message_id=MESSAGE_ID"
# → {"status":100,"message":"Success","message_id":"…","delivery_status":"delivered"}
Use the message_id from the HTTP API send response. Polling counts against the 60-requests-per-minute limit, so poll the messages that matter rather than everything.
3. Register a callback URL
Under Webhooks, give the platform an HTTPS address on your server. Delivery updates are posted to it as JSON and retried on failure (three attempts, with increasing delays), so your system stays in sync without polling. Store the state against the message ID you saved at send time.
4. On your SMPP bind
Receiver and transceiver sessions receive each receipt as a deliver_sm PDU with the message ID and state, as it happens. Transmitter-only binds do not; use a transceiver if you want receipts on the same session. See SMPP.
Using reports well
- Store the message ID at send time on the record the message relates to — the login, the order, the pupil. Reconciliation is impossible without it.
- Act on failed. For an OTP, offer a resend or another channel; for a campaign list, remove numbers that fail repeatedly.
- Watch delivered rate per network. A sudden drop on one network is a network issue; a low rate everywhere is a list-quality issue.
- Do not resend on submitted. The message is with the carrier; a resend produces a duplicate when the first one lands. (Identical messages within three minutes are suppressed by the platform for this reason.)
- Keep the reports. Exported reports are the audit trail for "we told the customer on this date".
Reports on Ontech BulkSMS
Ontech BulkSMS has direct connections to MTN, Airtel and Zamtel and stores every receipt against the message; a large share of receipts arrive within seconds of delivery, though final states for unreachable handsets depend on each network's retry behaviour. The SMS API and SMS gateway guides explain where reports fit in the send path.