Delivery Reports

Delivery reports are essential for tracking the status of messages sent via the Cecula API. They provide insight into whether messages were successfully delivered, failed, or encountered any other issues during transmission. By integrating delivery reports into your system, you can efficiently monitor and handle the outcome of sent messages.

Types of Delivery Reports

Cecula API supports two types of delivery reports for tracking the status of sent messages:

a) Webhook Delivery Report

The Webhook Delivery Report is an immediate notification method, where the Cecula system sends a detailed delivery report to a URL that you specify as soon as they become available. This provides real-time updates on the delivery status of your messages.

b) Periodic Polling

The Periodic Polling method involves sending requests to Cecula’s API at regular intervals to retrieve the status of your messages. This method is ideal for systems that do not require immediate status updates but still need to periodically check the delivery status.

Webhook Delivery Report

To start receiving delivery reports via Webhook, follow these steps:

Step 1: Define the Webhook URL

• Set up a listener endpoint on your server where Cecula can send the delivery reports. This URL will be configured in your Cecula settings.
  
  

Step 2: Configure Webhook in Cecula API

• Once you’ve set up your endpoint, log in to your Cecula account and configure the Webhook URL in the API settings.

🕺 Let's Go!

Log in to Cecula DartPro, navigate to the Settings screen (where API Keys are managed), and register the URL of your webhook. This is where delivery reports will be sent.

• Cecula will then send a POST request with the delivery report to the configured URL whenever a delivery status update occurs.
  
  

Step 3: Process Incoming Webhook Data

• Your endpoint must be able to process the incoming POST requests, which will contain delivery reports in JSON format.

💡 Remember!

Use the id returned in the response when sending SMS messages to identify the delivery report received on webhook. Always store this id for reference.

Periodic Polling

If you are sending messages from a stand-alone application designed to function independently from cloud servers or as offline-first platform such as Desktop Apps, Mobile Apps, Embedded Systems, etc., you want to use Periodic Polling To fetch delivery reports at your own schedule.

Here's how to fetch your delivery reports.

💡 Flash Back!

Remember the id (UUID) returned in the response when sending SMS messages? Yep! That's the reference you will use in the sample request below.

In this example we will be using the first id which had a value of b8bfb980-357a-4a39-863a-1b27c1f191d5.

Endpoint

• URL: /sms/delivery-report/{reference}
• Method: GET

Sample Request

curl --location 'https://app.cecula.com/api/sms/delivery-report/b8bfb980-357a-4a39-863a-1b27c1f191d5' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json'

Delivery Report Structure

Here is a sample delivery report:

{
    "reference": "b8bfb980-357a-4a39-863a-1b27c1f191d5",
    "mobile": "2348181234567",
    "sender": "Cecula",
    "status": "DELIVRD",
    "broadcastTime": "2024-10-08 07:41 AM",
    "pages": 1,
    "costPerPage": "1.50",
    "creditsDeducted": "1.50",
    "mccmnc": "060",
    "done": true,
    "doneDate": "2024-10-08 07:42 AM"
}

Description of Parameters

Parameter	Description	Example Value
reference	Unique identifier for the message sent. This allows you to track and associate the delivery report with the original message.	a86eba34-2011-4f25-9c34-4ae97b517262
id	Same as reference	a86eba34-2011-4f25-9c34-4ae97b517262
mobile	The recipient's mobile number. This helps identify the recipient.	2348038344968
sender	The sender name or identity of the sender (e.g., the name of the organization sending the message).	Cecula
status	The delivery status of the message. Common values: DELIVRD, UNDELIV, FAILED, REJECTD, EXPIRED.	DELIVRD
broadcastTime	The timestamp when the message was broadcast.	2024-10-08 07:11 AM
pages	The number of pages the message occupied (relevant for longer messages).	2
costPerPage	The cost of sending one page of the message.	1.50
creditsDeducted	The total credits deducted from your account for sending the message.	3.00
mccmnc	Mobile Country Code (MCC) and Mobile Network Code (MNC), identifying the network operator.	030
done	Indicates whether the delivery report has been processed. true means completed, false means still pending.	true
doneDate	The timestamp when the delivery process was completed.	2024-10-08 07:42 AM
sandbox	Optional response field indicates whether the message was sent in sandbox mode or not. Value can either be true or false.	false

Error Handling and Retries

• Failed Delivery Report: If a message fails to deliver, the status will be set to FAILED. Ensure that your system handles failed deliveries appropriately by retrying via other channels or notifying the user, depending on your use case.
• Retry Mechanism: If the Webhook cannot be delivered due to temporary network issues, Cecula will attempt to retry sending the delivery report. It's crucial to ensure that your Webhook endpoint is reliable and can handle retries gracefully.

💡 Important

If after 24 hours of periodic retry, Cecula will stop attempting to push the delivery report to your webhook. If you need to fetch the reports later, consider using the Polling method.

Delivery Status Codes

Status Code	Description
DELIVRD	Message was successfully delivered to the recipient.
UNDELIV	Message could not be delivered due to an error.
EXPIRED	Message expired before it could be delivered.
REJECTD	Message was rejected by the network or operator.
UNKNOWN	Unable to identify the network.
PENDING	Message is in progress and awaiting final status.
FAILED	Message failed to deliver for an unspecified reason.
NOCREDT	Message could not be sent due to insufficient account credit.
DND	Message was blocked due to Do Not Disturb (DND) settings.
SENT	Message has been sent but delivery confirmation is pending.

Best Practices

• Match by ID: Ensure you store the recipient id returned when the message is sent. Use this id to match the delivery report with the original SMS.

• Process Efficiently: Respond with an HTTP 200 status code as soon as you receive a delivery report. Perform any heavy processing (such as updating your database) asynchronously to avoid delays.

• Secure Your Webhook Endpoint: Ensure that the Webhook URL is secured, preferably by validating the source of the incoming request (e.g., by using a shared secret or verifying the User-Agent).

• Rate Limiting: Depending on your system’s load, it may be necessary to implement rate limiting to handle incoming reports efficiently.

• Logging and Auditing: Log incoming delivery reports for auditing purposes. This can be helpful for troubleshooting issues or tracking the performance of your messaging campaigns.

By utilizing the delivery reports, you can monitor the real-time status of your SMS campaigns, ensuring accurate tracking and improving user experience.