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": "DeliveryReceipt",
  "correlator": "8f24c8c6-7e7c-4b6f-a622-d4a25f91d3c1",
  "phone": "+254123456789",
  "timestamp": "2025-06-02T14:30:00Z",
  "deliveryStatus": "Delivered"
}

​
Fields Explanation

FieldTypeDescription
typeStringType of the request, which is always DeliveryReceipt for delivery receipts
correlatorStringUnique ID that correlates with your original message request
phoneStringRecipient’s phone number
timestampStringISO-8601 formatted date and time when the delivery status was recorded
deliveryStatusStringCurrent delivery status of the message
reasonStringOptional human-readable explanation for the delivery status
reasonCodeStringOptional provider-specific code related to the delivery status

​
Possible Delivery Status Values

StatusDescription
WaitingDelivery process is pending and hasn’t been attempted yet
DeliveredMessage was successfully delivered to the recipient
DeliveryUncertainDelivery status is ambiguous or unknown
DeliveryImpossibleDelivery failed and was deemed impossible
SenderBlacklistedSender is blacklisted, preventing delivery
InsufficientFundsDelivery failed due to insufficient account credits
InvalidLinkIdThe provided link ID for delivery was invalid
SubscriberOptedOutRecipient has opted out and cannot receive messages
AbsentSubscriberRecipient is temporarily unavailable or unreachable
InvalidMsisdnRecipient’s phone number is invalid
FailedTermination failed while attempting to handover to gateway