How to retrieve messages by date

Specification v1.0, August 2022

 

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 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 section 3 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 +13464004474, 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

 

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

0 Comments

Please sign in to leave a comment.