> ## Documentation Index
> Fetch the complete documentation index at: https://docs.d-api.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> SMS delivery status events and normalized error codes.

SMS webhooks notify the **final delivery status** of each message. Each event
sets the value of the `status` field. The examples below use the [account
webhook envelope](https://docs.d-api.cloud/en/sms/webhooks/visao-geral.md); the campaign envelope carries
the same fields at the root level.

## Events and resulting status

| Event | When it fires | Resulting `status` |
| - | - | - |
| `sms.delivered` | The message was **delivered** to the recipient | `delivered` |
| `sms.undelivered` | The carrier reported that the message was **not delivered** | `undelivered` |
| `sms.failed` | **Network failure after acceptance** — the message has already been charged | `undelivered` |
| `sms.expired` | The message **expired** before being delivered | `expired` |

> [!NOTE]
>
> `sms.failed` maps to the `undelivered` status. It is a network failure that
> happened **after the send was accepted**: since billing closes at acceptance,
> the message **has already been charged**.

## `data` fields (account webhook)

**messageId** `string` *required*

Message ID. Lets you correlate the event with the original send.

**to** `string` *required*

Destination number in E.164 format.

**status** `string` *required*

Resulting status: `delivered`, `undelivered` or `expired`.

**errorCode** `string | null` *required*

Normalized error code in case of failure, or `null` when there is no error.
See the [error codes](#error-codes) table.

**segments** `number` *required*

Number of SMS segments (parts).

**timestamp** `string` *required*

Time of the event in ISO 8601 (UTC).

## Examples by event

> [accordion] sms.delivered — delivered
>
> ```json theme={null}
> {
>   "event": "sms.delivered",
>   "channel": "sms",
>   "data": {
>     "messageId": "a1b2c3d4-...",
>     "to": "+5511999999999",
>     "status": "delivered",
>     "errorCode": null,
>     "segments": 1,
>     "timestamp": "2026-01-24T23:00:00.000Z"
>   },
>   "timestamp": "2026-01-24T23:00:00.000Z"
> }
> ```

> [accordion] sms.undelivered — undelivered
>
> ```json theme={null}
> {
>   "event": "sms.undelivered",
>   "channel": "sms",
>   "data": {
>     "messageId": "a1b2c3d4-...",
>     "to": "+5511999999999",
>     "status": "undelivered",
>     "errorCode": "INVALID_NUMBER",
>     "segments": 1,
>     "timestamp": "2026-01-24T23:00:00.000Z"
>   },
>   "timestamp": "2026-01-24T23:00:00.000Z"
> }
> ```

> [accordion] sms.failed — network failure after acceptance
>
> ```json theme={null}
> {
>   "event": "sms.failed",
>   "channel": "sms",
>   "data": {
>     "messageId": "a1b2c3d4-...",
>     "to": "+5511999999999",
>     "status": "undelivered",
>     "errorCode": "NETWORK_ERROR",
>     "segments": 1,
>     "timestamp": "2026-01-24T23:00:00.000Z"
>   },
>   "timestamp": "2026-01-24T23:00:00.000Z"
> }
> ```

> [accordion] sms.expired — expired
>
> ```json theme={null}
> {
>   "event": "sms.expired",
>   "channel": "sms",
>   "data": {
>     "messageId": "a1b2c3d4-...",
>     "to": "+5511999999999",
>     "status": "expired",
>     "errorCode": null,
>     "segments": 1,
>     "timestamp": "2026-01-24T23:00:00.000Z"
>   },
>   "timestamp": "2026-01-24T23:00:00.000Z"
> }
> ```

## Error codes

When there is a failure, the `errorCode` field carries a **normalized** value.
The possible values are listed below.

| `errorCode` | Meaning |
| - | - |
| `NETWORK_ERROR` | Network error between the gateway and the carrier |
| `INVALID_NUMBER` | Invalid destination number |
| `LANDLINE` | Landline number (cannot receive SMS) |
| `BLACKLIST` | Number on a block list (blacklist) |
| `CANCELED` | Send canceled |
| `NO_WHATSAPP` | Destination has no WhatsApp |
| `CONTENT_BLOCKED` | Message content blocked |
| `NO_COVERAGE` | No coverage for the destination |
| `REJECTED` | Message rejected by the carrier |
| `NOT_RECEIVED` | Message not received by the destination |

> [!NOTE]
>
> On success (`sms.delivered`) or expiration (`sms.expired`) events, the
> `errorCode` field comes as `null`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.