> ## Documentation Index
> Fetch the complete documentation index at: https://developer.zeckta.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delivery Status Callbacks

> Receive real-time SMS delivery updates through callback URLs.

Zeckta can send real-time delivery status updates to a callback URL that you provide when submitting a message or campaign.

Instead of repeatedly polling the Message Status API, your application can receive delivery events automatically as they occur.

Callback URLs can be supplied when:

* Sending a single SMS
* Creating an SMS campaign

When a message reaches a significant delivery milestone, Zeckta performs an HTTP POST request to the configured callback URL.

***

## Supported Delivery Statuses

| Status          | Description                                             |
| --------------- | ------------------------------------------------------- |
| `SUBMITTED`     | Message accepted by Zeckta and queued for delivery.     |
| `SENT`          | Message successfully submitted to the upstream carrier. |
| `DELIVERED`     | Message confirmed delivered to the recipient handset.   |
| `FAILED`        | Delivery attempt failed.                                |
| `UNDELIVERABLE` | Destination number could not be reached.                |
| `EXPIRED`       | Message validity period expired before delivery.        |
| `REJECTED`      | Message was rejected before delivery processing.        |

The following internal processing states do not generate callback notifications:

* `QUEUED`
* `PROCESSING`
* `SCHEDULED`
* `BUFFERED`

***

## Event Types

Each callback includes an event type representing the delivery milestone that occurred.

| Event Type              | Delivery Status |
| ----------------------- | --------------- |
| `MESSAGE_SUBMITTED`     | `SUBMITTED`     |
| `MESSAGE_SENT`          | `SENT`          |
| `MESSAGE_DELIVERED`     | `DELIVERED`     |
| `MESSAGE_FAILED`        | `FAILED`        |
| `MESSAGE_UNDELIVERABLE` | `UNDELIVERABLE` |
| `MESSAGE_EXPIRED`       | `EXPIRED`       |
| `MESSAGE_REJECTED`      | `REJECTED`      |

***

## Configuring a Callback URL

### Single SMS

```json theme={null}
{
  "src": "ZECKTA",
  "dest": "+233202007745",
  "message": "Hello from Zeckta",
  "callbackUrl": "https://example.com/callbacks/sms"
}
```

### SMS Campaign

```json theme={null}
{
  "name": "June Promotion",
  "src": "ZECKTA",
  "dests": [
    "+233202007745",
    "+233244111222"
  ],
  "message": "Special offer available now.",
  "callbackUrl": "https://example.com/callbacks/campaigns"
}
```

***

## Example Callback Payload

```json theme={null}
{
  "eventId": "4075b658-81d8-4f66-8da4-eb88ac4592b6",
  "eventType": "MESSAGE_DELIVERED",
  "timestamp": "2026-06-09T13:04:57.487133482Z",
  "message": {
    "uuid": "016205e1-6653-47fa-9c8b-e5c46945b81e",
    "src": "ZECKTA",
    "dest": "+233202007745",
    "status": "DELIVERED",
    "segments": 1,
    "units": 1,
    "attempts": 1,
    "cost": 1
  }
}
```

***

## Payload Fields

### Event Metadata

| Field       | Description                                 |
| ----------- | ------------------------------------------- |
| `eventId`   | Unique identifier for the callback event.   |
| `eventType` | Delivery event being reported.              |
| `timestamp` | ISO-8601 timestamp when the event occurred. |

### Message Object

| Field              | Description                           |
| ------------------ | ------------------------------------- |
| `message.uuid`     | Unique identifier of the SMS message. |
| `message.src`      | Sender ID used for the message.       |
| `message.dest`     | Recipient phone number.               |
| `message.status`   | Current delivery status.              |
| `message.segments` | Number of SMS segments consumed.      |
| `message.units`    | Billing units consumed.               |
| `message.attempts` | Number of delivery attempts made.     |
| `message.cost`     | Final message cost, if available.     |

***

## Delivery Lifecycles

### Successful Delivery

```text theme={null}
MESSAGE_SUBMITTED
        ↓
MESSAGE_SENT
        ↓
MESSAGE_DELIVERED
```

### Failed Delivery

```text theme={null}
MESSAGE_SUBMITTED
        ↓
MESSAGE_FAILED
```

### Expired Message

```text theme={null}
MESSAGE_SUBMITTED
        ↓
MESSAGE_EXPIRED
```

### Rejected Message

```text theme={null}
MESSAGE_REJECTED
```

***

## HTTP Requirements

Your callback endpoint should:

* Accept HTTP POST requests
* Return a successful `2xx` response
* Be publicly accessible
* Support HTTPS
* Process notifications idempotently

Example response:

```http theme={null}
HTTP/1.1 200 OK
```

***

## Idempotency

Callback notifications should be treated as idempotent.

Although every callback contains a unique `eventId`, your application should safely handle duplicate deliveries without creating duplicate records or triggering duplicate business actions.

A common approach is to store previously processed `eventId` values and ignore duplicates.

***

## Best Practices

* Validate incoming callback payloads before processing.
* Log callback deliveries for troubleshooting.
* Store delivery events for auditing and analytics.
* Process callbacks asynchronously where possible.
* Return a `2xx` response immediately after accepting the notification.
* Use the Message Status API when historical delivery data is required.

***

## Message Status API

If you need to retrieve the latest delivery information on demand, use the Message Status API.

```http theme={null}
GET /v1/messaging/sms/messages/{messageId}
```

This endpoint returns the current status and metadata for a specific message.

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Message Status API" href="/messaging/get-message-status">
    Retrieve the latest delivery status for a message.
  </Card>

  <Card title="Delivery Statuses" href="/introduction/delivery-statuses">
    Learn about the SMS delivery lifecycle and status definitions.
  </Card>
</CardGroup>