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

# Delivery status

> Interpret SMS lifecycle states and refresh provider status

Dugble tracks each SMS from queueing through its latest known provider or carrier outcome. Retrieve a message and inspect `last_event` for the current normalized state.

```bash theme={null}
curl --request GET \
  --url https://api.dugble.com/sms/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794 \
  --header "Authorization: Bearer $DUGBLE_API_KEY"
```

## Statuses

| Status        | Meaning                                                       | Final?          |
| ------------- | ------------------------------------------------------------- | --------------- |
| `queued`      | The SMS and its delivery job were created.                    | No              |
| `processing`  | A delivery worker claimed the message.                        | No              |
| `submitted`   | The provider accepted the message.                            | No              |
| `sent`        | The provider reported that the SMS was sent onward.           | No              |
| `delivered`   | Delivery was reported for the destination.                    | Yes             |
| `undelivered` | The provider or carrier could not deliver the SMS.            | Yes             |
| `rejected`    | The provider rejected the message.                            | Yes             |
| `expired`     | The delivery window expired before delivery.                  | Yes             |
| `failed`      | Dugble could not complete delivery.                           | Yes             |
| `unknown`     | The provider returned an unrecognized or indeterminate state. | Not necessarily |
| `canceled`    | A scheduled SMS was canceled before processing.               | Yes             |

Provider status support varies by route and destination. `submitted` or `sent` does not prove handset delivery.

## Refresh provider status

For a submitted message with provider identifiers, you can request a provider status refresh:

```bash theme={null}
curl --request POST \
  --url https://api.dugble.com/sms/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794/sync-status \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Idempotency-Key: status-refresh-49a3999c"
```

The response contains the public SMS object with the latest normalized `last_event` value.

## Failure information

For terminal failure states, the retrieve response can include a stable `failure` object:

```json theme={null}
{
  "failure": {
    "code": "SMS_UNDELIVERED",
    "message": "SMS could not be delivered"
  }
}
```

Dugble exposes stable public failure codes for `undelivered`, `rejected`, `failed`, and `expired` messages. Use the code for application logic and the message for display or diagnostics.

## Polling guidance

When polling message state:

* Poll only messages that are not in a final state.
* Apply backoff instead of polling continuously.
* Stop polling after a final state is reached.
* Use `sync-status` selectively because it performs a provider status lookup.

<Card title="SMS events" icon="timeline" href="/docs/sms/events">
  Inspect the event history recorded for an individual SMS message.
</Card>