Broadcast Reporting API

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-ddTHH:mm:ss.SSSZ) 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-ddTHH:mm:ss.SSSZ) 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,
      "carrier": "Acme Mobile"
    }, 
    {
      "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,
      "carrier": 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,
      "carrier": 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,
      "carrier": 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-ddTHH:mm:ss.SSSZ).
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-ddTHH:mm:ss.SSSZ).
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.
items. carrier	Mobile operator (carrier) of the recipient. Currently, this information is available only for some mobile operators in Colombia. When it is not available, the value is `null`.

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,
      "fc": "Acme Mobile"
    }, 
    {
      "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,
      "fc": 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,
      "fc": 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,
      "fc": 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-ddTHH:mm:ss.SSSZ).
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-ddTHH:mm:ss.SSSZ).
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.
items. fc	Mobile operator (carrier) of the recipient. Currently, this information is available only for some mobile operators in Colombia. When it is not available, the value is `null`.

Get a Message

Retrieve the information and the current status of a single message by its unique identifier (ID). This request is available for messages sent through any of the supported delivery channels (SMS, Email, WhatsApp, and RCS), so you can query a message without needing a different request for each channel.

The message ID is returned in the response to the sending request. Use the value of the data.id parameter of that response as the id parameter of this request. Save this value when you send the message if you plan to check its status later.

HTTP request: GET /v3/mlog/id

Parameter Required Description

Yes

Parameter	Required	Description
id	Yes	Unique identifier (ID) of the message whose information you want to retrieve. This is the ID returned in the response when the message was sent.
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. This is the default value. We recommend setting the `"pretty"` parameter to `"true"`.

Unique identifier (ID) of the message whose information you want to retrieve. This is the ID returned in the response when the message was sent.

pretty

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. This is the default value. We recommend setting the "pretty" parameter to "true".

For example, retrieve the information of an SMS message by its ID. The response includes the pagination object and the items list. Because the ID identifies a single message, the items list contains only one record.

When you set the pretty parameter to true, the response uses user-readable field names:

{
  "meta": {
    "timestamp": 1692803372871,
    "transactionId": "5c00068a-7bc9-4a0c-aa79"
  },
  "pagination": {
    "limit": 1,
    "page": 1,
    "pages": 1,
    "total": 1
  },
  "items": [
    {
      "channel": "S",
      "sender": "12125550143",
      "recipient": "+525500000000",
      "date": "2023-07-28T13:46:51.144Z",
      "campaignid": null,
      "status": "DELIVRD",
      "statusdate": "2023-07-28T13:46:52.070Z",
      "content": "Welcome to the new Coffee Shop!",
      "platform": null,
      "subject": null,
      "direction": "O",
      "subscriberid": null,
      "carrier": null
    }
  ]
}

When you set the pretty parameter to false, or you omit it, the response uses non-user-readable field names:

{
  "meta": {
    "timestamp": 1692803372871,
    "transactionId": "5c00068a-7bc9-4a0c-aa79"
  },
  "pagination": {
    "limit": 1,
    "page": 1,
    "pages": 1,
    "total": 1
  },
  "items": [
    {
      "_id": "1a2b3c4d5e6f47a8b9c0d1e2f3a4b5c6",
      "a": "S",
      "b": "12125550143",
      "c": "+525500000000",
      "d": "2023-07-28T13:46:51.144Z",
      "e": null,
      "f": "+525500000000",
      "g": "dev",
      "h": "dev",
      "i": null,
      "j": "DELIVRD",
      "k": "2023-07-28T13:46:52.070Z",
      "l": "Welcome to the new Coffee Shop!",
      "m": null,
      "n": null,
      "o": "0cb04d8c095d4b33bf77777b6",
      "p": null,
      "r": null,
      "s": null,
      "t": "O",
      "u": null,
      "v": null,
      "w": null,
      "fc": null
    }
  ]
}

The following example shows the record of a WhatsApp message sent with a message template. In this case, the items.l parameter (items.content when the pretty parameter is true) contains the details of the template used in the sending, instead of the text of the message.

{
  "meta": {
    "timestamp": 1692803372871,
    "transactionId": "5c00068a-7bc9-4a0c-aa79"
  },
  "pagination": {
    "limit": 1,
    "page": 1,
    "pages": 1,
    "total": 1
  },
  "items": [
    {
      "_id": "7f8e9d0c1b2a43c4d5e6f7a8b9c0d1e2",
      "a": "W",
      "b": "12125550143",
      "c": "+525500000001",
      "d": "2023-07-28T14:10:22.318Z",
      "e": null,
      "f": "+525500000001",
      "g": "dev",
      "h": "dev",
      "i": null,
      "j": "SENT",
      "k": "2023-07-28T14:10:23.204Z",
      "l": "{\"type\":\"template\",\"subType\":null,\"template\":{\"id\":\"1234567890123456\",\"name\":\"order_confirmation\",\"language\":\"en\",\"category\":\"UTILITY\",\"components\":[{\"type\":\"BODY\",\"text\":\"Hi! Your order has been confirmed.\",\"buttons\":[],\"cards\":[]}]}}",
      "m": null,
      "n": null,
      "o": "wamid.HBgNNTI1NTAwMDAwMDAxFQIAERgSQTFCMkMzRDRFNUY2RzdIOAA=",
      "p": null,
      "r": null,
      "s": null,
      "t": "O",
      "u": null,
      "v": "order_confirmation",
      "w": null,
      "fc": null
    }
  ]
}

Each record contains the same parameters described in the response-body tables of Get a Report (JSON). The table of user-readable values applies when the pretty parameter is true, and the table of non-user-readable values applies when it is false.

Use the items.status parameter (items.j when the pretty parameter is false) to check the current status of the message, and the items.statusdate parameter (items.k) to know the date of that status. For more information about the possible values, see message statuses.

The items._id parameter, which contains the unique identifier (ID) of the message, is included only when the pretty parameter is false. The response with the pretty parameter set to true does not include it.

If no message matches the ID you provide, the request returns the HTTP status code 404, and the errors.reason parameter of the response displays the following message: Mlog with id <id> was not found.

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-ddTHH:mm:ss.SSSZ) 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-ddTHH:mm:ss.SSSZ) 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-ddTHH:mm:ss.SSSZ).
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-ddTHH:mm:ss.SSSZ).
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.
Carrier	Mobile operator (carrier) of the recipient. Currently, this information is available only for some mobile operators in Colombia. When it is not available, the value is `null`.

Message Status

Get a Report (JSON)

NOTE

Get a Message

Export a Report (CSV)

NOTE

What’s Next