• Get Started
  • Get API Credentials
  • Set Callback URLs
  • SMS

  • Send SMS API Call
  • Receive SMS Callback
  • Process Delivery Reports Callback
  • Subscription

  • Request Subscription API Call
  • Cancel Subscription API Call
  • Process Subscription Callback
  • USSD

  • Process USSD Callback
  • Credits

  • Check Balance API Call
  • SDKs & Libraries

  • Download
  • Developer API
  • FAQ
  • Contact Us

Delivery Reports

Receiving and processing delivery reports

How It Works

To receive delivery reports, enter your URL endpoint under the Delivery URL when setting up an outbound (MT) SMS service e.g Bulk, On Demand or Subscription service.

  • When you send a message, Blackbox responds back with a unique message identifier known as reference
  • When a delivery report is received for the sent message, Blackbox initiates a HTTP POST to your callback URL with the delivery parameters

HTTP POST Parameters

Parameter Description Example
event Type of callback notification DELIVERY
reference Unique identifier of the message bb0b30ea2208c99b1164c965ade9dfb8cbb23fdaa1
status Current status of the message SUCCESS
date Date and time the delivery report is received in the format YYYY-MM-DD HH:mm:ss 2015-01-28 18:45:00
recipient Mobile number of recipient in international format starting with a plus sign and country code. +254722123456
sender Shortcode or sender of the message. This could be an alpha-numeric sender or a numeric sender. 20717
keyword Keyword for specified shortcode (if any). Not applicable for alpha-numeric senders. MUSIC
message Message sent to the recipient. This is a very serious message
message_date Date and time a message was sent in the format YYYY-MM-DD HH:mm:ss 2015-01-28 18:45:00
scheduled_date Date and time a message was scheduled in the format YYYY-MM-DD HH:mm:ss 2015-01-28 18:45:00

Status Types

Status Description
SENT The message has been successfully submitted to the mobile operator.
REJECTED The message has been rejected by the mobile operator. This is a terminal status.
SUCCESS The message has been successfully delivered to the recipient's phone. This is a terminal status.
FAILED The message could not be delivered to the recipient's phone. This is a terminal status.

Examples

  • PHP
  • Python
  • Ruby
  • Perl
  • C#
  • Java
  • Node
<?php
    // Process HTTP POST variables
    $event          =   $_POST["event"];
    $reference      =   $_POST["reference"];
    $status         =   $_POST["status"];
    $date           =   $_POST["date"];
    $recipient      =   $_POST["recipient"];
    $sender         =   $_POST["sender"];
    $keyword        =   $_POST["keyword"];
    $message        =   $_POST["message"];
    $message_date   =   $_POST["message_date"];
    $scheduled_date =   $_POST["scheduled_date"];
?>
​