Reporting
Reporting API (version 3) enables you to retrieve the messages (data) sent through the following delivery channels: SMS, Email, Push notification, WhatsApp, and RCS. You can use various filters for your requests and generate personalized reports for a specific period (less than 92 days) in which you have sent messages or notifications to our APIs and aggregate them with monthly, daily, or even hourly granularity.
Statistics data is available in near real-time. The Reporting API can help you monitor and analyze the messages sent to the recipients so you can optimize your usage with data insights.
Therefore, the Reporting API helps you analyze and gather information about your outbound (MT) and inbound messaging (MO) traffic.
Logs (records) are provided in JSON or CSV format:
Message Status
Before you start filtering or getting logs information, we recommend you read the following message status section. Each delivery channel has its own status. Therefore, this table is useful to understand the meaning of each status for each delivery channel.
Getting Report (JSON)
This endpoint allows retrieval of SMS, Email, Push notification, WhatsApp, RCS records sent over a specific period via JSON body.
NOTE
The max date range you can get the logs is 92 days.
If you set the date range more than 92 days, from the response body the parameter
"explain"will display the next message:"The date range exceeds the allowed limit: 92"If the size of the report which contains the records is too big, from the response body the parameter
"explain"will display the next message:"The size of the report is too big. Please contact support"
Statistics over an extended period could have a large number of logs. To make requests more responsive, we provide consistent filters and pagination as shown in the following table:
HTTP Request: GET /v3/mlog
| Parameter | Required Parameter | Description |
|---|---|---|
| from | Yes | The date and time is represented in UTC Zulu - ISO-8601 format (yyyy-mm-dd-Thh:mm:ss.ssZ) for the Start of the reporting period. For example: "2015-03-04T00:00:00.000Z" |
| to | Yes | The date and time is represented in UTC Zulu - ISO-8601 format (yyyy-mm-dd-Thh:mm:ss.ssZ) for the End of the reporting period. This must be after the start period time you defined in the "from" parameter.For example: "2015-03-04T00:00:00.000Z" |
| pretty | No | User-readable values - true: Set the value parameter in true to return a response with user-readable values.- false: Set the value parameter in false to return a response with non-user-readable values.We recommend set the "pretty" parameter in true |
| recipient | No | Enter the recipient's phone number or email address according to the delivery channel the message was sent to. For SMS, WhatsApp or RCS, you need to provide the phone number of the recipient. For Email, you need to provide the email address of the recipient. |
| campaignID | No | Unique identifier of the campaign. |
| channel | No | Delivery channel from which the message was sent. - S: SMS- E: Email- P: Push notification- W: WhatsApp- R: RCSNOTE: You can only filter by channel. That is, you cannot get logs from two or more delivery channels in the same request. |
| sender | No | Enter the sending identity (Sender) according to the delivery channel. |
| status | No | Status of the message. Each delivery channel has its own message status. NOTE: To filter by more than 1 status, enter each status separated by comma (without spaces). For example: SENT,EXPIRED |
For example, we are going to get the messages that were sent between July 01 and 02, 2023.
Once you have set the date range (start and ending) of the reporting period, we proceed to execute the API call, the following response body example contains 5 logs. According to the example, each log corresponds to a message that was sent from a specific delivery channel.
{
"meta": {
"timestamp": 1692668448063,
"transactionId": "ebea1509-2be3-4d53-8ff1-937db33ade79"
},
"pagination": {
"total": 2230
},
"items": [
{
"channel": "S",
"sender": "STRESS1",
"recipient": "+525500000000",
"date": "2023-07-28T13:46:51.144Z",
"campaignid": "11111",
"status": "SENT",
"statusdate": "2023-07-28T13:46:51.170Z",
"content": "Welcome to EliPackage!",
"platform": null,
"subject": null,
"direction": "O",
"subscriberid": null
},
{
"channel": "E",
"sender": "[email protected]",
"recipient": "[email protected]",
"date": "2023-07-28T16:20:30.241Z",
"campaignid": "14145",
"status": "OPEN",
"statusdate": "2023-07-28T21:56:21.620Z",
"content": null,
"platform": null,
"subject": "New Promo!",
"direction": "O",
"subscriberid": null
},
{
"channel": "P",
"sender": "DemoApp",
"recipient": "fv8aC_Emw0fRuN",
"date": "2023-07-03T06:51:39.521Z",
"campaignid": "15158",
"status": "SENT",
"statusdate": "2023-07-03T06:51:39.754Z",
"content": null,
"platform": "A",
"subject": null,
"direction": "O",
"subscriberid": null
},
{
"channel": "W",
"sender": "58412",
"recipient": "5800000000",
"date": "2023-07-31T23:59:15.765Z",
"campaignid": 12151,
"status": "READ",
"statusdate": "2023-07-31T23:59:15.783Z",
"content": "This is a new product!",
"platform": null,
"subject": null,
"direction": "I",
"subscriberid": null
},
{
"channel": "R",
"sender": "61e9bb8f4a01ea",
"recipient": "+525500000001",
"date": "2023-07-21T17:06:57.372Z",
"campaignid": "14320",
"status": "SENT",
"statusdate": "2023-07-21T17:06:57.969Z",
"content": "Hi! Welcome to the new Coffee Shop!",
"platform": null,
"subject": null,
"direction": "O",
"subscriberid": null
}
]
}
Parameters presented in the response body example when getting the logs are the following:
| Parameter | Description |
|---|---|
| items | List (array) of messages that were sent through a delivery channel. |
| items.channel | Delivery channel from which the message was sent.
|
| items.sender | Sending identity (Sender) according to the delivery channel. |
| items.recipient | Recipient's phone number or email address according to the delivery channel the message was sent to. For SMS, WhatsApp or RCS, it corresponds to the recipient's phone number. For Email, it corresponds to the recipient's email address. |
| items.date | Date when the message was sent. The date and time is represented in UTC Zulu - ISO-8601 format (yyyy-mm-dd-Thh:mm:ss.ssZ). |
| items.campaignid | Unique identifier of the campaign. |
| items.status | Status of the message. Each delivery channel has its own message status. To know the status message of each delivery channel go to the Message Status section. |
| items.statusdate | Date when the last update or status change. The date and time is represented in UTC Zulu - ISO-8601 format (yyyy-mm-dd-Thh:mm:ss.ssZ). |
| items.content | Content of the message sent to the end user. For Email, the content of the message will not be displayed. Therefore, the value of the parameter is null. |
| items.platform | Operating system of the recipient that received the notification.
|
| items.subject | Only applies when the message was sent through the Email channel. Subject of the email. |
| items.direction | Direction of the message:
|
| items.subscriberid | Unique identifier of the subscriber. |
In case you set the "pretty" parameter in false (non-user- readable values), the Example Response Body is the next:
{
"meta": {
"timestamp": 1692803372871,
"transactionId": "5c00068a-7bc9-4a0c-aa79"
},
"pagination": {
"total": 2230
},
"items": [
{
"a": "S",
"b": "STRESS1",
"c": "+525500000000",
"d": "2023-07-28T13:46:51.144Z",
"e": null,
"f": "+525500000000",
"g": "dev",
"h": "[email protected]",
"i": "11111",
"j": "SENT",
"k": "2023-07-28T13:46:51.170Z",
"l": "Welcome to EliPackage!",
"m": null,
"n": null,
"o": "0cb04d8c095d4b33bf77777b6",
"p": null,
"r": null,
"s": null,
"t": "O",
"u": null,
"v": null,
"w": null
},
{
"a": "E",
"b": "[email protected]",
"c": "[email protected]",
"d": "2023-07-28T16:20:30.241Z",
"e": "[email protected]",
"f": null,
"g": "dev",
"h": "[email protected]",
"i": "14145",
"j": "OPEN",
"k": "2023-07-28T21:56:21.620Z",
"l": "This is a new promotion!",
"m": null,
"n": null,
"o": "0cb04d8c095101033bf00",
"p": null,
"r": null,
"s": "New Promotion!",
"t": "O",
"u": null,
"v": null,
"w": null
},
{
"a": "P",
"b": "DemoApp",
"c": "fv8aC_Emw0fRuN",
"d": "2023-07-03T06:51:39.521Z",
"e": null,
"f": null,
"g": "dev",
"h": "[email protected]",
"i": "15158",
"j": "SENT",
"k": "2023-07-03T06:51:39.754Z",
"l": null,
"m": null,
"n": null,
"o": "0cb04d8c095d4b399898",
"p": "DemoApp",
"r": "A",
"s": null,
"t": "O",
"u": null,
"v": null,
"w": null
},
{
"a": "W",
"b": "58412",
"c": "+5800000000",
"d": "2023-07-31T23:59:15.765Z",
"e": null,
"f": "+5800000000",
"g": "dev",
"h": "[email protected]",
"i": "12151",
"j": "READ",
"k": "2023-07-31T23:59:15.783Z",
"l": "This is a new product!",
"m": null,
"n": null,
"o": "0cb04d8c095d4b33bf121212",
"p": null,
"r": null,
"s": null,
"t": "I",
"u": null,
"v": null,
"w": null
},
{
"a": "R",
"b": "61e9bb8f4a01ea",
"c": "+525500000001",
"d": "2023-07-21T17:06:57.372Z",
"e": null,
"f": "+525500000001",
"g": "dev",
"h": "[email protected]",
"i": "14320",
"j": "SENT",
"k": "2023-07-21T17:06:57.969Z",
"l": "Hi! Welcome to the new Coffee Shop!",
"m": null,
"n": null,
"o": "0cb04d8c095d4b33bf72727272",
"p": null,
"r": null,
"s": null,
"t": "O",
"u": null,
"v": null,
"w": null
}
]
}
Parameters presented in the response body example when getting the logs are the following:
| Parameter | Description |
|---|---|
| items | List (array) of messages that were sent through a delivery channel. |
| items.a | Delivery channel from which the message was sent.
|
| items.b | Sending identity (Sender) according to the delivery channel. |
| items.c | Recipient's phone number or email address according to the delivery channel the message was sent to. For SMS, WhatsApp or RCS, it corresponds to the recipient's phone number. For Email, it corresponds to the recipient's email address. |
| items.d | Date when the message was sent. The date and time is represented in UTC Zulu - ISO-8601 format (yyyy-mm-dd-Thh:mm:ss.ssZ). |
| items.e | Recipient's email address according to the delivery channel the message was sent to. |
| items.f | Recipient's phone number according to the delivery channel the message was sent to. |
| items.g | Owner or creator of the message transaction. |
| items.h | User who is a member of the owner or creator of the message. |
| items.i | Alphanumeric identifier that can be used for reporting purposes. |
| items.j | Status of the message. Each delivery channel has its own message status. To know the status message of each delivery channel go to the Message Status section. |
| items.k | Date when the last update or status change. The date and time is represented in UTC Zulu - ISO-8601 format (yyyy-mm-dd-Thh:mm:ss.ssZ). |
| items.l | Content of the message sent to the end user. |
| items.m | Unique user identifier that can be used for reporting purposes. |
| items.n | Only applies when the message was sent through the Email channel. Additional email address that you can use with your existing email account instead of your personal email address. |
| items.o | Unique identifier for the connector. |
| items.p | Only applies when the message was sent through the RCS channel. Agent's unique identifier. Set by RCS Business Messaging. |
| items.r | Operating system of the recipient that received the notification.
|
| items.s | Only applies when the message was sent through the Email channel. Subject of the email. |
| items.t | Direction of the message:
|
| items.u | Unique identifier of the subscriber. |
| items.v | Identifier of the template used in the sending if applicable. |
| items.w | Template Parameters |
| items.sd | Reason (status description) why sending the WhatsApp/RCS message failed. |
Exporting Report (CSV)
This endpoint allows retrieval of SMS, Email, Push notification, WhatsApp, RCS records sent over a specific period.
NOTE
- The generated report contains the logs of sent messages and will be sent directly to one or more email addresses in CSV format.
- The max date range you can get the logs is 92 days.
- If you set the date range more than 92 days, from the response body the parameter
"explain"will display the next message:"The date range exceeds the allowed limit: 92"- If the size of the report which contains the records is too big, from the response body the parameter
"explain"will display the next message:"The size of the report is too big. Please contact support"
Statistics over an extended period could have a large number of logs. To make requests more responsive, we provide consistent filters and pagination as shown in the following table:
HTTP Request : POST /v3/mlog
| Parameter | Required Parameter | Description |
|---|---|---|
| from | Yes | The date and time is represented in UTC Zulu - ISO-8601 format (yyyy-mm-dd-Thh:mm:ss.ssZ) for the Start of the reporting period. For example: "2015-03-04T00:00:00.000Z" |
| to | Yes | The date and time is represented in UTC Zulu - ISO-8601 format (yyyy-mm-dd-Thh:mm:ss.ssZ) for the End of the reporting period. This must be after the start period time you defined in the "from" parameter.For example: "2015-03-04T00:00:00.000Z" |
| recipient | No | Enter the recipient's phone number or email address according to the delivery channel the message was sent to. For SMS, WhatsApp or RCS, you need to provide the phone number of the recipient. For Email, you need to provide the email address of the recipient. |
| campaignID | No | Unique identifier of the campaign. |
| channel | No | Delivery channel from which the message was sent. - S: SMS- E: Email- P: Push notification- W: WhatsApp- R: RCSNOTE: You can only filter by channel. That is, you cannot get logs from two or more delivery channels in the same request. |
| sender | No | Enter the sending identity (Sender) according to the delivery channel. |
| status | No | Status of the message. Each delivery channel has its own message status. NOTE: To filter by more than 1 status, enter each status separated by comma (without spaces). For example: SENT,EXPIRED |
In the following API Call example, we are going to export the messages that were sent between July 01 and 02, 2023. The CSV file will be sent directly to the "[email protected]" and "[email protected]" addresses.
{
"emails": [
"[email protected]",
"[email protected]"
],
"from": "[email protected]",
"timezone": "GMT-0400"
}
The parameters presented in the request body example when exporting the logs are the following:
| Parameter | Required | Description |
|---|---|---|
| emails | Yes | List (array) of recipient emails where the CSV file will be sent. |
| from | Yes | Email address of the sender. |
| timezone | Yes | Timezone in GMT. |
| externalId | No | Alphanumeric identifier that can be used for reporting purposes. |
When you exported the logs, the response body contains the following data:
{
"meta": {
"timestamp": 1692717427850,
"transactionId": "1120626b-1742-487c-865e-920445c6a8e9",
"explain": "{\"reason\":\"You request is bein processed. Your report will be delivered in approx:\",\"timeSecAprox\":\"0\"}"
}
}
Parameters presented in the response body example when exporting the logs the following:
| Parameter | Description |
|---|---|
| explain | This parameter displays the next message explaining that the CSV file is being processed and the time (seconds) it will take to be sent to the email address. |
Once the report containing the logs has been sent to the email address, the CSV file example will contain the following columns and 5 logs. According to the example, each log corresponds to a message that was sent from a specific delivery channel.
| Parameter | Description |
|---|---|
| Channel | Delivery channel from which the message was sent.
|
| Sender | Sending identity (Sender) according to the delivery channel. |
| Recipient | Recipient's phone number or email address according to the delivery channel the message was sent to. For SMS, WhatsApp or RCS, it corresponds to the recipient's phone number. For Email, it corresponds to the recipient's email address. |
| Date | Date when the message was sent. The date and time is represented in UTC Zulu - ISO-8601 format (yyyy-mm-dd-Thh:mm:ss.ssZ). |
| Campaignid | Unique identifier of the campaign. |
| Status | Status of the message. Each delivery channel has its own message status. To know the status message of each delivery channel go to the Message Status section. |
| StatusDate | Date when the last update or status change. The date and time is represented in UTC Zulu - ISO-8601 format (yyyy-mm-dd-Thh:mm:ss.ssZ). |
| Content | Content of the message sent to the end user. For Email, the content of the message will not be displayed. Therefore, the value of the parameter is null. |
| Platform | Operating system of the recipient that received the notification.
|
| items.Subject | Only applies when the message was sent through the Email channel. Subject of the email. |
| Direction | Direction of the message:
|
| Subscriberid | Unique identifier of the subscriber. |
| items.StatusDescription | Reason (status description) why sending the WhatsApp/RCS message failed. |
Updated about 1 year ago