Reporting API beta

Notification icon

Be the first to explore your data in our new reporting API, now in beta. To gain access, email our product manager: sebastiaan@messagebird.com

This API enables you to programmatically retrieve reports on SMS/Voice/Conversations sent performed on our platform. You can use various filters and group-by parameters for your requests. For example, you can retrieve all messages sent to recipients in a particular country and find out how often deliveries failed. You can generate 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.

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.

URL

Please note that values of request parameters 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.

URL

https://rest.messagebird.com/reporting

SMS

Required request parameters

AttributeTypeDescription
periodStartdatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the start of the reporting period.
periodEnddatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

AttributeTypeDescription
periodGroupstringThe time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezonestringThe 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.
groupBystring listZero 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]stringFilters 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]integerA 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]stringAn 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]integerA 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]integerA 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]stringAn 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]stringFilters 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
sortstringSpecify 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]integerThe page to be accessed. Default: 1, the first page.
pageSize [deprecated]integerValid values are any integer number between 1 and 2500, both inclusive. A number larger than 2500 will be clipped to 2500. Default: 500.
offsetintegerThe number of elements to skip. Default: 0, skipping zero element.
limitintegerThe 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.
refstringA 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 YOUR_ACCESS_KEY' -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

AttributeTypeDescription
itemsarrayMessages are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestampdatetimeThe timestamp in RFC3339 format (Y-m-dTH: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[].messageobjectContains details about the messages based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].submittedCountintegerThe number of messages submitted to MessageBird in the specified time period.
items[].deliveredCountintegerThe number of messages delivered in the specified time period.
items[].processingCountintegerThe number of messages being processed at MessageBird.
items[].failedCountintegerThe number of messages failed to deliver.
items[].deliveryImpossibleCountintegerThe number of messages that were impossible to deliver, for example an invalid recipient.
refstringA string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.
prev [deprecated]stringA link to get the previous page. Omitted for the first page. Note you still need to set authorization.
next [deprecated]stringA link to get the next page. Omitted for the last page. Note you still need to set authorization.
totalCountintegerThe total number of items that can be retrieved for this request through pagination.

The message Object

AttributeTypeDescription
mccintegerMobile Country Code, e.g. 204.
countryNamestringFull English name of the destination country.
networkCodeintegerMCC + MNC (Mobile Network Code), e.g. 20408.
originatorstringThe 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”.
accountstringAccount name. Exists only when group by account.

CSV format response fields

AttributeTypeDescription
timestampdatetimeThe date and time in RFC3339 format (Y-m-dTH: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.
mccintegerMobile country code. Exists only when group by country.
countryNamestringFull 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.
networkCodeintegerMCC + MNC (mobile network code). Exists only when group by networkCode.
originatorstringThe originator. Exists only when group by originator.
accountstringAccount name. Exists only when group by account.
submittedCountintegerThe number of messages submitted to MessageBird in the specified time period.
deliveredCountintegerThe number of messages delivered among the submitted.
processingCountintegerThe number of messages being processed at MessageBird.
failedCountintegerThe number of messages failed to deliver.
deliveryImpossibleCountintegerThe 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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -H 'Accept: application/json

CALL

Required request parameters

AttributeTypeDescription
periodStartdatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the start of the reporting period.
periodEnddatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

AttributeTypeDescription
periodGroupstringThe time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezonestringThe 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.
groupBystring listZero 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]stringA source that has been used for creating a call, which can either be a phone number or an alphanumeric caller. Default: empty.
filterBy[sourceCountryCode]stringAn 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]integerA 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]integerAn 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]stringType 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]stringA destination that has been used for receiving a call, for example a phone number. Default: empty.
filterBy[destinationCountryCode]stringAn 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]integerA 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]integerAn 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]stringType 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]stringA call status. See the Call Status table for possible values. More than one status can be provided by repeating the query parameter. Default: empty.
sortstringSpecify 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.
offsetintegerThe number of elements to skip. Default: 0, skipping zero element.
limitintegerThe 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.
refstringA 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 YOUR_ACCESS_KEY' -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

StatusDescription
startingA call is being established.
ongoingA call is happening now.
endedA call has been finished successfully.
failedAn error has occurred when establishing a call.
busyA call could not be established as the endpoint was busy.
no_answerA call was not picked up.
queuedA call is awaiting to be initiated.

Call Report object

This object represents a statistic.

Attributes

AttributeTypeDescription
itemsarrayCalls are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestampdatetimeThe timestamp in RFC3339 format (Y-m-dTH: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[].callobjectContains details about the calls based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].totalDurationintegerThe total duration (seconds) of calls in a group.
items[].averageDurationfloatThe average duration (seconds) of calls in a group.
items[].countintegerThe total number of calls in a group.
items[].successCountintegerThe number of successful calls in a group.
items[].failureCountintegerThe number of failed calls in a group.
items[].successRatefloatThe average rate of successful calls in a group.
items[].failureRatefloatThe average rate of failed calls in a group.
refstringA string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.
totalCountintegerThe 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.

AttributeTypeDescription
sourceEndpoint objectSource of a call.
destinationEndpoint objectDestination of a call.
statusstringThe status of calls in a group. See the Call Status table.
The Endpoint object

An endpoint is an object stores information about a number.

AttributeTypeDescription
numberstringNumber of the endpoint, such as 31648888888 and MessageBird.
countryCodestringCountry code of the endpoint. Exists only when group by country and number is a valid phone number.
countryPrefixintegerCountry prefix of the endpoint. Exists only when group by country and number is a valid phone number..
operatorPrefixintegerOperator prefix of the endpoint. Exists only when group by operator prefix and number is a valid phone number..
typestringType of the endpoint. Exists only when group by type.

CSV format response fields

AttributeTypeDescription
timestampdatetimeThe date and time in RFC3339 format (Y-m-dTH: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.
sourcestringSource number of a call. Exists only when group by source.
sourceCountryCodestringCountry code of the source of a call. Exists only when group by source country.
sourceCountryPrefixintegerCountry prefix of the source of a call. Exists only when group by source country.
sourceOperatorPrefixintegerOperator prefix of the source of a call. Exists only when group by operator prefix.
sourceTypestringType of the source of a call. Exists only when group by source type.
destinationstringDestination number of a call. Exists only when group by destination. Exists only when group by destination.
destinationCountryCodestringCountry code of the destination of a call. Exists only when group by destination country.
destinationCountryPrefixintegerCountry prefix of the destination of a call. Exists only when group by destination country.
destinationOperatorPrefixintegerOperator prefix of the destination of a call. Exists only when group by destination operator prefix.
destinationTypestringType of the destination of a call. Exists only when group by destination type.
statusstringThe status of calls in a group. See the Call Status table. Exists only when group by status.
totalDurationintegerThe total duration (seconds) of calls in a group.
averageDurationfloatThe average duration (seconds) of calls in a group.
countintegerThe total number of calls in a group.
successCountintegerThe number of successful calls in a group.
failureCountintegerThe number of failed calls in a group.
successRatefloatThe average rate of successful calls in a group.
failureRatefloatThe 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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -H 'Accept: application/json'

Leg

Required request parameters

AttributeTypeDescription
periodStartdatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the start of the reporting period.
periodEnddatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

AttributeTypeDescription
periodGroupstringThe time granularity to group the statistics. Valid values are none, hour, day, week, month and year, case insensitive. Default: day.
timezonestringThe 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.
groupBystring listZero 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]stringA source that has been used for creating a leg, which can either be a phone number or an alphanumeric string. Default: empty.
filterBy[sourceCountryCode]stringAn 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]integerA 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]integerAn 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]stringType 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]stringA destination that has been used for receiving a leg, which can either be a phone number or an alphanumeric receiver. Default: empty.
filterBy[destinationCountryCode]stringAn 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]integerA 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]integerAn 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]stringType 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]stringDirection of a leg, either incoming or outgoing, case insensitive. For example filterBy[direction]=incoming. Default: empty.
filterBy[protocol]stringA 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]stringA leg status. See the Leg Status table for possible values. More than one status can be provided by repeating the query parameter. Default: empty.
sortstringSpecify 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.
offsetintegerThe number of elements to skip. Default: 0, skipping zero element.
limitintegerThe 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.
refstringA 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 osl8FBYWkrFiJJjXpUkgZ9aj8' -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

StatusDescription
startingA leg is being established.
ringingA leg is awaiting to be picked up.
ongoingA leg is happening now.
hangupA leg has been finished successfully.
busyA leg could not be established as the endpoint was busy.
no_answerA leg was not picked up.
failedAn error has occurred when establishing a leg.

Leg Report object

This object represents a statistic.

Attributes

AttributeTypeDescription
itemsarrayLegs are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestampdatetimeThe timestamp in RFC3339 format (Y-m-dTH: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[].legobjectContains details about the legs based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].totalDurationintegerThe total duration (seconds) of legs in a group.
items[].averageDurationfloatThe average duration (seconds) of legs in a group.
items[].countintegerThe total number of legs in a group.
items[].successCountintegerThe number of successful legs in a group.
items[].failureCountintegerThe number of failed legs in a group.
items[].successRatefloatThe average rate of successful legs in a group.
items[].failureRatefloatThe average rate of failed legs in a group.
refstringA string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.
totalCountintegerThe 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.

AttributeTypeDescription
sourceEndpoint objectSource of a leg.
destinationEndpoint objectDestination of a leg.
directionstringDirection of a leg, either incoming or outgoing.
protocolstringA leg protocol. Possible values are did, sip, webrtc.
statusstringThe status of legs in a group. See the Leg Status table.
The Endpoint object

An endpoint is an object stores information about a number.

AttributeTypeDescription
numberstringNumber of the endpoint, for example 31648888888.
countryCodestringCountry code of the endpoint. Exists only when group by country.
operatorPrefixintegerOperator prefix of the endpoint. Exists only when group by operator prefix.
typestringType of the endpoint. Exists only when group by type.

CSV format response fields

AttributeTypeDescription
timestampdatetimeThe date and time in RFC3339 format (Y-m-dTH: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.
sourcestringSource number of a leg. Exists only when group by source.
sourceCountryCodestringCountry code of the source of a leg. Exists only when group by source country.
sourceOperatorPrefixintegerOperator prefix of the source of a leg. Exists only when group by operator prefix.
sourceTypestringType of the source of a leg. Exists only when group by source type.
destinationstringDestination number of a leg. Exists only when group by destination. Exists only when group by destination.
destinationCountryCodestringCountry code of the destination of a leg. Exists only when group by destination country.
destinationOperatorPrefixintegerOperator prefix of the destination of a leg. Exists only when group by destination operator prefix.
destinationTypestringType of the destination of a leg. Exists only when group by destination type.
directionstringDirection of a leg, either incoming or outgoing. Exists only when group by direction.
protocolstringA leg protocol. Possible values are did, sip, webrtc.
statusstringThe status of legs in a group. See the Leg Status table. Exists only when group by status.
totalDurationintegerThe total duration (seconds) of legs in a group.
averageDurationfloatThe average duration (seconds) of legs in a group.
countintegerThe total number of legs in a group.
successCountintegerThe number of successful legs in a group.
failureCountintegerThe number of failed legs in a group.
successRatefloatThe average rate of successful legs in a group.
failureRatefloatThe 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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -H 'Accept: application/json'

Conversations Message

Parameters

AttributeTypeDescription
periodStartTimestampField is Required. The date and time in RFC3339 format (Y-m-dTH:i:sP) for the start of the reporting period.
periodEndTimestampField is Required. The date and time in RFC3339 format (Y-m-dTH:i:sP) for the end of the reporting period. This must be after periodStart.
periodGroupstringThe time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezonestringThe 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.
groupBysstringZero 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.
filterByPublicFilterYou 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.
sortstringSpecify 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.
offsetuint32The number of elements to skip. Default: 0, skipping zero element.
limituint32The 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.
refstringA 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

AttributeTypeDescription
directionstringDirection of a message, either sent or received, case insensitive. For example filterBy[direction]=sent. Default: empty.
statusstringStatus 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.
typestringType 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_idstringId of channel. More than one type of protocol can be provided by repeating the query parameter. Default: empty.
platformstringPlatform 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 YOUR_ACCESS_KEY' -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

AttributeTypeDescription
itemsMessageResponseItemMessages are split by provided grouping fields. Each item corresponds to statistics of a group.
refstringA string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.
total_countuint64The total number of items that can be retrieved for this request through pagination.

MessageResponseItem object

AttributeTypeDescription
timestampstringThe timestamp in RFC3339 format (Y-m-dTH: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.
messageMessageItemContains details about the messages based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
countuint64The total number of messages in a group.

MessageItem object

AttributeTypeDescription
directionstringDirection of a message, either sent or received.
platformstringMessage platform name.
statusstringStatus of a message, valid values are deleted, delivered, failed, pending, read, received, rejected, sent, unsupported.
typestringType of a message, valid values are text, image, audio, video, location, file, hsm (only for WhatsApp), unknown.
channelstringMessage channel id.

CSV format response fields

AttributeTypeDescription
countintegerThe total number of messages in a group.
timestampdatetimeThe date and time in RFC3339 format (Y-m-dTH: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.
directionstringDirection of a message, either sent or received.
statusstringStatus of a message, valid values are deleted, delivered, failed, pending, read, received, rejected, sent, unsupported.
typestringType of a message, valid values are text, image, audio, video, location, file, hsm (only for WhatsApp), unknown.
platformstringMessage platform name.
channelstringMessage 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 YOUR_ACCESS_KEY' -H 'Accept: application/json'

Flow

Required request parameters

AttributeTypeDescription
periodStartdatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the start of the reporting period.
periodEnddatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the end of the reporting period. This must be after periodStart.

Available HTTP Methods

GET /flow

Optional parameters

AttributeTypeDescription
periodGroupstringThe time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezonestringThe 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.
groupBystring listZero 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]stringThe UUID of the flow. It remains unchanged during its lifecycle. Default: empty.
filterBy[trigger]stringAn action that caused a invocation to be triggered. Default: empty.
sortstringSpecify 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.
offsetintegerThe number of elements to skip. Default: 0, skipping zero element.
limitintegerThe 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.
refstringA 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

TriggerDescription
on_received_smsA flow triggered by an sms.
on_incoming_voice_callA flow triggered by an phonecall.
on_received_http_requestA flow triggered by an webhook.
on_received_conversation_messageA 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.

AttributeTypeDescription
triggerstringThe 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

AttributeTypeDescription
itemsarrayFlows are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestampdatetimeThe timestamp in RFC3339 format (Y-m-dTH: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[].flowobjectContains details about the flows based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].countintegerThe number of items in a group.
totalCountintegerThe total number of items that can be retrieved for this request through pagination.
refstringA string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.

CSV format response fields

AttributeTypeDescription
timestampdatetimeThe date and time in RFC3339 format (Y-m-dTH: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.
triggerstringAn action that caused an invocation to be triggered. Exist only when group by triggerType
countintegerThe 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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -H 'Accept: application/json'

Invocation

Required request parameters

AttributeTypeDescription
periodStartdatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the start of the reporting period.
periodEnddatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

AttributeTypeDescription
periodGroupstringThe time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezonestringThe 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.
groupBystring listZero 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]stringThe UUID of the flow. It remains unchanged during its lifecycle. Default: empty.
filterBy[status]stringStatus of an invocation. Valid values are in_progress, finished and failed, case insensitive. Default: empty.
filterBy[flowTrigger]stringAn action that caused a invocation to be triggered. Default: empty.
filterBy[source]stringThe 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]stringThe target of the invocation, e.g. the recipient (VMN) of a received SMS, or some other identifier related to the trigger. Default: empty.
sortstringSpecify 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.
offsetintegerThe number of elements to skip. Default: 0, skipping zero element.
limitintegerThe 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.
refstringA 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 YOUR_ACCESS_KEY' -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

TriggerDescription
on_received_smsA flow triggered by an sms.
on_incoming_voice_callA flow triggered by an phone call.
on_received_http_requestA flow triggered by an webhook.
on_received_conversation_messageA flow triggered by an omnichannel conversation message.

The status table

StatusDescription
in_progressAn invocation is in progress.
finishedAn invocation has finished.
failedAn invocation has failed.
cancelledAn invocation has cancelled.
expiredAn invocation has expired.

The invocation Object

An invocation describes a flow being invoked by a user.

AttributeTypeDescription
statusstringStatus of an invocation. Exist only when group by status.
flowIdstringId of the flow the invocation refers. Exist only when group by flowId.
flowTriggerstringAn action that caused a invocation to be triggered. Exist only when group by flowTrigger.

Invocation Report object

This object represents a statistic.

Attributes

AttributeTypeDescription
itemsarrayInvocations are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestampdatetimeThe timestamp in RFC3339 format (Y-m-dTH: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[].invocationobjectContains details about the invocations based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].successCountintegerThe number of successful invocations in a group.
items[].failureCountintegerThe number of failed invocations in a group.
items[].successRatefloatThe average rate of successful invocations in a group.
items[].failureRatefloatThe average rate of failed invocations in a group.
items[].countintegerThe number of items in a group.
totalCountintegerThe total number of items that can be retrieved for this request through pagination.
refstringA string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.

CSV format response fields

AttributeTypeDescription
timestampdatetimeThe date and time in RFC3339 format (Y-m-dTH: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.
statusstringStatus of an invocation. Exist only when group by status
flowIdstringThe UUID of the flow. It remains unchanged during its lifecycle. Exist only when group by flowId
flowTriggerstringAn action that caused a invocation to be triggered. Exist only when group by flowTrigger
countintegerThe total number of items in a group.
successCountintegerThe number of successful invocations in a group.
failureCountintegerThe number of failed invocations in a group.
successRatefloatThe average rate of successful invocations in a group.
failureRatefloatThe 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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -H 'Accept: application/json'

Step

Required request parameters

AttributeTypeDescription
periodStartdatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the start of the reporting period.
periodEnddatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

AttributeTypeDescription
periodGroupstringThe time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezonestringThe 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.
groupBystring listZero 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]stringThe UUID of the flow. It remains unchanged during its lifecycle. Default: empty.
filterBy[status]stringStatus of an step. Valid values are finished and failed, case insensitive. Default: empty.
filterBy[action]stringThe action of the step; the thing it does. Default: empty.
sortstringSpecify 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.
offsetintegerThe number of elements to skip. Default: 0, skipping zero element.
limitintegerThe 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.
refstringA 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 YOUR_ACCESS_KEY' -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

TriggerDescription
subscribe_to_groupAn action to subscribe to a group
unsubscribe_from_groupAn action to unsubscribe from a group
send_smsAn action to send an sms
forward_to_emailAn action to forward to an email
send_emailAn action to send an email
do_http_callbackAn action to do an http callback
transferAn action to do transfer
sayAn action to say something
playAn action to play something
pauseAn action to pause something
recordAn action to record something
fetch_call_flowAn action to fetch a call flow
hangupAn action to hangup
switchAn action to switch
do_outbound_voice_callAn action to do an outbound voice call
awaitAn action to await
delete_contactAn action to delete a contact
jump_to_stepAn action to jump to a step
send_conversation_messageAn action to send a conversation message

The status table

StatusDescription
finishedA step has finished.
failedA step has failed.

The step Object

A step describes a flow being invoked by a user.

AttributeTypeDescription
statusstringStatus of an step.
flowIdstringId of the flow the step refers.
actionstringThe action of the step; the thing it does.

Step Report object

This object represents a statistic.

Attributes

AttributeTypeDescription
itemsarraySteps are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestampdatetimeThe timestamp in RFC3339 format (Y-m-dTH: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[].stepobjectContains details about the steps based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].successCountintegerThe number of successful steps in a group.
items[].failureCountintegerThe number of failed steps in a group.
items[].successRatefloatThe average rate of successful steps in a group.
items[].failureRatefloatThe average rate of failed steps in a group.
items[].countintegerThe number of items in a group.
totalCountintegerThe total number of items that can be retrieved for this request through pagination.
refstringA string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.

CSV format response fields

AttributeTypeDescription
timestampdatetimeThe date and time in RFC3339 format (Y-m-dTH: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.
statusstringStatus of an step. Exist only when group by status
flowIdstringId of the flow the step refers. Exist only when group by flowId
actionstringThe action of the step; the thing it does. Exist only when group by action
countintegerThe total number of items in a group.
successCountintegerThe number of successful steps in a group.
failureCountintegerThe number of failed steps in a group.
successRatefloatThe average rate of successful steps in a group.
failureRatefloatThe 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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -H 'Accept: application/json'

Email

Required request parameters

AttributeTypeDescription
periodStartdatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the start of the reporting period.
periodEnddatetimeThe date and time in RFC3339 format (Y-m-dTH:i:sP) for the end of the reporting period. This must be after periodStart.

Optional parameters

AttributeTypeDescription
periodGroupstringThe time granularity to group the statistics. Valid values are none, hour, day, week, month, year. Default: day.
timezonestringThe 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.
groupBystring listZero 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]stringFilters by channel id, for example filterBy[channelId]=ad27e9240ba241a792ce54dfd330f360&filterBy[channelId]=0fc77eed542d4397b8eac6725b626472
filterBy[messageId]stringA UUID identifying an email. For example filterBy[messageId]=b54ccc2b5684473aa6f6863309e61fdb&filterBy[messageId]=fc1f5798491e481b93f13452e3f55407. Default: empty.
filterBy[status]stringFilters 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
sortstringSpecify 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.
offsetintegerThe number of elements to skip. Default: 0, skipping zero element.
limitintegerThe 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.
refstringA 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 YOUR_ACCESS_KEY' -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

AttributeTypeDescription
itemsarrayEmails are split by provided grouping fields. Each item corresponds to statistics of a group.
items[].timestampdatetimeThe timestamp in RFC3339 format (Y-m-dTH: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[].emailobjectContains details about the messages based on the groupBy parameters. If no groupBy parameter was specified this object will be empty.
items[].countintegerThe 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.
refstringA string to ensure consistency of pagination. A ref expires one day after creation and its lifetime cannot be extended.
totalCountintegerThe 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

AttributeTypeDescription
channelIdstringChannel id, a UUID string. Exists only when group by channelId.
statusstringEmail status. Exists only when group by status.

CSV format response fields

AttributeTypeDescription
timestampdatetimeThe date and time in RFC3339 format (Y-m-dTH: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.
channelIdstringChannel id, a UUID string. Exists only when group by channelId.
statusstringEmail status. Exists only when group by status.
countintegerThe number of emails.

Email 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.

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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -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 YOUR_ACCESS_KEY' -H 'Accept: application/json'
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings