# Check the message status

Use these endpoints to retrieve the delivery status of sent messages.
Before making requests, ensure you have configured [authentication](/products/sms/enterprise-documentation/developer-documentation/authentication-api-status).

| Endpoint | Use when |
|  --- | --- |
| [Get by message ID](#get-message-status-by-message-id) | You have the message ID returned by the send API |
| [Get by phone number](#get-latest-messages-by-phone-number) | You want the history of messages sent to a number |
| [Get by reference key](#get-latest-messages-by-reference-key) | You want to track messages by your own reference key |


For the full technical reference, see the [OpenAPI specification](/products/sms/openapi-api-status).

Use [webhooks](/products/sms/enterprise-documentation/developer-documentation/wb/wb-how) for real-time status updates (push).

## Response structure

All three endpoints return the same response structure. For the list endpoints (`/phonenumber` and `/reference`), the response is wrapped in a `messages` array; each item contains a `message` object with the fields below.

- **`id`**: Message identifier
- **`providerAcceptanceAt`**: Timestamp when the message was accepted by the provider (ISO 8601). Corresponds to the initial `PROVIDER_ACCEPTANCE` status
- **`statusChangedAt`**: Timestamp of the most recent status change (ISO 8601)
- **`reference`**: Reference object from the send request. May be empty `{}` if no reference was provided. See [Reference Attribute](/products/sms/enterprise-documentation/developer-documentation/integration-guide/attribute-reference)
- **`channel`**: Delivery channel — `SMS` or `RCS`
- **`status`**: Current delivery status. See [Status transitions](/products/sms/enterprise-documentation/developer-documentation/wb/wb-how#status-transition-diagram). Possible values:
  - `PROVIDER_ACCEPTANCE` — request accepted by the provider (initial state)
  - `SENT` — sent by the provider
  - `DELIVERED` — delivered to the handset
  - `REJECTED` — rejected by the provider (not sent)
  - `UNDELIVERED` — failed to deliver
  - `READ` — (RCS only) read by recipient
- **`provider`**: Provider information
  - **`name`**: Provider name
  - **`id`**: Provider's message identifier
  - **`status`**: Provider-specific status
  - **`code`**: Provider status/error code
  - **`message`**: Optional provider error details (e.g. `Number Blocked by Carrier`)
- **`sms`**:
  - **`segments`**: Number of SMS segments used. Messages exceeding 160 characters (GSM-7) or 70 characters (UCS-2) are split into multiple segments


## Authentication errors

All endpoints require a valid API key. Authentication failures return HTTP 401.

| HTTP Status | Error code | Error type | Solution |
|  --- | --- | --- | --- |
| `401` | 2 | `Empty or missing api-key` | The API key is missing or invalid. See [Authentication](/products/sms/enterprise-documentation/developer-documentation/authentication-api-status) |


## Get message status by message ID

Retrieves the delivery status for a specific message.

If the message ID is not found, the endpoint returns HTTP 404.

#### Endpoint


```
GET /api/messagestatus/{messageid}
```

#### Headers

| Name | Required | Description |
|  --- | --- | --- |
| `X-Api-Key` | Yes | API key for the account. See [Authentication](/products/sms/enterprise-documentation/developer-documentation/authentication-api-status). |


#### Path parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `messageid` | string | Yes | Message identifier (UUID format) |


#### Request example


```
GET /api/messagestatus/011d9d6e-b5b9-4cb9-be13-2bc336a923ce
```

#### Response examples

**200 — Message status**


```json
{
  "message": {
    "id": "011d9d6e-b5b9-4cb9-be13-2bc336a923ce",
    "providerAcceptanceAt": "2026-02-04T06:54:35Z",
    "statusChangedAt": "2026-02-04T06:54:55Z",
    "reference": {
      "service": "DIGITALSIGN",
      "action": "AUTH",
      "key": "EXT_KEY"
    },
    "channel": "SMS",
    "status": "DELIVERED",
    "provider": {
      "name": "PROVIDER1",
      "id": "bbe7a7b4-067b-484e-a55c-318f5716997e",
      "status": "delivered",
      "code": "0"
    },
    "sms": {
      "segments": 1
    }
  }
}
```

#### Error codes

| HTTP Status | Error code | Error type | Solution |
|  --- | --- | --- | --- |
| `404` | 1 | `Message not found` | The message ID does not exist |


## Get latest messages by phone number

Retrieves the delivery status of the latest messages sent to a given phone number.

If no messages are found, the endpoint returns HTTP 200 with an empty array: `{"messages": []}`.

#### Endpoint


```
GET /api/messagestatus/phonenumber/{phonenumber}
```

#### Headers

| Name | Required | Description |
|  --- | --- | --- |
| `X-Api-Key` | Yes | API key for the account. See [Authentication](/products/sms/enterprise-documentation/developer-documentation/authentication-api-status). |


#### Path parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `phonenumber` | string | Yes | Phone number in E.164 format (e.g. `+390000000000`) |


#### Query parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `count` | integer | No | Maximum number of messages to return. Range: 1–100. Default: 50. Values above 100 are silently capped |
| `sendDate` | string | No | Filter messages sent before this timestamp. Format: ISO 8601 (e.g. `2026-12-31T23:59:59Z`). Default: current time |


#### Request example


```
GET /api/messagestatus/phonenumber/+390000000000?count=1&sendDate=2026-12-31T23:59:59Z
```

#### Response examples

**200 — Messages list**


```json
{
  "messages": [
    {
      "message": {
        "id": "011d9d6e-b5b9-4cb9-be13-2bc336a923ce",
        "providerAcceptanceAt": "2026-02-04T06:54:35Z",
        "statusChangedAt": "2026-02-04T06:54:55Z",
        "reference": {
          "service": "DIGITALSIGN",
          "action": "AUTH",
          "key": "EXT_KEY"
        },
        "channel": "SMS",
        "status": "DELIVERED",
        "provider": {
          "name": "PROVIDER1",
          "id": "bbe7a7b4-067b-484e-a55c-318f5716997e",
          "status": "delivered",
          "code": "0"
        },
        "sms": {
          "segments": 1
        }
      }
    }
  ]
}
```

Each item in `messages` contains a `message` object with the fields described in [Response structure](#response-structure).

## Get latest messages by reference key

Retrieves the delivery status of the latest messages associated with the external key specified in the `reference.key` parameter of the [send](/products/sms/enterprise-documentation/developer-documentation/api-references/services-send) API.

If no messages are found, the endpoint returns HTTP 200 with an empty array: `{"messages": []}`.

#### Endpoint


```
GET /api/messagestatus/reference/{referencekey}
```

#### Headers

| Name | Required | Description |
|  --- | --- | --- |
| `X-Api-Key` | Yes | API key for the account. See [Authentication](/products/sms/enterprise-documentation/developer-documentation/authentication-api-status). |


#### Path parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `referencekey` | string | Yes | External reference key |


#### Query parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `count` | integer | No | Maximum number of messages to return. Range: 1–100. Default: 50. Values above 100 are silently capped |
| `sendDate` | string | No | Filter messages sent before this timestamp. Format: ISO 8601 (e.g. `2026-12-31T23:59:59Z`). Default: current time |


#### Request example


```
GET /api/messagestatus/reference/user-12345-verification?count=2&sendDate=2026-12-31T23:59:59Z
```

#### Response examples

**200 — Messages list**


```json
{
  "messages": [
    {
      "message": {
        "id": "011d9d6e-b5b9-4cb9-be13-2bc336a923ce",
        "providerAcceptanceAt": "2026-02-04T06:54:35Z",
        "statusChangedAt": "2026-02-04T06:54:55Z",
        "reference": {
          "service": "DIGITALSIGN",
          "action": "AUTH",
          "key": "EXT_KEY"
        },
        "channel": "SMS",
        "status": "DELIVERED",
        "provider": {
          "name": "PROVIDER1",
          "id": "bbe7a7b4-067b-484e-a55c-318f5716997e",
          "status": "delivered",
          "code": "0"
        },
        "sms": {
          "segments": 1
        }
      }
    }
  ]
}
```

Each item in `messages` contains a `message` object with the fields described in [Response structure](#response-structure).