Skip to main content
Check the delivery status of sent SMS messages using this endpoint. You can filter results by a single message, an entire bulk campaign batch, or a specific delivery status. Results are paginated for efficient retrieval.
All requests must include the Authorization: Bearer YOUR_API_KEY header. Responses use Content-Type: application/json.

​
Endpoint

GET https://api.hany.tools/v1/sms/delivery-reports

​
Query Parameters

​
message_id
string
Filter results to a specific message. Use the message_id returned when you sent the message via POST /sms/send.
​
batch_id
string
Filter results to all messages belonging to a bulk campaign. Use the batch_id returned from POST /sms/bulk.
​
status
string
Filter results by delivery status. Accepted values: delivered, failed, pending, sent.
​
page
integer
Page number for paginated results. Defaults to 1.
​
limit
integer
Number of results to return per page. Defaults to 50. Maximum is 200.

​
Request

curl "https://api.hany.tools/v1/sms/delivery-reports?message_id=msg_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
200 — Success

{
  "status": "success",
  "data": [
    {
      "message_id": "msg_abc123xyz",
      "to": "+233XXXXXXXXX",
      "from": "YourBrand",
      "status": "delivered",
      "delivered_at": "2024-06-01T08:05:23Z",
      "sent_at": "2024-06-01T08:05:10Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1
  }
}

​
Response Fields

​
status
string
Indicates the outcome of the request. Either "success" or "error".
​
data
array
An array of delivery report objects matching your query.
​
data[].message_id
string
The unique identifier of the message. Matches the message_id from the send response.
​
data[].to
string
The recipient phone number in E.164 format.
​
data[].from
string
The Sender ID used to send this message.
​
data[].status
string
Current delivery status. One of pending, sent, delivered, or failed.
​
data[].delivered_at
string
ISO 8601 timestamp of when the message was confirmed delivered to the recipient’s handset. null if not yet delivered.
​
data[].sent_at
string
ISO 8601 timestamp of when the message was dispatched to the carrier network.
​
pagination
object
Metadata about the paginated result set.
​
pagination.page
integer
The current page number.
​
pagination.limit
integer
The number of results per page as requested.
​
pagination.total
integer
The total number of records matching your query across all pages.

​
Delivery Status Values

StatusDescription
pendingMessage is queued but has not yet been dispatched to the carrier network.
sentMessage has been dispatched to the carrier network and is awaiting handset confirmation.
deliveredDelivery confirmed — the message reached the recipient’s handset.
failedDelivery failed. The message could not be delivered to the recipient’s handset.

​
Code Examples

// Check delivery for a single message
const response = await fetch(
  "https://api.hany.tools/v1/sms/delivery-reports?message_id=msg_abc123xyz",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
    },
  }
);
const data = await response.json();
const report = data.data[0];
console.log(report.status);        // "delivered"
console.log(report.delivered_at);  // "2024-06-01T08:05:23Z"

// Check delivery for an entire bulk campaign
const batchResponse = await fetch(
  "https://api.hany.tools/v1/sms/delivery-reports?batch_id=batch_xyz789abc&status=failed&limit=100",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
    },
  }
);
const batchData = await batchResponse.json();
console.log(`Failed deliveries: ${batchData.pagination.total}`);
Use webhooks for real-time delivery notifications instead of polling this endpoint. Webhooks push status updates to your callback_url the moment a delivery event occurs, reducing API calls and eliminating latency.