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:

Access detailed information about all your sent messages to monitor delivery, track performance, and optimize your messaging strategy.

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.

Name	Type	Description
data	`object`	Contains message information.

Data Object

Name	Type	Description
id	`string`	Unique identifier of your message.
account_id	`string`	Unique identifier of your account.
status	`string`	Initial status of your message. Possible values: `PENDING`, `FAILED`, `DELIVERED`, `SEEN`
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`
direction	`string`	Indicates the flow of the message — whether it was sent by your system or received from a user. Possible values: `OUTBOUND`, `INBOUND`
country	`string`	Specifies the country of the recipient for outbound messages and the country of the sender for inbound messages. The value is provided in ISO 3166-1 alpha-2 format.
type	`string`	Indicates the type of message content being sent or received. This helps identify whether the message is a plain text, template-based, or media message (such as images or videos), including interactive content for WhatsApp.
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",
            "status": "PENDING",
            "from": "TopMessage",
            "to": "111511234567",
            "text": "Hi there! Just testing out this cool SMS feature. https://topmessage.com",
            "channel": "SMS",
            "segment_count": "1",
            "encoding": "STANDARD",
            "direction": "OUTBOUND",
            "country": "US",
            "type": "text",
            "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",
            "status": "PENDING",
            "from": "TopMessage",
            "to": "111511234568",
            "text": "Just giving this SMS feature a quick test.",
            "channel": "SMS",
            "segment_count": "1",
            "encoding": "STANDARD",
            "direction": "OUTBOUND",
            "country": "US",
            "type": "text",
            "schedule": "2024-11-10T08:11:46Z",
            "create_date": "2024-11-10T08:11:46Z",
            "update_date": "2024-11-10T08:11:46Z"
        }
    ]
}