TopMessage API Documentation | Retrieve Messages & Verify Codes

Get Message

Retrieve details for both incoming and outgoing messages, and verify authentication codes sent to your customers. Access a list of all messages or find information about a specific message using the unique message ID provided when it was created or received.

Use Case Examples

The user verification was successful if the header X-Total-Count has got value 1 or the data object list in response is not empty.

The following are some examples of use cases for the TopMessage API:

Full Request Parameters

No request parameters are required.

Full Response Parameters

The response includes all parameters from the request, along with the additional parameters listed below.

Data Object

Name	Type	Description
id	`string`	Unique identifier of your message.
account_id	`string`	Unique identifier of your account.
from	`string`	The name your message will appear to be sent from. You can customize it with your company name (up to 11 characters) or use a virtual number.
to	`string[]`	The recipient's mobile phone number(s) in international format.
text	`string[]`	Your message text to be sent to the recipient(s).
channel	`string`	The communication channel your message sent through. Possible values: `SMS` and `WHATSAPP` Default: `SMS`
segment_count	`integer`	The number of segments your message consisted of.
encoding	`string`	Encoding of your message. Possible values: `STANDARD` and `UNICODE`
schedule	`string`	Specifies the time when the message should be sent. The time must be in UTC and follow the ISO-8601 format ("2024-12-01T18:00:00Z"). The scheduled time cannot be set for more than 1 year in the future. Default: Now
create_date	`string`	Time when the message was initiated
update_date	`string`	Last status update date of your message.

GET

https://api.topmessage.com/v1/messages

X-TopMessage-Key: {API_KEY}
Content-Type: application/json

Response Sample

'X-Total-Count': 1

{
    "data": [
        {
            "id": "0f15fa5d-97ef-46d5-844a-f507f1c4c461",
            "account_id": "0d1f7f1c-27df-41bf-8bdc-5666608a4285",
            "from": "TopMessage",
            "to": "111511234567",
            "text": "Hi there! Just testing out this cool SMS feature. https://topmessage.com",
            "channel": "SMS",
            "segment_count": "1",
            "encoding": "STANDARD",
            "schedule": "2024-11-10T08:11:46Z",
            "create_date": "2024-11-10T08:11:46Z",
            "update_date": "2024-11-10T08:11:46Z"
        },
        {
            "id": "6fc214dc-4e51-4fce-bc0a-324a1d8a542b",
            "account_id": "0d1f7f1c-27df-41bf-8bdc-5666608a4285",
            "from": "TopMessage",
            "to": "111511234568",
            "text": "Just giving this SMS feature a quick test.",
            "channel": "SMS",
            "segment_count": "1",
            "encoding": "STANDARD",
            "schedule": "2024-11-10T08:11:46Z",
            "create_date": "2024-11-10T08:11:46Z",
            "update_date": "2024-11-10T08:11:46Z"
        }
    ]
}