Reporting

Use the Reporting API (version 3) to retrieve SMS, Email, WhatsApp, and RCS message records and analyze your outbound (MT) and inbound (MO) messaging traffic.

Statistical data is available in near real time. Filter requests and generate reports for periods of up to 92 days, with monthly, daily, or hourly aggregation.

Retrieve logs (records) in either format:

Message Status

Before you filter or retrieve logs, review message statuses. Each delivery channel uses its own statuses.

Get a Report (JSON)

Retrieve SMS, Email, WhatsApp, and RCS records for a specified period as JSON.

📘
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"

Long reporting periods can return many logs. Use the filters and pagination described in the following table to narrow the results.

HTTP request: GET /v3/mlog

Parameter	Required	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 broadcast.
channel	No	Delivery channel from which the message was sent. `"S"`: SMS `"E"`: Email `"W"`: WhatsApp. `"R"`: RCS. NOTE: 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 a comma (without Workspaces). For example: `SENT,EXPIRED`.

For example, retrieve messages sent between July 1 and July 2, 2023.

Set the start and end of the reporting period, then send the API request. The following response contains four sample logs, each for a message sent through a 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": "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
    }
  ]
}

The following table describes the response-body parameters:

Parameter	Description
items	List (array) of messages that were sent through a delivery channel.
items. channel	Delivery channel from which the message was sent. `"S"`: SMS `"E"`: Email `"W"`: WhatsApp `"R"`: RCS
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 broadcast.
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. `"A"`: Android (Google) `"I"`: iOS (Apple)
items. subject	Only applies when the message was sent through the Email channel. Subject of the email.
items. direction	Direction of the message: `"O"`: Mobile message routed from a client or an application and delivered to the end user’s mobile phone is called a MT (Mobile Terminated). `"I"`: The term MO (mobile originated) message stands for a mobile message routed from an end user’s mobile device and delivered to a mobile phone or an application.
items. subscriberid	Unique identifier of the contact.

When you set the "pretty" parameter to false, the response uses non-human-readable field names:

{
  "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": "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. `"S"`: SMS `"E"`: Email `"W"`: WhatsApp `"R"`: RCS
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. `"A"`: Android (Google) `"I"`: iOS (Apple)
items. s	Only applies when the message was sent through the Email channel. Subject of the email.
items. t	Direction of the message: `"O"`: Mobile message routed from a client or an application and delivered to the end user’s mobile phone is called a MT (Mobile Terminated). `"I"`: The term MO (mobile originated) message stands for a mobile message routed from an end user’s mobile device and delivered to a mobile phone or an application.
items. u	Unique identifier of the contact.
items. v	Identifier of the message template used in the sending if applicable.
items. w	Message Template Parameters
items. sd	Reason (status description) why sending the WhatsApp/RCS message failed.

Export a Report (CSV)

Export SMS, Email, WhatsApp, and RCS records for a specified period as a CSV file delivered by email.

📘
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"

Long reporting periods can contain many logs. Use the filters described in the following table to narrow the export.

HTTP request: POST /v3/mlog

Parameter	Required	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 broadcast.
channel	No	Delivery channel from which the message was sent. `"S"`: SMS `"E"`: Email `"W"`: WhatsApp. `"R"`: RCS. NOTE: 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 a comma (without Workspaces). For example: `SENT,EXPIRED`.

The following example exports messages sent between July 1 and July 2, 2023. The CSV file is sent to "[email protected]" and "[email protected]".

{
  "emails": [
    "[email protected]",
    "[email protected]"
  ],
  "from": "[email protected]",
  "timezone": "GMT-0400"
}

The following table describes the request-body parameters:

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.

After you export 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\"}"
  }
}

The following table describes the response-body parameters:

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.

After the report is delivered, the CSV file contains the following columns. Each row represents a message sent through a delivery channel.

Parameter	Description
Channel	Delivery channel from which the message was sent. `"S"`: SMS `"E"`: Email `"W"`: WhatsApp `"R"`: RCS
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 broadcast.
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. `"A"`: Android (Google) `"I"`: iOS (Apple)
items. Subject	Only applies when the message was sent through the Email channel. Subject of the email.
Direction	Direction of the message: `"O"`: Mobile message routed from a client or an application and delivered to the end user’s mobile phone is called a MT (Mobile Terminated). `"I"` : The term MO (mobile originated) message stands for a mobile message routed from an end user’s mobile device and delivered to a mobile phone or an application.
Subscriberid	Unique identifier of the contact.
items. StatusDescription	Reason (status description) why sending the WhatsApp/RCS message failed.