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:
- They must be provided as query parameters.
- They must be in ISO 8601 format (e.g.: YYYY-MM-DDTHH:mm:ss.SSSZ)
- 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 |
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 |
0 Comments