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.
{
"type": "SmsDeliveryReceipt",
"correlator": "8f24c8c6-7e7c-4b6f-a622-d4a25f91d3c1",
"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 |
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 send 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 send 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.
