How to retrieve messages by date


The SCG messaging APIs allow to retrieve one or multiple messages, using datetime fields as filters. The values of the datetime filters, must be properly formatted using the ISO 8601 format.

This document explains and provides examples of how to retrieve messages from the SCG platform, using datetime filters in ISO 8601 format.


Available datetime fields

You can use any of the following datetime fields as parameter to filter

Field name



The timestamp when the message was submitted to downstream system for delivery.


The timestamp when the message has been delivered, corresponds to DR date.


The timestamp when the message was converted. This will be set automatically by SCG for messages with link tracking. For external tracking, the customer must provide the converted timestamp.


The date and time that this message should be delivered. This is the user specific time as calculated by the SCG based on the destination time zone and requested time zone calculation.


This is the timestamp after which the messages will no Integer be sent to the downstream system for delivery.


The timestamp when the message was created, which corresponds to the time when the bulk message POST was done by the client.


The data the resource was last changed.


This is the timestamp after which all paused messages will expire and will be removed from the outbound queue. The maximum expiry time is 24h. If application creates a message request with Integer pause expiry time, the message request will fail.


Formatting the datetime range

The SCG API call to retrieve messages from SCG is the following:


Messages can be filtered by the datetime ranges, using the fields described in next section of this document.

The datetime fields must adhere to the following rules:

  1. They must be provided as query parameters.
  2. They must be in ISO 8601 format (e.g.: YYYY-MM-DDTHH:mm:ss.SSSZ)
  3. They must be URL-encoded.

For example, the URL encoded value of the datetime range:

[2022-08-10T16:20:21.000Z,2022-08-10T16:20:22.000Z] is:



To encode a datetime field to the URL encoded format, you can use the tool:

To convert an epoch timestamp to ISO 8601 datetime, you can use the tool:


Example: Retrieving messages created in a time range

The following example shows how to retrieve all the messages sent to address +1346400XXXX, between Jan 20, 2022, and Jan 28, 2022.

curl -L -X GET \
to_address=%2B1346400XXXX" \
-H "Authorization: Bearer [TOKEN]"


Additional resources



An online tool that allows you to Encode to URL-encoded format

An online tool that allows you to Decode from URL-encoded format

Epoch & Unix Timestamp Conversion Tools


Was this article helpful?
0 out of 0 found this helpful


Please sign in to leave a comment.