# Check the message status

You can retrieve the delivery status of a message using the following APIs:

- `/api/messagestatus/{messageid}` - Check specific message
- `/api/messagestatus/phonenumber/{phonenumber}` - User message history
- `/api/messagestatus/reference/{referencekey}` - Track by reference


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

Before making requests, ensure you have configured [authentication](/products/sms/enterprise-documentation/developer-documentation/authentication-api-status).

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

#### Body Response

All endpoints return the following fields:

* **message**: Message information object:
  * **id**: Message identifier
  * **providerAcceptanceAt**: Timestamp when the message was accepted by the provider (ISO 8601 format, e.g., 2026-02-12T14:51:00Z). Corresponds to the initial PROVIDER_ACCEPTANCE status.
  * **statusChangedAt**: Timestamp of the most recent status change (ISO 8601 format, e.g., 2026-02-12T14:51:05Z).
  * **reference**: Reference object specified in the send request. May be an empty
object (`{}`) if no reference was provided. See [Reference
Attribute](/products/sms/enterprise-documentation/developer-documentation/integration-guide/attribute-reference) for details on the service, action, and key fields.
  * **channel** : Delivery channel. Possible values:
    * `SMS`
    * `RCS`
  * **status**: Current delivery status. See [Status Transitions](/products/sms/enterprise-documentation/developer-documentation/wb/wb-how#status-transition-diagram) for details. Possible values:
    * `PROVIDER_ACCEPTANCE`: Request accepted by the provider (initial state)
    * `SENT` : Request sent by the provider
    * `DELIVERED` : Message delivered to the handset
    * `REJECTED`: Request rejected by the provider. (not sent)
    * `UNDELIVERED` : Message failed to deliver
    * `READ` : (RCS only) Message 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**: SMS-specific information:
    * **segments** : Number of SMS segments used. Messages exceeding 160 characters (GSM-7) or 70 characters (UCS-2) are split into multiple segments.


#### HTTP errors

| HTTP Status | Error | Solution |
|  --- | --- | --- |
| 403 | Forbidden | 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

* **URL**: `/api/messagestatus/{messageid}`
* **Method**: `GET`


#### Headers

* `X-Api-Key: YOUR_API_KEY` (replace `YOUR_API_KEY` with your actual API key)


#### Path parameters

* `messageid`: Message identifier (UUID format)


#### Request Example

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

#### Response Example


```
{ 
  "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
    }
  }
}
```

### Get the latest messages status 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

* **URL**: `/api/messagestatus/phonenumber/{phonenumber}`
* **Method**: `GET`


#### Headers

* `Content-Type: application/json`
* `X-Api-Key: YOUR_API_KEY` (replace `YOUR_API_KEY` with your actual API key)


#### Path parameters

* `{phonenumber}` - Phone number in E.164 format (e.g., +1234567890)


#### Query parameters

* `count` (optional): Maximum number of messages to return. Range: 1-100. Default: 50. If a value greater than 100 is provided, it is silently capped to 100.
* `sendDate` (optional): 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/+1234567890?count=1&sendDate=2026-12-31T23:59:59Z`

#### Response Example


```
{
  "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
        }
      }
    }
  ]
}
```

### Get the latest messages status by the external 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

* **URL**: `/api/messagestatus/reference/{referencekey}`
* **Method**: `GET`


#### Headers

* `Content-Type: application/json`
* `X-Api-Key: YOUR_API_KEY` (replace `YOUR_API_KEY` with your actual API key)


#### Path parameters

* `{referencekey}` - external reference key
* 

#### Query parameters

* `count` (optional): Maximum number of messages to return. Range: 1–100. Default: 50. If a value greater than 100 is provided, it is silently capped to 100.
* `sendDate` (optional): 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 Example


```
{
  "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
        }
      }
    }
  ]
}
```