Skip to content
DEVELOPER DOCUMENTATION
/
Message Status APIs
/API References/
Message status
Last updated

Check the message status

Use these endpoints to retrieve the delivery status of sent messages.
Before making requests, ensure you have configured authentication.

EndpointUse when
Get by message IDYou have the message ID returned by the send API
Get by phone numberYou want the history of messages sent to a number
Get by reference keyYou want to track messages by your own reference key

For the full technical reference, see the OpenAPI specification.

Use webhooks 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
  • channel: Delivery channel — SMS or RCS
  • status: Current delivery status. See Status transitions. 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 StatusError codeError typeSolution
4012Empty or missing api-keyThe API key is missing or invalid. See Authentication

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

NameRequiredDescription
X-Api-KeyYesAPI key for the account. See Authentication.

Path parameters

ParameterTypeRequiredDescription
messageidstringYesMessage identifier (UUID format)

Request example

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

Response examples

200 — Message status

{
  "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 StatusError codeError typeSolution
4041Message not foundThe 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

NameRequiredDescription
X-Api-KeyYesAPI key for the account. See Authentication.

Path parameters

ParameterTypeRequiredDescription
phonenumberstringYesPhone number in E.164 format (e.g. +390000000000)

Query parameters

ParameterTypeRequiredDescription
countintegerNoMaximum number of messages to return. Range: 1–100. Default: 50. Values above 100 are silently capped
sendDatestringNoFilter 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

{
  "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.

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 API.

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

Endpoint

GET /api/messagestatus/reference/{referencekey}

Headers

NameRequiredDescription
X-Api-KeyYesAPI key for the account. See Authentication.

Path parameters

ParameterTypeRequiredDescription
referencekeystringYesExternal reference key

Query parameters

ParameterTypeRequiredDescription
countintegerNoMaximum number of messages to return. Range: 1–100. Default: 50. Values above 100 are silently capped
sendDatestringNoFilter 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

{
  "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.

Previous page
Next page