Delivery reports

Two ways to know a message reached the handset: push webhooks to your endpoint (recommended) or the lookup endpoint.

Push: DLR webhooks

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: the 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"
}

Pull with filters: the v2 lookup

POSThttps://api.mobilesasa.com/v2/dlr

The v2 lookup returns a paginated list instead of a single status, and filters by phone, sender and date range. start and end are required — omitting them answers The start is not a valid date.

Parameters

Field	Type	Required	Description
start	string	Yes	Window start. YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, or RFC3339.
end	string	Yes	Window end, same formats. A bare date means end of that day.
messageId	string	No	Your v2 trackingId, or the ID returned at send time.
phone	string	No	Filter to one recipient.
senderID	string	No	Filter to one sender name.
page	int	No	Page number, 1-based.

curl -X POST https://api.mobilesasa.com/v2/dlr \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-08-01",
    "end": "2026-08-01",
    "phone": "254712345678",
    "page": 1
  }'

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.