---
title: "How to Get Delivery Reports"
description: "Track delivery updates for outbound SMS messages."
---

# How to Get Delivery Reports

Delivery reports let your application know whether a submitted SMS was delivered, failed, or is still pending.

## Endpoints

This page does not expose a Bulkit send endpoint. Delivery reports are posted to the webhook URL you configure in your application.

## Authorization

Bulkit does not send your API credentials back to your webhook. Protect the endpoint with your own controls such as:

- HTTPS only
- IP allowlisting
- URL query authorization tokens if desired
- Idempotent request handling

## What delivery reports are used for

- updating your internal message state
- reconciling support tickets
- triggering retries or fallback channels
- reporting on campaign performance

Configure your **DLR Webhook URL** under **API Keys** -> **Webhooks** in the dashboard. Once set, Bulkit forwards all delivery reports directly to that endpoint. For detailed documentation, visit [Delivery Reports Guide](/webhooks/delivery-reports).

## Example delivery report payload

```json
{
  "event": "sms.delivered",
  "message_id": "451980165",
  "internal_message_id": 144,
  "outbox_id": 33,
  "mobile": "254754424353",
  "status": "delivered",
  "description": "DeliveredToTerminal",
  "response_code": "200",
  "response_description": "Success",
  "delivered_at": "2026-03-09T11:21:06Z",
  "blacklisted": false,
  "sender_id": 12,
  "network_id": 2,
  "tat": "0.45 sec"
}
```

## Failure example

```json
{
  "event": "sms.failed",
  "message_id": "451980166",
  "internal_message_id": 145,
  "outbox_id": 34,
  "mobile": "254700000001",
  "status": "failed",
  "description": "Delivery failed at network",
  "response_code": "500",
  "response_description": "Network delivery failure",
  "delivered_at": null,
  "blacklisted": false,
  "sender_id": 12
}
```

## Blacklisted example

If QuickSMS returns `SenderName Blacklisted`, Bulkit forwards a blacklist-aware payload and records that MSISDN against the sender blacklist.

```json
{
  "event": "sms.blacklisted",
  "message_id": "452719776",
  "internal_message_id": 146,
  "outbox_id": 35,
  "mobile": "254700000001",
  "status": "blacklisted",
  "description": "SenderName Blacklisted",
  "response_code": "200",
  "response_description": "SenderName Blacklisted",
  "delivered_at": "2026-03-10T04:35:20Z",
  "blacklisted": true,
  "blacklist_reason": "SenderName Blacklisted",
  "sender_id": 12,
  "network_id": 1,
  "tat": "0.18 sec"
}
```

## Recommended handling

- store the delivery report against your internal message ID
- treat webhook delivery as asynchronous and eventually consistent
- keep the provider message ID for support and traceability
- handle `status: "blacklisted"` separately if you want to stop future sends for that sender and recipient pair

## Webhook headers

Bulkit includes standard HTTP headers when forwarding delivery reports:

- `Content-Type: application/json`
- `X-Bulkit-Webhook-Event: sms.delivered | sms.failed | sms.blacklisted | whatsapp.receipt.updated`

## Error response

Your webhook should return a `2xx` HTTP status code (such as `200 OK`) immediately upon receiving the payload. Any `4xx` or `5xx` response indicates to Bulkit that your server failed to process the callback.