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

# Get message status

> Track delivery and read receipts using the ID returned when you send a message.

Save the `messageId` returned by a send endpoint, then request its latest status
with the same customer app token.

## Endpoint

| Field | Value |
| - | - |
| Method | `GET` |
| Path | `/api/messages/{messageId}/status` |
| Required header | `X-API-KEY: your-app-token` |

```bash theme={null}
curl "https://modawer.com/api/messages/01a172ee-9200-7000-8000-000000000001/status" \
  -H "X-API-KEY: your-app-token"
```

## Response

```json theme={null}
{
  "messageId": "01a172ee-9200-7000-8000-000000000001",
  "status": "Delivered",
  "deliveryChannel": "WhatsApp",
  "createdAt": "2026-10-25T12:00:00Z",
  "sentAt": "2026-10-25T12:00:01Z",
  "deliveredAt": "2026-10-25T12:00:02Z",
  "readAt": null,
  "failedAt": null,
  "failureCode": null,
  "failureReason": null
}
```

| Status | Meaning |
| - | - |
| `Pending` | Accepted for processing, or waiting for the next delivery channel. |
| `Sent` | The provider accepted the message. Delivery is not yet confirmed. |
| `Delivered` | The provider confirmed delivery. |
| `Read` | The provider confirmed the recipient read the message. |
| `Warning` | A provider warning or an uncertain outcome requiring reconciliation. |
| `Failed` | The active attempt failed and no fallback is pending. Check `failureCode` and `failureReason` when available. |

`deliveryChannel` identifies the active delivery attempt. During fallback it changes
to the next channel, and the status remains `Pending` until that attempt progresses.
Receipt timestamps describe that active attempt.

All timestamps use ISO 8601. Receipt timestamps are nullable. Provider timestamps
take precedence when available; otherwise the API records when the status was
reported or provider acceptance was observed. A read receipt without a delivery
timestamp does not create a delivery timestamp. Historical messages can have a
known status with null receipt timestamps and a null delivery channel.

Delivery and read receipts depend on provider reporting. A missing receipt does
not establish that the message failed. The endpoint excludes message content,
OTP values, recipient details, and provider identifiers.

## Authentication and errors

Use the customer app token that submitted the message. For OTPs sent through
Modawer's shared sender, use your own app token. Dashboard sessions and dev tokens
do not authorize this endpoint.

| HTTP status | Meaning |
| - | - |
| `400` | The message ID is not a valid UUID. |
| `401` | The app token is missing or invalid. |
| `404` | The message does not exist or belongs to another app. |

For polling, start with a two-second interval and back off for messages that remain
pending. Continue after `Sent` or `Delivered` if you need later receipts.

In development and OTP log-only mode, sends receive a durable ID but remain
`Pending` with null receipt timestamps because no provider receives the message.


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