Delivery Receipts

Delivery receipts provide a mechanism to track the status of messages sent through the API. When you send a message with a receiptRequest, the system will send a delivery receipt to your specified callback URL once the message reaches its final state. This allows you to monitor the delivery status of your messages in real-time.

Delivery receipts are sent to the callback URL specified in the receiptRequest object of the message request. If you do not include a receiptRequest, no delivery receipt will be sent.
Ensure that the callback URL is publicly accessible and can handle incoming HTTP POST requests to receive the delivery receipts.

Delivery Receipt Format

A delivery receipt is sent as an HTTP POST request to your callback URL with the following JSON structure:

{
  "type": "SmsDeliveryReceipt",
  "correlator": "8f24c8c6-7e7c-4b6f-a622-d4a25f91d3c1",
  "requestId": "7tewbasen-1234-5678-90ab-cdef12345678",
  "phone": "+254123456789",
  "timestamp": "2025-06-02T14:30:00Z",
  "deliveryStatus": "Delivered"
}

Fields Explanation

Field	Type	Description
`type`	String	Type of the request, which is always `SmsDeliveryReceipt` for SMS delivery receipts
`correlator`	String	Unique ID that correlates with your original message request
`phone`	String	Recipient’s phone number
`timestamp`	String	ISO-8601 formatted date and time when the delivery status was recorded
`deliveryStatus`	String	Current delivery status of the message
`reason`	String	Optional human-readable explanation for the delivery status
`reasonCode`	String	Optional provider-specific code related to the delivery status
`requestId`	String	Original message request ID returned by the API when the message was submitted. Use this value to correlate the delivery receipt with the originating API request.

Correlating a Delivery Receipt

When a message is submitted, the API returns a unique request ID for that message. The same ID is included as requestId in the corresponding delivery receipt callback. Clients can store the request ID from the API response and use it to match subsequent delivery receipts to the original message. For example, if the API response contains:

{
"requestId": "7tewbasen-1234-5678-90ab-cdef12345678"
}

The corresponding delivery receipt will contain:

{
"type": "SmsDeliveryReceipt",
"correlator": "8f24c8c6-7e7c-4b6f-a622-d4a25f91d3c1",
"requestId": "7tewbasen-1234-5678-90ab-cdef12345678",
"phone": "+254123456789",
"timestamp": "2025-06-02T14:30:00Z",
"deliveryStatus": "Delivered"
}

This allows the delivery receipt to be reliably associated with the original message request.

Possible Delivery Status Values

Status	Description
`Waiting`	Delivery process is pending and hasn’t been attempted yet
`Delivered`	Message was successfully delivered to the recipient
`DeliveryUncertain`	Delivery status is ambiguous or unknown
`DeliveryImpossible`	Delivery failed and was deemed impossible
`SenderBlacklisted`	Sender is blacklisted, preventing delivery
`InsufficientFunds`	Delivery failed due to insufficient account credits
`InvalidLinkId`	The provided link ID for delivery was invalid
`SubscriberOptedOut`	Recipient has opted out and cannot receive messages
`AbsentSubscriber`	Recipient is temporarily unavailable or unreachable
`InvalidMsisdn`	Recipient’s phone number is invalid
`Failed`	Termination failed while attempting to handover to gateway

Receipt Request

An optional object on sent requests that enables delivery status callbacks. It must be included in the SMS message request body when sending a message to receive delivery receipts for that message.

{
  "correlator": "12345678-1234-5678-1234-567812345678",
  "callbackUrl": "https://acme.org/sms/delivery-reports"
}

Receipt Request

An optional object on sent requests that enables delivery status callbacks. It must be included in the SMS message request body when sending a message to receive delivery receipts for that message.

{
  "correlator": "12345678-1234-5678-1234-567812345678",
  "callbackUrl": "https://acme.org/sms/delivery-reports"
}

Field	Type	Constraints
correlator	string	Non-empty, maximum 100 characters. Used to correlate callbacks to the originating request (we recommend `UUID`).
callbackUrl	string	Valid `https://` or `http://` URL. The endpoint must not require authentication

When provided, both fields are required. An invalid receiptRequest causes the entire request to be rejected with 400 Bad Request before any messages are dispatched.

Verify receipts with callback security. If posts stop arriving, check the circuit breaker.

REST API

Authentication

Services

Messaging

USSD

Mobile Data

Bundles

Campaigns

Delivery Receipt Format

Fields Explanation

Correlating a Delivery Receipt

Possible Delivery Status Values

Receipt Request

Receipt Request

​Delivery Receipt Format

​Fields Explanation

​Correlating a Delivery Receipt

​Possible Delivery Status Values

​Receipt Request

​Receipt Request

Delivery Receipt Format

Fields Explanation

Correlating a Delivery Receipt

Possible Delivery Status Values

Receipt Request

Receipt Request