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.

Example delivery report payload

{
  "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

{
  "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.

{
  "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.