Delivery reports
Two ways to know a message reached the handset: push webhooks to your endpoint (recommended) or the lookup endpoint.
Push — DLR webhooks
Register a callback URL once (see POST /v2/companies/) and we POST each delivery status to it as networks confirm:
Webhook payload (POST to your URL)
{
"trackingId": "order-4521-confirm",
"phone": "254712345678",
"status": "Delivered",
"deliveredAt": "2026-07-11T09:41:22+03:00"
}Status values
| Field | Type | Required | Description |
|---|---|---|---|
| Delivered | final | No | Confirmed on the handset. |
| Failed | final | No | The network could not deliver (off, invalid, barred). |
| Rejected | final | No | The carrier refused the message (filtering, invalid sender for that route). |
| Queued | interim | No | Dispatched, awaiting carrier confirmation. |
Webhook hygiene
Respond
200 quickly (under 5s) and process asynchronously. Treat deliveries as at-least-once — dedupe on trackingId + status. Your endpoint must be HTTPS.Pull — lookup endpoint
POSThttps://api.mobilesasa.com/v1/dlr
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| messageId | string | Yes | The message reference to look up — your v2 trackingId, or the ID returned at send time. |
curl -X POST https://api.mobilesasa.com/v1/dlr \
-H "Authorization: Bearer $MOBILESASA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messageId": "order-4521-confirm"
}'Response
{
"status": true,
"responseCode": "0200",
"message": "Delivered"
}Which should I use?
Webhooks — always, if you can host an endpoint. They're real-time and free of polling overhead. The lookup exists for spot checks, reconciliation jobs, and platforms that can't receive inbound HTTP.