API Reference

Be the first to explore your data in our new reporting API, now in beta. You can start testing the Reporting API using the REST API key that is provided in your Dashboard here. If you would have feedback or missing functionality, email our product manager here. We are working on adding Inbox Reporting.

MessageBird’s Reporting API enables you to programmatically retrieve reports on SMS, Voice, and Conversations performed on our platform. You can use various filters and group-by parameters for your requests and generate personalized reports for any period in which you have used 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 your use of MessageBird APIs so you can optimize your usage with data insights.

The Reporting API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization framework. Request and response payloads are formatted as JSON—although we provide a GET alternative for requests—using UTF-8 encoding and URL encoded values.

API Endpoint

All URLs referenced in MessageBird's Reporting Messaging API documentation have the base URL in the code snippet on the right side:

The request parameters values have to be URL-encoded. Please check the documentation of your programming language or HTTP client, a method or function for URL-encoding should be provided. For example, the date and time `2018-04-01T15:04:05+07:00` would be `2018-04-01T15%3A04%3A05%2B07%3A00` after URL-encoding.

API Endpoint

https://rest.messagebird.com/reporting

Rate limiting

MessageBird has made near real-time insights available to our customers. Still, analytical queries with aggregations and filters on a vast amount of data could take a long time and resources. To ensure reliable service for all our customers, we impose rate limiting on this API. More precisely, per Access Key. We will handle at most five requests per second and five simultaneous requests. Excess requests receive an HTTP status 429 (Too Many Requests).

Pagination

Statistics over an extended period could have a large number of items. To make requests more responsive, we provide consistent pagination.

We have updated the way of pagination to make it more consistent with our other APIs. Now a part of items can be obtained by specifying offset and limit. offset means the number of elements to skip and limit represents the number of items to return. For example, to get the first 100 items, offset and limit should be set to 0 and 100, respectively. The response will contain 100 elements (possibly less if there are less than 100 items in total), a field totalCount representing the number of items in total and a reference token ref. ref ensures consistent pagination, meaning that the dataset will not change with updated information as long as the reference token remains the same. To obtain any other part of the result, you need to change offset and limit and set the reference token accordingly in your new request. Note the token will expire in one day.

Deprecated: For SMS reporting only, by default, the first page with 500 items is returned, if the total number of items is larger than 500. Otherwise, a single page containing all items is returned. A user can also specify any integer number between 1 and 2500 (both inclusive) as the page size. Along with the first page, the response includes a link to get the next page (if applicable). The link looks almost identical to the original request, except for pageNumber, pageSize, and a reference token. This token ensures that a customer always has consistent pagination, meaning that the dataset will not change with updated information as long as the reference token remains the same. If there are any following pages, a user can iterate through them by following those links. A user may jump over several pages by setting pageSize and pageNumber. Note that a reference token is required for any page after the first.

Pagination is only used with JSON responses. If you request CSV output, offset and limit or pageSize and pageNumber are ignored and the complete available dataset is returned. Moreover, you cannot use offset, limit and pageSize, pageNumber at the same time.

SMS

Required parameters

Attribute	Type	Description
periodStart	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the start of the reporting period.
periodEnd	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

Attribute	Type	Description
periodGroup	string	The time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezone	string	The timezone to group and display the results in the time-dimension, such as “Europe/Amsterdam” or “US/Central”. All location names in the IANA Time Zone Database are valid. Default: UTC.
groupBy	string list	Zero or more values from country, networkCode, originator, account. More than one value can be specified by repeating the query parameter. For example, groupBy=account&groupBy=country groups items by account AND country. Note you cannot group by status any more, for it is integrated into every insight. Each insight includes counts of messages that are in different statues, including delivered, processing, failed, delivery_impossible (for example an invalid recipient). Default: empty.
filterBy[]		You can specify multiple filters as explained below. Specifying the same type of filter multiple times with different values is considered a union query, which means that the reports contains all messages that match one of the conditions. The same is true if multiple country-related filters are defined, for example filterBy[mcc]=204&filterBy[countryCode]=US returns all messages sent to the Netherlands or the United States (see explanations below). Specifying multiple different filters results in an intersection query, for example filterBy[countryCode]=UK&filterBy[originator]=messagebird only returns messages sent to the United Kingdom from MessageBird.
filterBy[account]	string	Filters by sub account name. More than one account name can be provided by repeating the query parameter, for example filterBy[account]=account1&filterBy[account]=account2
filterBy[mcc]	integer	A three digit Mobile Country Code, as defined in ITU E.212, for example 204 for the Netherlands. More than one MCC can be provided by repeating the query parameter, such as filterBy[mcc]=204&filterBy[mcc]=404&filterBy[mcc]=405. Default: empty.
filterBy[countryCode]	string	An ISO 639 country code, for example DE for Germany. It will be translated to filterBy[mcc]. For example, filterBy[countryCode]=NL will be translated to filterBy[mcc]=204. More than one code can be provided by repeating the query parameter, for example filterBy[countryCode]=NL&filterBy[countryCode]=IN. Default: empty.
filterBy[countryPrefix]	integer	A country telephone prefix, for example 91 for India. It will be translated to filterBy[mcc]. For example, filterBy[countryCode]=31 will be translated to filterBy[mcc]=204. More than one prefix can be provided by repeating the query parameter, for example filterBy[countryPrefix]=31&filterBy[countryPrefix]=91.
filterBy[networkCode]	integer	A 5-6 digit Mobile Network Code, as defined in ITU-T E.212 (MCC/MNC tuple), for example 20408 for KPN Mobile Netherlands. More than one code can be provided by repeating the query parameter.
filterBy[originator]	string	An originator that has been used for sending messages, which can either be a phone number or an alphanumeric sender. Note messages sent before March 9, 2018 cannot be filtered based on this field.
filterBy[status]	string	Filters by message status, valid values are delivered, processing, failed, delivery_impossible. More than one status can be provided by repeating the query parameter, for example filterBy[status]=processing&filterBy[status]=delivered
sort	string	Specify sort criteria with the following syntax: key1:direction1[,key2:direction2]. If a direction is omitted, asc (ascending) is assumed. Valid keys are submittedCount, deliveredCount, processingCount, failedCount, deliveryImpossibleCount. Valid directions are asc, desc. The appearance order of more than one key will be preserved when sorting a result. Further, the sorted result will be sorted by time in ascending order. For example, sort=deliveredCount:desc will sort results by deliveredCount in descending order. And the items having the same deliveredCount will be sorted in time ascending order.
pageNumber [deprecated]	integer	The page to be accessed. Default: 1, the first page.
pageSize [deprecated]	integer	Valid values are any integer number between 1 and 2500, both inclusive. A number larger than 2500 will be clipped to 2500. Default: 500.
offset	integer	The number of elements to skip. Default: 0, skipping zero element.
limit	integer	The number of elements to return. Valid values are any integer number between 1 and 2500, both inclusive. A number larger than 2500 will be clipped to 2500. Default: 500.
ref	string	A string to ensure consistency of pagination. When accessing the first part of result, it will be included in the response. To access further parts it needs to be added as a request query parameter.

Available HTTP Methods

GET /sms

Example Request

curl -X GET 'https://rest.messagebird.com/reporting/sms?periodStart=2019-01-01T00:00:00Z&periodEnd=2019-01-30T00:00:00Z&periodGroup=month&groupBy=country&groupBy=networkCode' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Example Response

{
    "items": [
       {
          "timestamp": "2019-01-01T00:00:00Z",
          "message": {
             "mcc": 204,
             "countryName": "Netherlands",
             "networkCode": 20402
          },
          "submittedCount": 2,
          "deliveredCount": 2,
          "processingCount": 0,
          "failedCount": 0,
          "deliveryImpossibleCount": 0
       },
       {
          "timestamp": "2019-01-01T00:00:00Z",
          "message": {
             "mcc": 204,
             "countryName": "Netherlands",
             "networkCode": 20416
          },
          "submittedCount": 1,
          "deliveredCount": 1,
          "processingCount": 0,
          "failedCount": 0,
          "deliveryImpossibleCount": 0
       }
    ],
    "ref": "59d4a651fada4873b6a8b173b0a4a180",
    "totalCount": 2
 }

The desired output format can be specified with the Accept header. Valid values are application/json (default) and text/csv.

SMS Report object

This object represents a statistic.

Attributes

Attribute	Type	Description
items	array	Messages are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestamp	datetime	The timestamp in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-04-09T00:00:00Z represents the 15th week in 2018 or the first hour of the day April 9, 2018 or the day itself.
items[].message	object	Contains details about the messages based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].submittedCount	integer	The number of messages submitted to MessageBird in the specified time period.
items[].deliveredCount	integer	The number of messages delivered in the specified time period.
items[].processingCount	integer	The number of messages being processed at MessageBird.
items[].failedCount	integer	The number of messages failed to deliver.
items[].deliveryImpossibleCount	integer	The number of messages that were impossible to deliver, for example an invalid recipient.
ref	string	A string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.
prev [deprecated]	string	A link to get the previous page. Omitted for the first page. Note you still need to set authorization.
next [deprecated]	string	A link to get the next page. Omitted for the last page. Note you still need to set authorization.
totalCount	integer	The total number of items that can be retrieved for this request through pagination.

The message object

Attribute	Type	Description
mcc	integer	Mobile Country Code, e.g. 204.
countryName	string	Full English name of the destination country.
networkCode	integer	MCC + MNC (Mobile Network Code), e.g. 20408.
originator	string	The originator, which can either be a phone number or an alphanumeric sender. It is possible that the originator is unavailable, for example because the owner of the phone number has made a request to remove it from logs. In this case, a secure hash string prefixed with “UNKNOWN” will be returned instead, which is consistent among different requests. Note originators of all messages sent before March 9, 2018 will be “UNKNOWN”.
account	string	Account name. Exists only when group by account.

CSV format response fields

Attribute	Type	Description
timestamp	datetime	The date and time in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-04-09T00:00:00Z represents the 15th week in 2018 or the first hour of the day April 9, 2018 or the day itself. Exists only when periodGroup is not none.
mcc	integer	Mobile country code. Exists only when group by country.
countryName	string	Full English name of the destination country. Exists only when group by country. For some virtual numbers, we don’t have that data and the countryName will show as Unknown.
networkCode	integer	MCC + MNC (mobile network code). Exists only when group by networkCode.
originator	string	The originator. Exists only when group by originator.
account	string	Account name. Exists only when group by account.
submittedCount	integer	The number of messages submitted to MessageBird in the specified time period.
deliveredCount	integer	The number of messages delivered among the submitted.
processingCount	integer	The number of messages being processed at MessageBird.
failedCount	integer	The number of messages failed to deliver.
deliveryImpossibleCount	integer	The number of messages that were impossible to deliver, for example an invalid recipient.

SMS Example requests

You can retrieve a variety of insights from the Reporting API through different combinations of filterBy and groupBy parameters. We have collected a variety of requests below to serve as an inspiration for you to build your own queries.

Successful messages grouped by country

Imagine you’re running a global SMS-based marketing campaign and want to know how many people you have reached in the last month in each country. You can group by country. And, because you just need total numbers, a monthly granularity is enough.

Successful messages grouped by country

curl -X GET 'https://rest.messagebird.com/reporting/sms?periodStart=2018-04-01T00:00:00Z&periodEnd=2018-04-30T00:00:00Z&periodGroup=month&groupBy=country' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Messages from an originator

It’s important to know how many text messages are actually received and how many get stuck in the network to understand whether your SMS-based campaigns are successful. Also, let’s say you’re running multiple campaigns on the same account but each uses a different originator. You’re only interested in two of them, so you can use them both as filter criteria and group by originator as well.

Messages from an originator

curl --globoff -X GET 'https://rest.messagebird.com/reporting/sms?periodStart=2018-04-01T00:00:00Z&periodEnd=2018-04-30T00:00:00Z&periodGroup=month&filterBy[originator]=OmNomNom&filterBy[originator]=BeautyBird&groupBy=originator' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Messages for a country and originator grouped by network

Imagine you’re getting customer complaints about not receiving messages. Anecdotally the customers with these complaints seem to have the same provider, so you want to dive into this and investigate messages by the network code of the receiver. To keep the data manageable you add a filter for your originator and one country at which you want to look. Also you choose daily granularity, so you can also analyze whether those problems occur differently over time.

Messages for a country and originator grouped by network

curl --globoff -X GET 'https://rest.messagebird.com/reporting/sms?periodStart=2018-04-01T00:00:00Z&periodEnd=2018-04-30T00:00:00Z&periodGroup=day&filterBy[countryCode]=DE&groupBy=networkCode' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Iterate over all items

Requesting the first part gives us the first 100 items and ref: b5ba8e88b10011e896f8529269fb1459. In order to get the second part, run the second request.

Iterate over all items

curl -X GET 'https://rest.messagebird.com/reporting/sms?periodStart=2018-04-01T00:00:00Z&periodEnd=2018-09-30T00:00:00Z&periodGroup=day&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

curl -X GET 'https://rest.messagebird.com/reporting/sms?periodStart=2018-04-01T00:00:00Z&periodEnd=2018-09-30T00:00:00Z&periodGroup=day&offset=100&limit=100&ref=b5ba8e88b10011e896f8529269fb1459' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Call

Required parameters

Attribute	Type	Description
periodStart	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the start of the reporting period.
periodEnd	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

Attribute	Type	Description
periodGroup	string	The time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezone	string	The timezone to group and display the results in the time-dimension, such as “Europe/Amsterdam” or “US/Central”. All location names in the Time Zone Database are valid. Default: UTC.
groupBy	string list	Zero or more values from status, source, sourceCountry, sourceOperatorPrefix, sourceType, destination, destinationCountry, destinationOperatorPrefix, destinationType. More than one value can be specified by repeating the query parameter groupBy. For example, groupBy=status&groupBy=sourceCountry groups items by status AND source country. Default: empty.
filterBy[]		You can specify multiple filters as explained below. Specifying the same type of filter multiple times with different values is considered a union query, which means that the reports contains all calls that match one of the conditions. Specifying multiple different filters results in an intersection query, for example filterBy[sourceCountryPrefix]=44&filterBy[status]=ended only returns calls sent to the United Kingdom that were successful. Default: empty.
filterBy[source]	string	A source that has been used for creating a call, which can either be a phone number or an alphanumeric caller. Default: empty.
filterBy[sourceCountryCode]	string	An ISO 639 country code, for example DE for Germany. More than one code can be provided by repeating the query parameter, such as filterBy[sourceCountryCode]=NL&filterBy[sourceCountryCode]=UK. Default: empty.
filterBy[sourceCountryPrefix]	integer	A country phone number prefix, for example 1 for USA and Canada. More than one prefix can be provided by repeating the query parameter. This will be translated to filterBy[sourceCountryCode]. For example filterBy[sourceCountryPrefix]=1 will be translated to filterBy[sourceCountryCode]=CA&filterBy[sourceCountryCode]=US. Default: empty.
filterBy[sourceOperatorPrefix]	integer	An operator prefix, for example 86135 for a number belongs to China Mobile. More than one prefix can be provided by repeating the query parameter, such as filterBy[sourceOperatorPrefix]=86135&filterBy[sourceOperatorPrefix]=86139. Default: empty.
filterBy[sourceType]	string	Type of source number. Valid values are landline, mobile, paging, mobile_paging, mobile_landline, satellite, supplementary_services, case insensitive. For example filterBy[sourceType]=landline. Default: empty.
filterBy[destination]	string	A destination that has been used for receiving a call, for example a phone number. Default: empty.
filterBy[destinationCountryCode]	string	An ISO 639 country code, for example DE for Germany. More than one code can be provided by repeating the query parameter. Default: empty.
filterBy[destinationCountryPrefix]	integer	A country phone number prefix, for example 91 for India. More than one prefix can be provided by repeating the query parameter. This will be translated to filterBy[destinationCountryCode]. Default: empty.
filterBy[destinationOperatorPrefix]	integer	An operator prefix, for example 86135 for a number belongs to China Mobile. More than one prefix can be provided by repeating the query parameter. Default: empty.
filterBy[destinationType]	string	Type of destination number. Valid values are landline, mobile, paging, mobile_paging, mobile_landline, satellite, supplementary_services, case insensitive. For example filterBy[destinationType]=landline. Default: empty.
filterBy[status]	string	A call status. See the Call Status table for possible values. More than one status can be provided by repeating the query parameter. Default: empty.
sort	string	Specify sort criteria with the following syntax: key1:direction1[,key2:direction2]. If a direction is omitted, asc (ascending) is assumed. Valid keys are count, successCount, failureCount, totalDuration, averageDuration, successRate, failureRate. Valid directions are asc, desc. The appearance order of more than one key will be preserved when sorting a result. Further, the sorted result will be sorted by time in ascending order. For example, sort=count:desc will sort results by count in descending order. And the items having the same sorting key values will be sorted in time ascending order if periodGroup is not none. Default: empty.
offset	integer	The number of elements to skip. Default: 0, skipping zero element.
limit	integer	The number of elements to return. Valid values are any integer number between 1 and 2500, both inclusive. A number larger than 2500 will be clipped to 2500. Default: 500.
ref	string	A string to ensure consistency of pagination. When accessing the first part of result, it will be included in the response. To access further parts it needs to be added as a request query parameter.

The desired output format can be specified with the Accept header. Valid values are application/json (default) and text/csv.

Available HTTP Methods

GET /call

Example Request

curl -X GET 'https://rest.messagebird.com/reporting/call?periodStart=2019-01-01T00:00:00Z&periodEnd=2019-01-30T00:00:00Z&periodGroup=month&groupBy=status&groupBy=sourceCountry&groupBy=sourceType' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Example Response

{
  "items": [
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "call": {
        "source": {
          "countryCode": "US",
          "type": "country_code"
        },
        "status": "ended"
      },
      "totalDuration": 24,
      "averageDuration": 8,
      "count": 3,
      "successCount": 3,
      "failureCount": 0,
      "successRate": 1,
      "failureRate": 0
    },
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "call": {
        "source": {
          "countryCode": "ES",
          "type": "landline"
        },
        "status": "ended"
      },
      "totalDuration": 17,
      "averageDuration": 8.5,
      "count": 2,
      "successCount": 2,
      "failureCount": 0,
      "successRate": 1,
      "failureRate": 0
    },
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "call": {
        "source": {
          "countryCode": "ES",
          "type": "mobile"
        },
        "status": "ended"
      },
      "totalDuration": 50,
      "averageDuration": 8.333333,
      "count": 6,
      "successCount": 6,
      "failureCount": 0,
      "successRate": 1,
      "failureRate": 0
    },
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "call": {
        "source": {
          "countryCode": "NL",
          "type": "mobile"
        },
        "status": "ended"
      },
      "totalDuration": 61,
      "averageDuration": 15.25,
      "count": 4,
      "successCount": 4,
      "failureCount": 0,
      "successRate": 1,
      "failureRate": 0
    }
  ],
  "ref": "821fa2bfb6114381b79748ceb53b0721",
  "totalCount": 4
}}

The Call Status table

Status	Description
starting	A call is being established.
ongoing	A call is happening now.
ended	A call has been finished successfully.
failed	An error has occurred when establishing a call.
busy	A call could not be established as the endpoint was busy.
no_answer	A call was not picked up.
queued	A call is awaiting to be initiated.

Call Report object

This object represents a statistic.

Attributes

Attribute	Type	Description
items	array	Calls are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestamp	datetime	The timestamp in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-08-06T00:00:00Z represents the 32th week in 2018 or the first hour of the day August 6, 2018 or the day itself.
items[].call	object	Contains details about the calls based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].totalDuration	integer	The total duration (seconds) of calls in a group.
items[].averageDuration	float	The average duration (seconds) of calls in a group.
items[].count	integer	The total number of calls in a group.
items[].successCount	integer	The number of successful calls in a group.
items[].failureCount	integer	The number of failed calls in a group.
items[].successRate	float	The average rate of successful calls in a group.
items[].failureRate	float	The average rate of failed calls in a group.
ref	string	A string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.
totalCount	integer	The total number of items that can be retrieved for this request through pagination.

The call object

A call describes a voice call made to a number.

Attribute	Type	Description
source	Endpoint object	Source of a call.
destination	Endpoint object	Destination of a call.
status	string	The status of calls in a group. See the Call Status table.

The Endpoint object

An endpoint is an object stores information about a number.

Attribute	Type	Description
number	string	Number of the endpoint, such as 31648888888 and MessageBird.
countryCode	string	Country code of the endpoint. Exists only when group by country and number is a valid phone number.
countryPrefix	integer	Country prefix of the endpoint. Exists only when group by country and number is a valid phone number..
operatorPrefix	integer	Operator prefix of the endpoint. Exists only when group by operator prefix and number is a valid phone number..
type	string	Type of the endpoint. Exists only when group by type.

CSV format response fields

Attribute	Type	Description
timestamp	datetime	The date and time in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-04-09T00:00:00Z represents the 15th week in 2018 or the first hour of the day April 9, 2018 or the day itself. Exists only when periodGroup is not none.
source	string	Source number of a call. Exists only when group by source.
sourceCountryCode	string	Country code of the source of a call. Exists only when group by source country.
sourceCountryPrefix	integer	Country prefix of the source of a call. Exists only when group by source country.
sourceOperatorPrefix	integer	Operator prefix of the source of a call. Exists only when group by operator prefix.
sourceType	string	Type of the source of a call. Exists only when group by source type.
destination	string	Destination number of a call. Exists only when group by destination. Exists only when group by destination.
destinationCountryCode	string	Country code of the destination of a call. Exists only when group by destination country.
destinationCountryPrefix	integer	Country prefix of the destination of a call. Exists only when group by destination country.
destinationOperatorPrefix	integer	Operator prefix of the destination of a call. Exists only when group by destination operator prefix.
destinationType	string	Type of the destination of a call. Exists only when group by destination type.
status	string	The status of calls in a group. See the Call Status table. Exists only when group by status.
totalDuration	integer	The total duration (seconds) of calls in a group.
averageDuration	float	The average duration (seconds) of calls in a group.
count	integer	The total number of calls in a group.
successCount	integer	The number of successful calls in a group.
failureCount	integer	The number of failed calls in a group.
successRate	float	The average rate of successful calls in a group.
failureRate	float	The average rate of failed calls in a group.

Call Example requests

Monthly calls grouped by country

Group all calls made in August, 2018 UTC+8 by source country to see calls originated from every country in August.

Monthly calls grouped by country

curl -X GET 'https://rest.messagebird.com/reporting/call?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&periodGroup=none&groupBy=sourceCountry&timezone=Asia/Shanghai' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily calls grouped by country

Group all calls made in August, 2018 UTC+8 by source country and day to see daily calls originated from every country.

Daily calls grouped by country

curl -X GET 'https://rest.messagebird.com/reporting/call?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&groupBy=sourceCountry' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily calls originated from the Netherlands

Group all calls made in August, 2018 UTC+8 from the Netherlands by day to see daily calls originated from the Netherlands.

Daily calls originated from the Netherlands

curl --globoff -X GET 'https://rest.messagebird.com/reporting/call?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&filterBy[sourceCountryCode]=NL' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily calls originated from the Netherlands and Germany

Group all calls made in August, 2018 UTC+8 from the Netherlands and Germany by day to see daily calls originated from the two countries.

Daily calls originated from the Netherlands and Germany

curl --globoff -X GET 'https://rest.messagebird.com/reporting/call?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&filterBy[sourceCountryCode]=NL&filterBy[sourceCountryCode]=DE' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily failed calls originated from the Netherlands

Group all calls made in August, 2018 UTC+8 from the Netherlands by day to see daily calls originated from the Netherlands.

Daily failed calls originated from the Netherlands

curl --globoff -X GET 'https://rest.messagebird.com/reporting/call?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&filterBy[sourceCountryCode]=NL&filterBy[status]=failed' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily distribution of caller types originated from the Netherlands

Group all calls made in August, 2018 UTC+8 from the Netherlands by day and sourceType to see daily distribution of caller types originated from the Netherlands.

Daily distribution of caller types originated from the Netherlands

curl --globoff -X GET 'https://rest.messagebird.com/reporting/call?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&filterBy[sourceCountryCode]=NL&groupBy=sourceType' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Iterate over all items

Requesting the first part gives us the first 100 items and ref: 03aa7194b10111e88981529269fb1459. In order to get the second part, run the second request.

Daily distribution of caller types originated from the Netherlands

curl -X GET 'https://rest.messagebird.com/reporting/call?periodStart=2016-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

curl -X GET 'https://rest.messagebird.com/reporting/call?periodStart=2016-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&offset=100&limit=100&ref=03aa7194b10111e88981529269fb1459' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Leg

Required parameters

Attribute	Type	Description
periodStart	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the start of the reporting period.
periodEnd	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

Attribute	Type	Description
periodGroup	string	The time granularity to group the statistics. Valid values are none, hour, day, week, month and year, case insensitive. Default: day.
timezone	string	The timezone to group and display the results in the time-dimension, such as “Europe/Amsterdam” or “US/Central”. All location names in the Time Zone Database are valid. Default: UTC.
groupBy	string list	Zero or more values from status, source, sourceCountry, sourceOperatorPrefix, sourceType, destination, destinationCountry, destinationOperatorPrefix, destinationType, direction, protocol. More than one value can be specified by repeating the query parameter groupBy. For example, groupBy=status&groupBy=sourceCountry groups items by status AND source country. Default: empty.
filterBy[]		You can specify multiple filters as explained below. Specifying the same type of filter multiple times with different values is considered a union query, which means that the reports contains all legs that match one of the conditions. Specifying multiple different filters results in an intersection query, for example filterBy[sourceCountryPrefix]=44&filterBy[status]=ended only returns legs sent to the United Kingdom that were successful. Default: empty.
filterBy[source]	string	A source that has been used for creating a leg, which can either be a phone number or an alphanumeric string. Default: empty.
filterBy[sourceCountryCode]	string	An ISO 639 country code, for example DE for Germany. More than one code can be provided by repeating the query parameter, such as filterBy[sourceCountryCode]=NL&filterBy[sourceCountryCode]=UK. Default: empty.
filterBy[sourceCountryPrefix]	integer	A country phone number prefix, for example 91 for India. More than one prefix can be provided by repeating the query parameter. This will be translated to filterBy[sourceCountryCode]. For example filterBy[sourceCountryPrefix]=31&filterBy[sourceCountryPrefix]=91 will be translated to filterBy[sourceCountryCode]=NL&filterBy[sourceCountryPrefix]=IN. Default: empty.
filterBy[sourceOperatorPrefix]	integer	An operator prefix, for example 86135 for a number belongs to China Mobile. More than one prefix can be provided by repeating the query parameter, such as filterBy[sourceOperatorPrefix]=86135&filterBy[sourceOperatorPrefix]=86139. Default: empty.
filterBy[sourceType]	string	Type of source number. Valid values are landline, mobile, paging, mobile_paging, mobile_landline, satellite, supplementary_services, case insensitive. For example filterBy[sourceType]=landline. Default: empty.
filterBy[destination]	string	A destination that has been used for receiving a leg, which can either be a phone number or an alphanumeric receiver. Default: empty.
filterBy[destinationCountryCode]	string	An ISO 639 country code, for example DE for Germany. More than one code can be provided by repeating the query parameter. Default: empty.
filterBy[destinationCountryPrefix]	integer	A country phone number prefix, for example 91 for India. More than one prefix can be provided by repeating the query parameter. This will be translated to filterBy[destinationCountryCode]. Default: empty.
filterBy[destinationOperatorPrefix]	integer	An operator prefix, for example 86135 for a number belongs to China Mobile. More than one prefix can be provided by repeating the query parameter. Default: empty.
filterBy[destinationType]	string	Type of destination number. Valid values are landline, mobile, paging, mobile_paging, mobile_landline, satellite, supplementary_services, case insensitive. For example filterBy[destinationType]=landline. Default: empty.
filterBy[direction]	string	Direction of a leg, either incoming or outgoing, case insensitive. For example filterBy[direction]=incoming. Default: empty.
filterBy[protocol]	string	A leg protocol. Valid values are did, sip, webrtc, case insensitive. More than one type of protocol can be provided by repeating the query parameter. Default: empty.
filterBy[status]	string	A leg status. See the Leg Status table for possible values. More than one status can be provided by repeating the query parameter. Default: empty.
sort	string	Specify sort criteria with the following syntax: key1:direction1[,key2:direction2]. If a direction is omitted, asc (ascending) is assumed. Valid keys are count, successCount, failureCount, totalDuration, averageDuration, successRate, failureRate. Valid directions are asc, desc. The appearance order of more than one key will be preserved when sorting a result. Further, the sorted result will be sorted by time in ascending order. For example, sort=count:desc will sort results by count in descending order. And the items having the same sorting key values will be sorted in time ascending order if periodGroup is not none. Default: empty.
offset	integer	The number of elements to skip. Default: 0, skipping zero element.
limit	integer	The number of elements to return. Valid values are any integer number between 1 and 2500, both inclusive. A number larger than 2500 will be clipped to 2500. Default: 500.
ref	string	A string to ensure consistency of pagination. When accessing the first part of result, it will be included in the response. To access further parts it needs to be added as a request query parameter.

The desired output format can be specified with the Accept header. Valid values are application/json (default) and text/csv.

Available HTTP Methods

GET /leg

Example Request

curl -X GET 'https://rest.messagebird.com/reporting/leg?periodStart=2019-01-01T00:00:00Z&periodEnd=2019-01-30T00:00:00Z&periodGroup=month&groupBy=status&groupBy=sourceCountry&groupBy=sourceType' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Example Response

{
  "items": [
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "leg": {
        "source": {
          "countryCode": "US",
          "type": "country_code"
        },
        "status": "HANGUP"
      },
      "totalDuration": 27,
      "averageDuration": 9,
      "count": 3,
      "successCount": 3,
      "failureCount": 0,
      "successRate": 1,
      "failureRate": 0
    },
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "leg": {
        "source": {
          "countryCode": "ES",
          "type": "mobile"
        },
        "status": "HANGUP"
      },
      "totalDuration": 56,
      "averageDuration": 9.333333,
      "count": 6,
      "successCount": 6,
      "failureCount": 0,
      "successRate": 1,
      "failureRate": 0
    },
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "leg": {
        "source": {
          "countryCode": "ES",
          "type": "landline"
        },
        "status": "HANGUP"
      },
      "totalDuration": 19,
      "averageDuration": 9.5,
      "count": 2,
      "successCount": 2,
      "failureCount": 0,
      "successRate": 1,
      "failureRate": 0
    },
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "leg": {
        "source": {
          "countryCode": "NL",
          "type": "mobile"
        },
        "status": "HANGUP"
      },
      "totalDuration": 65,
      "averageDuration": 13,
      "count": 5,
      "successCount": 5,
      "failureCount": 0,
      "successRate": 1,
      "failureRate": 0
    }
  ],
  "ref": "c4f78607865e407eb9abf9856cc93e6e",
  "totalCount": 4
}

The Leg Status table

Status	Description
starting	A leg is being established.
ringing	A leg is awaiting to be picked up.
ongoing	A leg is happening now.
hangup	A leg has been finished successfully.
busy	A leg could not be established as the endpoint was busy.
no_answer	A leg was not picked up.
failed	An error has occurred when establishing a leg.

Leg Report object

This object represents a statistic.

Attributes

Attribute	Type	Description
items	array	Legs are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestamp	datetime	The timestamp in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-08-06T00:00:00Z represents the 32th week in 2018 or the first hour of the day August 6, 2018 or the day itself.
items[].leg	object	Contains details about the legs based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].totalDuration	integer	The total duration (seconds) of legs in a group.
items[].averageDuration	float	The average duration (seconds) of legs in a group.
items[].count	integer	The total number of legs in a group.
items[].successCount	integer	The number of successful legs in a group.
items[].failureCount	integer	The number of failed legs in a group.
items[].successRate	float	The average rate of successful legs in a group.
items[].failureRate	float	The average rate of failed legs in a group.
ref	string	A string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.
totalCount	integer	The total number of items that can be retrieved for this request through pagination.

The leg Object

A call has legs which are incoming or outgoing voice connections. An incoming leg is created when somebody calls a number. Outgoing legs are created when a call is transferred.

Attribute	Type	Description
source	Endpoint object	Source of a leg.
destination	Endpoint object	Destination of a leg.
direction	string	Direction of a leg, either incoming or outgoing.
protocol	string	A leg protocol. Possible values are did, sip, webrtc.
status	string	The status of legs in a group. See the Leg Status table.

The Endpoint object

An endpoint is an object stores information about a number.

Attribute	Type	Description
number	string	Number of the endpoint, for example 31648888888.
countryCode	string	Country code of the endpoint. Exists only when group by country.
operatorPrefix	integer	Operator prefix of the endpoint. Exists only when group by operator prefix.
type	string	Type of the endpoint. Exists only when group by type.

CSV format response fields

Attribute	Type	Description
timestamp	datetime	The date and time in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-04-09T00:00:00Z represents the 15th week in 2018 or the first hour of the day April 9, 2018 or the day itself. Exists only when periodGroup is not none.
source	string	Source number of a leg. Exists only when group by source.
sourceCountryCode	string	Country code of the source of a leg. Exists only when group by source country.
sourceOperatorPrefix	integer	Operator prefix of the source of a leg. Exists only when group by operator prefix.
sourceType	string	Type of the source of a leg. Exists only when group by source type.
destination	string	Destination number of a leg. Exists only when group by destination. Exists only when group by destination.
destinationCountryCode	string	Country code of the destination of a leg. Exists only when group by destination country.
destinationOperatorPrefix	integer	Operator prefix of the destination of a leg. Exists only when group by destination operator prefix.
destinationType	string	Type of the destination of a leg. Exists only when group by destination type.
direction	string	Direction of a leg, either incoming or outgoing. Exists only when group by direction.
protocol	string	A leg protocol. Possible values are did, sip, webrtc.
status	string	The status of legs in a group. See the Leg Status table. Exists only when group by status.
totalDuration	integer	The total duration (seconds) of legs in a group.
averageDuration	float	The average duration (seconds) of legs in a group.
count	integer	The total number of legs in a group.
successCount	integer	The number of successful legs in a group.
failureCount	integer	The number of failed legs in a group.
successRate	float	The average rate of successful legs in a group.
failureRate	float	The average rate of failed legs in a group.

Leg Example requests

Monthly legs grouped by country

Group all legs made in August, 2018 UTC+8 by source country to see legs originated from every country in August.

Monthly legs grouped by country

curl -X GET 'https://rest.messagebird.com/reporting/leg?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&periodGroup=none&groupBy=sourceCountry&timezone=Asia/Shanghai' -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' -H 'Accept: application/json'

Daily legs grouped by country

Group all legs made in August, 2018 UTC+8 by source country and day to see daily legs originated from every country.

Daily legs grouped by country

curl -X GET 'https://rest.messagebird.com/reporting/leg?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&groupBy=sourceCountry' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily legs originated from the Netherlands

Group all legs made in August, 2018 UTC+8 from the Netherlands by day to see daily legs originated from the Netherlands.

Daily legs originated from the Netherlands

curl --globoff -X GET 'https://rest.messagebird.com/reporting/leg?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&filterBy[sourceCountryCode]=NL' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily legs originated from the Netherlands and Germany

Group all legs made in August, 2018 UTC+8 from the Netherlands and Germany by day to see daily legs originated from the two countries.

Daily legs originated from the Netherlands and Germany

curl --globoff -X GET 'https://rest.messagebird.com/reporting/leg?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&filterBy[sourceCountryCode]=NL&filterBy[sourceCountryCode]=DE' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily failed legs originated from the Netherlands

Group all legs made in August, 2018 UTC+8 from the Netherlands by day to see daily legs originated from the Netherlands.

Daily failed legs originated from the Netherlands

curl --globoff -X GET 'https://rest.messagebird.com/reporting/leg?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&filterBy[sourceCountryCode]=NL&filterBy[status]=failed' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily distribution of leg types originated from the Netherlands

Group all legs made in August, 2018 UTC+8 from the Netherlands by day and sourceType to see daily distribution of leg types originated from the Netherlands.

Daily distribution of leg types originated from the Netherlands

curl --globoff -X GET 'https://rest.messagebird.com/reporting/leg?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&filterBy[sourceCountryCode]=NL&groupBy=sourceType' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Iterate over all items

Requesting the first part gives us the first 100 items and ref: 1d192ee0b10111e896f8529269fb1459. In order to get the second part, run the second request.

Iterate over all items

curl -X GET 'https://rest.messagebird.com/reporting/leg?periodStart=2016-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

curl -X GET 'https://rest.messagebird.com/reporting/leg?periodStart=2016-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&offset=100&limit=100&ref=1d192ee0b10111e896f8529269fb1459' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Conversations Message

Required parameters

Attribute	Type	Description
periodStart	Timestamp	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the start of the reporting period.
periodEnd	Timestamp	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

Attribute	Type	Description
periodGroup	string	The time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezone	string	The timezone to group and display the results in the time-dimension, such as “Europe/Amsterdam” or “US/Central”. All location names in the IANA Time Zone Database are valid. Default: UTC.
groupBys	string	Zero or more values from channel, platform, direction, status, type. More than one value can be specified by repeating the query parameter. For example, groupBy=status&groupBy=platform groups items by status AND direction. Default: empty.
filterBy	PublicFilter	You can specify multiple filters as explained in Filter table. Specifying the same type of filter multiple times with different values is considered a union query, which means that the reports contains all messages that match one of the conditions. Specifying multiple different filters results in an intersection query, for example filterBy[type]=text&filterBy[status]=delivered only returns messages only delivered messages of type text. Default: empty.
sort	string	Specify sort criteria with the following syntax: key1:direction1[,key2:direction2]. If a direction is omitted, asc (ascending) is assumed. Valid keys are count. Valid directions are asc, desc. The appearance order of more than one key will be preserved when sorting a result. Further, the sorted result will be sorted by time in ascending order. For example, sort=count:desc will sort results by count in descending order. And the items having the same count will be sorted in time ascending order.
offset	uint32	The number of elements to skip. Default: 0, skipping zero element.
limit	uint32	The number of elements to return. Valid values are any integer number between 1 and 2500, both inclusive. A number larger than 2500 will be clipped to 2500. Default: 500.
ref	string	A string to ensure consistency of pagination. When accessing the first part of result, it will be included in the response. To access further parts it needs to be added as a request query parameter.

PublicFilter

Attribute	Type	Description
direction	string	Direction of a message, either sent or received, case insensitive. For example filterBy[direction]=sent. Default: empty.
status	string	Status of a message, valid values are deleted, delivered, failed, pending, read, received, rejected, sent, unsupported, case insensitive. More than one type of protocol can be provided by repeating the query parameter, for example: filterBy[status]=sent&filterBy[status]=delivered Default: empty.
type	string	Type of a message, valid values are text, image, audio, video, location, file, hsm (only for WhatsApp), unknown, case insensitive. More than one type of protocol can be provided by repeating the query parameter. Default: empty.
channel_id	string	Id of channel. More than one type of protocol can be provided by repeating the query parameter. Default: empty.
platform	string	Platform name. More than one type of protocol can be provided by repeating the query parameter. Default: empty.

The desired output format can be specified with the Accept header. Valid values are application/json (default) and text/csv.

Available HTTP Methods

GET /conversations/message

Example Request

curl -X GET 'https://rest.messagebird.com/reporting/conversations/message?periodStart=2019-01-01T00:00:00Z&periodEnd=2019-01-30T00:00:00Z&periodGroup=month&groupBy=status&groupBy=platform' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Example Response

{
  "items": [
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "message": {
        "platform": "whatsapp",
        "status": "deleted"
      },
      "count": 9
    },
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "message": {
        "platform": "whatsapp",
        "status": "delivered"
      },
      "count": 12
    }
  ],
  "ref": "985de941e2a641699aac9556fce68b78",
  "total_count": 2
}

Conversations Message report object

This object represents a statistic.

Response object

Attribute	Type	Description
items	MessageResponseItem	Messages are split by provided grouping fields. Each item corresponds to statistics of a group.
ref	string	A string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.
total_count	uint64	The total number of items that can be retrieved for this request through pagination.

MessageResponseItem object

Attribute	Type	Description
timestamp	string	The timestamp in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-04-09T00:00:00Z represents the 15th week in 2018 or the first hour of the day April 9, 2018 or the day itself.
message	MessageItem	Contains details about the messages based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
count	uint64	The total number of messages in a group.

MessageItem object

Attribute	Type	Description
direction	string	Direction of a message, either sent or received.
platform	string	Message platform name.
status	string	Status of a message, valid values are deleted, delivered, failed, pending, read, received, rejected, sent, unsupported, opened, clicked, accepted, bounce, spam_compliant, out_of_bound, delayed.
type	string	Type of a message, valid values are text, image, audio, video, location, file, hsm (only for WhatsApp), unknown.
channel	string	Message channel id.

Email Statuses

The following email statuses could be received from the Conversations API.

Status Type	Description
pending	Message is sent to an email provider.
accepted	Message is accepted by the email provider.
sent	Remote mail transfer agent acknowledged a message.
opened	Recipient has opened the email. It only works for html content.
clicked	Recipient clicked a tracked link in the email. It only works for html content with href defined links.
bounce	Remote mail transfer agent has rejected the email.
spam_complaint	Message is classified as spam by the recipient.
out_of_bounded	Message is not delivered to recipient.
delayed	Remote mail transfer agent is rejected the email temporarily.
received	Message is received from sender.

CSV format response fields

Attribute	Type	Description
count	integer	The total number of messages in a group.
timestamp	datetime	The date and time in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-04-09T00:00:00Z represents the 15th week in 2018 or the first hour of the day April 9, 2018 or the day itself. Exists only when periodGroup is not none.
direction	string	Direction of a message, either sent or received.
status	string	Status of a message, valid values are deleted, delivered, failed, pending, read, received, rejected, sent, unsupported.
type	string	Type of a message, valid values are text, image, audio, video, location, file, hsm (only for WhatsApp), unknown.
platform	string	Message platform name.
channel	string	Message channel id.

Conversations Message Example requests

Monthly messages grouped by status

Group all messages made in August, 2018 UTC+8 by status.

Monthly messages grouped by status

curl -X GET 'https://rest.messagebird.com/reporting/conversations/message?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&periodGroup=none&groupBy=status&timezone=Asia/Shanghai' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Flow

Required parameters

Attribute	Type	Description
periodStart	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the start of the reporting period.
periodEnd	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the end of the reporting period. This must be after periodStart.

Available HTTP Methods

GET /flow

Optional parameters

Attribute	Type	Description
periodGroup	string	The time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezone	string	The timezone to group and display the results in the time-dimension, such as “Europe/Amsterdam” or “US/Central”. All location names in the IANA Time Zone Database are valid. Default: UTC.
groupBy	string list	Zero or more values from trigger. More than one value can be specified by repeating the query parameter. For example, groupBy=trigger&groupBy=XXXXX groups items by triggerType AND XXXXX. Default: empty.
filterBy[]		You can specify multiple filters as explained below. Specifying the same type of filter multiple times with different values is considered a union query, which means that the reports contains all invocations that match one of the conditions. Specifying multiple different filters results in an intersection query, for example filterBy[triggerType]=received_sms&filterBy[id]=123e4567e89b12d3a456426655440000 only returns invocation which failed and have a flowId of 123e4567e89b12d3a456426655440000. Default: empty.
filterBy[id]	string	The UUID of the flow. It remains unchanged during its lifecycle. Default: empty.
filterBy[trigger]	string	An action that caused a invocation to be triggered. Default: empty.
sort	string	Specify sort criteria with the following syntax: key1:direction1[,key2:direction2]. If a direction is omitted, asc (ascending) is assumed. Valid keys are count. Valid directions are asc, desc. The appearance order of more than one key will be preserved when sorting a result. Further, the sorted result will be sorted by time in ascending order. For example, sort=count:desc will sort results by count in descending order. And the items having the same sorting key values will be sorted in time ascending order if periodGroup is not none. Default: empty.
offset	integer	The number of elements to skip. Default: 0, skipping zero element.
limit	integer	The number of elements to return. Valid values are any integer number between 1 and 2500, both inclusive. A number larger than 2500 will be clipped to 2500. Default: 500.
ref	string	A string to ensure consistency of pagination. When accessing the first part of result, it will be included in the response. To access further parts it needs to be added as a request query parameter.

The desired output format can be specified with the Accept header. Valid values are application/json (default) and text/csv.

The trigger table

Trigger	Description
on_received_sms	A flow triggered by an sms.
on_incoming_voice_call	A flow triggered by an phonecall.
on_received_http_request	A flow triggered by an webhook.
on_received_conversation_message	A flow triggered by an omnichannel conversation message.

The flow Object

A flow describes the set of steps that will be executed when a flow is invoked.

Attribute	Type	Description
trigger	string	The thing/event that will lead to a flow being invoked. Exist only when group by trigger.

Flow Report object

This object represents a statistic.

Attributes

Attribute	Type	Description
items	array	Flows are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestamp	datetime	The timestamp in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-08-06T00:00:00Z represents the 32th week in 2018 or the first hour of the day August 6, 2018 or the day itself.
items[].flow	object	Contains details about the flows based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].count	integer	The number of items in a group.
totalCount	integer	The total number of items that can be retrieved for this request through pagination.
ref	string	A string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.

CSV format response fields

Attribute	Type	Description
timestamp	datetime	The date and time in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-04-09T00:00:00Z represents the 15th week in 2018 or the first hour of the day April 9, 2018 or the day itself. Exists only when periodGroup is not none.
trigger	string	An action that caused an invocation to be triggered. Exist only when group by triggerType
count	integer	The total number of items in a group.

Flow Example requests

Invocations grouped by trigger type

Group all flows made in August, 2018 UTC+8 by trigger type to see one month flows for the trigger types.

Invocations grouped by trigger type

curl -X GET 'https://rest.messagebird.com/reporting/flow?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&periodGroup=none&groupBy=trigger&timezone=Asia/Shanghai' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily invocations grouped by trigger type

Group all flows made in August, 2018 UTC+8 by trigger type and day to see daily flows for the trigger types.

Daily invocations grouped by trigger type

curl -X GET 'https://rest.messagebird.com/reporting/flow?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&groupBy=trigger' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Iterate over all items

Requesting the first part gives us the first 100 items and ref: 03aa7194b10111e88981529269fb1459. In order to get the second part, run the second request.

Daily invocations grouped by trigger type

curl -X GET 'https://rest.messagebird.com/reporting/flow?periodStart=2016-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

curl -X GET 'https://rest.messagebird.com/reporting/flow?periodStart=2016-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&offset=100&limit=100&ref=03aa7194b10111e88981529269fb1459' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Invocation

Required parameters

Attribute	Type	Description
periodStart	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the start of the reporting period.
periodEnd	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

Attribute	Type	Description
periodGroup	string	The time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezone	string	The timezone to group and display the results in the time-dimension, such as “Europe/Amsterdam” or “US/Central”. All location names in the IANA Time Zone Database are valid. Default: UTC.
groupBy	string list	Zero or more values from status, flowId, flowTrigger, source, target. More than one value can be specified by repeating the query parameter. For example, groupBy=status&groupBy=flowId groups items by status AND flowId. Default: empty.
filterBy[]		You can specify multiple filters as explained below. Specifying the same type of filter multiple times with different values is considered a union query, which means that the reports contains all invocations that match one of the conditions. Specifying multiple different filters results in an intersection query, for example filterBy[status]=failed&filterBy[flowId]=123e4567e89b12d3a456426655440000 only returns invocation which failed and have a flowId of 123e4567e89b12d3a456426655440000. Default: empty.
filterBy[flowId]	string	The UUID of the flow. It remains unchanged during its lifecycle. Default: empty.
filterBy[status]	string	Status of an invocation. Valid values are in_progress, finished and failed, case insensitive. Default: empty.
filterBy[flowTrigger]	string	An action that caused a invocation to be triggered. Default: empty.
filterBy[source]	string	The source of the invocation, e.g. the originator (phone number) of a received SMS, or some other identifier related to the trigger. Default: empty.
filterBy[target]	string	The target of the invocation, e.g. the recipient (VMN) of a received SMS, or some other identifier related to the trigger. Default: empty.
sort	string	Specify sort criteria with the following syntax: key1:direction1[,key2:direction2]. If a direction is omitted, asc (ascending) is assumed. Valid keys are count, successCount, failureCount, successRate, failureRate. Valid directions are asc, desc. The appearance order of more than one key will be preserved when sorting a result. Further, the sorted result will be sorted by time in ascending order. For example, sort=count:desc will sort results by count in descending order. And the items having the same sorting key values will be sorted in time ascending order if periodGroup is not none. Default: empty.
offset	integer	The number of elements to skip. Default: 0, skipping zero element.
limit	integer	The number of elements to return. Valid values are any integer number between 1 and 2500, both inclusive. A number larger than 2500 will be clipped to 2500. Default: 500.
ref	string	A string to ensure consistency of pagination. When accessing the first part of result, it will be included in the response. To access further parts it needs to be added as a request query parameter.

The desired output format can be specified with the Accept header. Valid values are application/json (default) and text/csv.

Available HTTP Methods

GET /invocation

Example Request

curl -X GET 'https://rest.messagebird.com/reporting/invocation?periodStart=2019-01-01T00:00:00Z&periodEnd=2019-01-30T00:00:00Z&periodGroup=month&groupBy=status&groupBy=flowTrigger' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Example Response

{
  "items": [
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "invocation": {
        "status": "expired",
        "flowTrigger": "invalid"
      },
      "count": 1,
      "successCount": 0,
      "failureCount": 0,
      "successRate": 0,
      "failureRate": 0
    }
  ],
  "ref": "54730373ac1a4fdaba0814d82e10d16e",
  "totalCount": 1
}

The flowTrigger table

Trigger	Description
on_received_sms	A flow triggered by an sms.
on_incoming_voice_call	A flow triggered by an phone call.
on_received_http_request	A flow triggered by an webhook.
on_received_conversation_message	A flow triggered by an omnichannel conversation message.

The status table

Status	Description
in_progress	An invocation is in progress.
finished	An invocation has finished.
failed	An invocation has failed.
cancelled	An invocation has cancelled.
expired	An invocation has expired.

The invocation Object

An invocation describes a flow being invoked by a user.

Attribute	Type	Description
status	string	Status of an invocation. Exist only when group by status.
flowId	string	Id of the flow the invocation refers. Exist only when group by flowId.
flowTrigger	string	An action that caused a invocation to be triggered. Exist only when group by flowTrigger.

Invocation Report object

This object represents a statistic.

Attributes

Attribute	Type	Description
items	array	Invocations are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestamp	datetime	The timestamp in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-08-06T00:00:00Z represents the 32th week in 2018 or the first hour of the day August 6, 2018 or the day itself.
items[].invocation	object	Contains details about the invocations based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].successCount	integer	The number of successful invocations in a group.
items[].failureCount	integer	The number of failed invocations in a group.
items[].successRate	float	The average rate of successful invocations in a group.
items[].failureRate	float	The average rate of failed invocations in a group.
items[].count	integer	The number of items in a group.
totalCount	integer	The total number of items that can be retrieved for this request through pagination.
ref	string	A string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.

CSV format response fields

Attribute	Type	Description
timestamp	datetime	The date and time in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-04-09T00:00:00Z represents the 15th week in 2018 or the first hour of the day April 9, 2018 or the day itself. Exists only when periodGroup is not none.
status	string	Status of an invocation. Exist only when group by status
flowId	string	The UUID of the flow. It remains unchanged during its lifecycle. Exist only when group by flowId
flowTrigger	string	An action that caused a invocation to be triggered. Exist only when group by flowTrigger
count	integer	The total number of items in a group.
successCount	integer	The number of successful invocations in a group.
failureCount	integer	The number of failed invocations in a group.
successRate	float	The average rate of successful invocations in a group.
failureRate	float	The average rate of failed invocations in a group.

Invocation Example requests

Invocations grouped by trigger type

Group all invocations made in August, 2018 UTC+8 by flow trigger to see one month invocations for the trigger types.

Invocations grouped by trigger type

curl -X GET 'https://rest.messagebird.com/reporting/invocation?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&periodGroup=none&groupBy=flowTrigger&timezone=Asia/Shanghai' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily invocations grouped by trigger type

Group all invocations made in August, 2018 UTC+8 by flow trigger and day to see daily invocations for the trigger types.

Daily invocations grouped by trigger type

curl -X GET 'https://rest.messagebird.com/reporting/invocation?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&groupBy=flowTrigger' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Iterate over all items

Requesting the first part gives us the first 100 items and ref: 03aa7194b10111e88981529269fb1459. In order to get the second part, run the second request.

Iterate over all items

curl -X GET 'https://rest.messagebird.com/reporting/invocation?periodStart=2016-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

curl -X GET 'https://rest.messagebird.com/reporting/invocation?periodStart=2016-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&offset=100&limit=100&ref=03aa7194b10111e88981529269fb1459' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Step

Required parameters

Attribute	Type	Description
periodStart	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the start of the reporting period.
periodEnd	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

Attribute	Type	Description
periodGroup	string	The time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezone	string	The timezone to group and display the results in the time-dimension, such as “Europe/Amsterdam” or “US/Central”. All location names in the IANA Time Zone Database are valid. Default: UTC.
groupBy	string list	Zero or more values from status, flowId, action. More than one value can be specified by repeating the query parameter. For example, groupBy=status&groupBy=flowId groups items by status AND flowId. Default: empty.
filterBy[]		You can specify multiple filters as explained below. Specifying the same type of filter multiple times with different values is considered a union query, which means that the reports contains all steps that match one of the conditions. Specifying multiple different filters results in an intersection query, for example filterBy[status]=failed&filterBy[flowId]=123e4567e89b12d3a456426655440000 only returns step which failed and have a flowId of 123e4567e89b12d3a456426655440000. Default: empty.
filterBy[flowId]	string	The UUID of the flow. It remains unchanged during its lifecycle. Default: empty.
filterBy[status]	string	Status of an step. Valid values are finished and failed, case insensitive. Default: empty.
filterBy[action]	string	The action of the step; the thing it does. Default: empty.
sort	string	Specify sort criteria with the following syntax: key1:direction1[,key2:direction2]. If a direction is omitted, asc (ascending) is assumed. Valid keys are count, totalSuccessCount, totalFailureCount, successRate, failureRate. Valid directions are asc, desc. The appearance order of more than one key will be preserved when sorting a result. Further, the sorted result will be sorted by time in ascending order. For example, sort=count:desc will sort results by count in descending order. And the items having the same sorting key values will be sorted in time ascending order if periodGroup is not none. Default: empty.
offset	integer	The number of elements to skip. Default: 0, skipping zero element.
limit	integer	The number of elements to return. Valid values are any integer number between 1 and 2500, both inclusive. A number larger than 2500 will be clipped to 2500. Default: 500.
ref	string	A string to ensure consistency of pagination. When accessing the first part of result, it will be included in the response. To access further parts it needs to be added as a request query parameter.

The desired output format can be specified with the Accept header. Valid values are application/json (default) and text/csv.

Available HTTP Methods

GET /step

Example Request

curl -X GET 'https://rest.messagebird.com/reporting/step?periodStart=2019-03-01T00:00:00Z&periodEnd=2019-03-30T00:00:00Z&periodGroup=month&groupBy=status' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Example Response

{
  "items": [
    {
      "timestamp": "2019-01-01T00:00:00Z",
      "invocation": {
        "status": "expired",
        "flowTrigger": "invalid"
      },
      "count": 1,
      "successCount": 0,
      "failureCount": 0,
      "successRate": 0,
      "failureRate": 0
    }
  ],
  "ref": "54730373ac1a4fdaba0814d82e10d16e",
  "totalCount": 1
}

The action table

Trigger	Description
subscribe_to_group	An action to subscribe to a group
unsubscribe_from_group	An action to unsubscribe from a group
send_sms	An action to send an sms
forward_to_email	An action to forward to an email
send_email	An action to send an email
do_http_callback	An action to do an http callback
transfer	An action to do transfer
say	An action to say something
play	An action to play something
pause	An action to pause something
record	An action to record something
fetch_call_flow	An action to fetch a call flow
hangup	An action to hangup
switch	An action to switch
do_outbound_voice_call	An action to do an outbound voice call
await	An action to await
delete_contact	An action to delete a contact
jump_to_step	An action to jump to a step
send_conversation_message	An action to send a conversation message

The status table

Status	Description
finished	A step has finished.
failed	A step has failed.

The step Object

A step describes a flow being invoked by a user.

Attribute	Type	Description
status	string	Status of an step.
flowId	string	Id of the flow the step refers.
action	string	The action of the step; the thing it does.

Step Report object

This object represents a statistic.

Attributes

Attribute	Type	Description
items	array	Steps are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestamp	datetime	The timestamp in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-08-06T00:00:00Z represents the 32th week in 2018 or the first hour of the day August 6, 2018 or the day itself.
items[].step	object	Contains details about the steps based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].successCount	integer	The number of successful steps in a group.
items[].failureCount	integer	The number of failed steps in a group.
items[].successRate	float	The average rate of successful steps in a group.
items[].failureRate	float	The average rate of failed steps in a group.
items[].count	integer	The number of items in a group.
totalCount	integer	The total number of items that can be retrieved for this request through pagination.
ref	string	A string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.

CSV format response fields

Attribute	Type	Description
timestamp	datetime	The date and time in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-04-09T00:00:00Z represents the 15th week in 2018 or the first hour of the day April 9, 2018 or the day itself. Exists only when periodGroup is not none.
status	string	Status of an step. Exist only when group by status
flowId	string	Id of the flow the step refers. Exist only when group by flowId
action	string	The action of the step; the thing it does. Exist only when group by action
count	integer	The total number of items in a group.
successCount	integer	The number of successful steps in a group.
failureCount	integer	The number of failed steps in a group.
successRate	float	The average rate of successful steps in a group.
failureRate	float	The average rate of failed steps in a group.

Step Example requests

Steps grouped by trigger type

Group all steps made in August, 2018 UTC+8 by action to see one month steps for the trigger types.

Steps grouped by trigger type

curl -X GET 'https://rest.messagebird.com/reporting/step?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&periodGroup=none&groupBy=action&timezone=Asia/Shanghai' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Daily steps grouped by trigger type

Group all steps made in August, 2018 UTC+8 by action and day to see daily steps for the trigger types.

Daily steps grouped by trigger type

curl -X GET 'https://rest.messagebird.com/reporting/step?periodStart=2018-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&timezone=Asia/Shanghai&periodGroup=day&groupBy=action' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Iterate over all items

Requesting the first part gives us the first 100 items and ref: 03aa7194b10111e88981529269fb1459. In order to get the second part, run the second request.

Iterate over all items

curl -X GET 'https://rest.messagebird.com/reporting/step?periodStart=2016-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

curl -X GET 'https://rest.messagebird.com/reporting/step?periodStart=2016-08-01T00%3A00%3A00%2B08%3A00&periodEnd=2018-09-01T00%3A00%3A00%2B08%3A00&offset=100&limit=100&ref=03aa7194b10111e88981529269fb1459' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Email

Required parameters

Attribute	Type	Description
periodStart	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the start of the reporting period.
periodEnd	datetime	The date and time in UTC, RFC3339 format (Y-m-d\TH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

Attribute	Type	Description
periodGroup	string	The time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezone	string	The timezone to group and display the results in the time-dimension, such as “Europe/Amsterdam” or “US/Central”. All location names in the IANA Time Zone Database are valid. Default: UTC.
groupBy	string list	Zero or more values from channelId, status. More than one value can be specified by repeating the query parameter. For example, groupBy=channelId&groupBy=status groups items by channel AND status. Default: empty.
filterBy[]		You can specify multiple filters as explained below. Specifying the same type of filter multiple times with different values is considered a union query, which means that the reports contains all emails that match one of the conditions. Specifying multiple different filters results in an intersection query, for example filterBy[channelId]=b54ccc2b5684473aa6f6863309e61fdb&filterBy[status]=received returns statistics over emails received by recipients through channel b54ccc2b5684473aa6f6863309e61fdb.
filterBy[channelId]	string	Filters by channel id, for example filterBy[channelId]=ad27e9240ba241a792ce54dfd330f360&filterBy[channelId]=0fc77eed542d4397b8eac6725b626472
filterBy[messageId]	string	A UUID identifying an email. For example filterBy[messageId]=b54ccc2b5684473aa6f6863309e61fdb&filterBy[messageId]=fc1f5798491e481b93f13452e3f55407. Default: empty.
filterBy[status]	string	Filters by email status, valid values are accepted, delayed, failed, opened, received, sent. Note a status is transitional. An email could go through accepted to sent to received and opened but it can be in only one status at one moment. For example filterBy[status]=accepted&filterBy[status]=received
sort	string	Specify sort criteria with the following syntax: key1:direction1[,key2:direction2]. Valid keys are count. Valid directions are asc, desc. If a direction is omitted, asc is assumed. The appearance order of more than one key will be preserved when sorting a result. Further, the sorted result will be sorted by time in ascending order. For example, sort=count:desc will sort results by count in descending order. And the items having the same count will be sorted in time ascending order.
offset	integer	The number of elements to skip. Default: 0, skipping zero element.
limit	integer	The number of elements to return. Valid values are any integer number between 1 and 2500, both inclusive. A number larger than 2500 will be clipped to 2500. Default: 500.
ref	string	A string to ensure consistency of pagination. When accessing the first part of result, it will be included in the response. To access further parts it needs to be added as a request query parameter.

Available HTTP Methods

GET /conversations/email

Example Request

curl -X GET 'https://rest.messagebird.com/reporting/conversations/email?periodStart=2019-06-01T00:00:00Z&periodEnd=2019-09-01T00:00:00Z&periodGroup=month&groupBy=status' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Example Response

{
  "items": [
    {
      "timestamp": "2019-06-01T00:00:00Z",
      "message": {
        "status": "received"
      },
      "count": 1
    },
    {
      "timestamp": "2019-06-01T00:00:00Z",
      "message": {
        "status": "sent"
      },
      "count": 8
    }
  ],
  "ref": "e84a7c0b943d4ba7bec73cc956a6b113",
  "totalCount": 2
}

The desired output format can be specified with the Accept header. Valid values are application/json (default) and text/csv.

Email Report object

This object represents a statistic.

Attributes

Attribute	Type	Description
items	array	Emails are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestamp	datetime	The timestamp in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2019-03-27T08:00:00+01:00 represents the start of 8AM March 27, 2019 in UTC+1.
items[].email	object	Contains details about the messages based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].count	integer	The number of emails submitted to MessageBird in the specified time period. If email status is not empty, it represents the number of emails in that status when a request is being made.
ref	string	A string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.
totalCount	integer	The total number of items that can be retrieved for this request through pagination. Note this is not the sum over all count in each item.

The email Object

Attribute	Type	Description
channelId	string	Channel id, a UUID string. Exists only when group by channelId.
status	string	Email status. Exists only when group by status.

CSV format response fields

Attribute	Type	Description
timestamp	datetime	The date and time in RFC3339 format (Y-m-d\TH:i:sP). The first second of hour / day / week / month / year will be used to represent the period group. For example, 2018-04-09T00:00:00Z represents the 15th week in 2018 or the first hour of the day April 9, 2018 or the day itself. Exists only when periodGroup is not none.
channelId	string	Channel id, a UUID string. Exists only when group by channelId.
status	string	Email status. Exists only when group by status.
count	integer	The number of emails.

Email Example requests

Number of emails accepted by MessageBird in June, 2019.

Submitted emails in June

curl -X GET 'https://rest.messagebird.com/reporting/conversations/email?periodStart=2019-06-01T00%3A00%3A00%2B08%3A00&periodEnd=2019-07-01T00%3A00%3A00%2B08%3A00&periodGroup=none&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Number of emails accepted by MessageBird per month in 2019.

Submitted emails grouped by month

curl -X GET 'https://rest.messagebird.com/reporting/conversations/email?periodStart=2019-01-01T00%3A00%3A00%2B08%3A00&periodEnd=2020-01-01T00%3A00%3A00%2B08%3A00&periodGroup=month&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Number of emails accepted by MessageBird per status in June, 2019.

Submitted emails grouped by status

curl -X GET 'https://rest.messagebird.com/reporting/conversations/email?periodStart=2019-06-01T00%3A00%3A00%2B08%3A00&periodEnd=2019-07-01T00%3A00%3A00%2B08%3A00&periodGroup=none&groupBy=status&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Number of emails received per day in June, 2019.

Received emails per day in June

curl -X GET 'https://rest.messagebird.com/reporting/conversations/email?periodStart=2019-06-01T00%3A00%3A00%2B01%3A00&periodEnd=2019-07-01T00%3A00%3A00%2B02%3A00&periodGroup=day&filterBy%5Bstatus%5D=received&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Number of emails accepted by MessageBird per day in March, 2019, Amsterdam time.

Note periodStart is in UTC+1 while periodEnd is in UTC+2 and timezone is set to Europe/Amsterdam due to daylight saving time. In response, the timestamp also carries timezone information, for example 2019-03-27T00:00:00+01:00.

Submitted emails per day in Amsterdam time

curl -X GET 'https://rest.messagebird.com/reporting/conversations/email?periodStart=2019-03-01T00%3A00%3A00%2B01%3A00&periodEnd=2019-04-01T00%3A00%3A00%2B02%3A00&periodGroup=day&timezone=Europe/Amsterdam&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

A large number of items (totalCount is large).

First request, offset=0&limit=100. The second request offset=0&limit=100&ref=0226f90e567d43c6ae160fe0ddfa5560.

A large number of items

curl -X GET 'https://rest.messagebird.com/reporting/conversations/email?periodStart=2019-01-01T00%3A00%3A00%2B01%3A00&periodEnd=2020-01-01T00%3A00%3A00%2B02%3A00&periodGroup=day&offset=0&limit=100' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

curl -X GET 'https://rest.messagebird.com/reporting/conversations/email?periodStart=2019-01-01T00%3A00%3A00%2B01%3A00&periodEnd=2020-01-01T00%3A00%3A00%2B02%3A00&periodGroup=day&offset=100&limit=100&ref=0226f90e567d43c6ae160fe0ddfa5560' \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Accept: application/json'

Is this page useful?

Next upApi

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings