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	Description
sent_date	The timestamp when the message was submitted to downstream system for delivery.
delivered_date	The timestamp when the message has been delivered, corresponds to DR date.
converted_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.
scheduled_delivery_time	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.
expiry_time	This is the timestamp after which the messages will no Integer be sent to the downstream system for delivery.
created_date	The timestamp when the message was created, which corresponds to the time when the bulk message POST was done by the client.
last_updated_date	The data the resource was last changed.
pause_expiry_time	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:

GET

https://api.syniverse.com/scg-externalapi/api/v1/messaging/messages

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:

%5B2022-08-10T16%3A20%3A21.000Z%2C2022-08-10T16%3A20%3A22.000Z%5D

 

To encode a datetime field to the URL encoded format, you can use the tool: https://www.urlencoder.org/

To convert an epoch timestamp to ISO 8601 datetime, you can use the tool: https://www.epochconverter.com/

 

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 \
"https://api.syniverse.com/scg-external-api/api/v1/messaging/messages?\
offset=0&\
limit=20&\
sort=-created_date&\
created_date=%5B2022-01-20T00%3A00%3A00.000Z%2C2022-01-28T23%3A59%3A59.999Z%5D&\
to_address=%2B1346400XXXX" \
-H "Authorization: Bearer [TOKEN]"

 

Additional resources

Resource	Description
https://www.urlencoder.org/	An online tool that allows you to Encode to URL-encoded format
https://www.urldecoder.org/	An online tool that allows you to Decode from URL-encoded format
https://www.epochconverter.com/	Epoch & Unix Timestamp Conversion Tools