Get Message Reports

Lets you download a list of messages sent by CleverTap.

Overview

To get a message report, you submit a request specifying the required date range. You can also filter results by setting optional parameters to return only specific channels or message statuses.

Base URL

The following is a sample base URL:

https://<region>.api.clevertap.com/1/message/report.json

For region-specific endpoints, refer to Region.

HTTP Method

POST

Headers

Refer to Headers for more details.

Body Parameters

The body is uploaded as a JSON payload. from and to are required. All optional parameters except daily accept multiple values as a comma-separated array.

The following table lists the body parameters.

ParameterDescriptionTypeExample Value
fromStart of the report date range. Value specified in YYYYMMDD format. Required.string"20171201"
toEnd of the date range for the report. Value specified in YYYYMMDD format. Required.string"20171225"
channelThe channels to include in the report. Supported values: push (mobile push), email, sms, browser (browser push), audiences (Facebook), inapp (in-app), webhooks, web_pop_up, web_exit_intent, web_native_display, web_inbox, tiktok, nativedisplay (alias for web_native_display). Optional.array of strings["push","email"]
deliveryDelivery type of communications for the report. Supported values: one_time, inaction, action, recurring, property_time, api, multiple_dates. Optional.array of strings["inaction","action"]
dailyDetermines if the report is a day-wise split or an aggregate report. When true, the data array in the response contains one entry per day in the date range. When false (default), data contains a single aggregated entry. Supported values: true or false. Optional.booleanfalse
statusThe campaign statuses to include in the report. Supported values: scheduled, running, stopped, completed. Optional.array of strings["completed","running"]
message_typeThe message types to include in the report. Supported values: single, ab, message_on_user_property. Optional.array of strings["single","ab"]
labelFilters results to include only messages with the specified labels. Optional.array of strings["Onboarding"]

The following is a sample payload:

{
   "from": "20171011",
   "to": "20171130",
   "daily": false,
   "channel": [
      "inapp"
   ],
   "delivery": [
      "inaction", "action"
   ],
   "status": [
      "completed"
   ],
   "message_type": [
      "single"
   ],
   "label": []
}

Example Request

The following is a sample request to the Get Message Reports API, showing the headers needed to authenticate the request.

curl -X POST -d '{"from":"20171101","to":"20171225"}' "https://<region>.api.clevertap.com/1/message/report.json" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE" \
-H "Content-Type: application/json"
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://<region>.api.clevertap.com/1/message/report.json")
request = Net::HTTP::Post.new(uri)
request.content_type = "application/json"
request["X-Clevertap-Account-Id"] = "ACCOUNT_ID"
request["X-Clevertap-Passcode"] = "PASSCODE"
request.body = JSON.dump({
  "from" => "20171101",
  "to" => "20171225"
})

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'X-CleverTap-Account-Id': 'ACCOUNT_ID',
    'X-CleverTap-Passcode': 'PASSCODE',
    'Content-Type': 'application/json',
}

data = '{"from":"20171101","to":"20171225"}'

response = requests.post('https://<region>.api.clevertap.com/1/message/report.json', headers=headers, data=data)
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
    'X-CleverTap-Account-Id' => 'ACCOUNT_ID',
    'X-CleverTap-Passcode' => 'PASSCODE',
    'Content-Type' => 'application/json'
);
$data = '{"from":"20171101","to":"20171225"}';
$response = Requests::post('https://<region>.api.clevertap.com/1/message/report.json', $headers, $data);
var request = require('request');

var headers = {
    'X-CleverTap-Account-Id': 'ACCOUNT_ID',
    'X-CleverTap-Passcode': 'PASSCODE',
    'Content-Type': 'application/json'
};

var dataString = '{"from":"20171101","to":"20171225"}';

var options = {
    url: 'https://<region>.api.clevertap.com/1/message/report.json',
    method: 'POST',
    headers: headers,
    body: dataString
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

Example Response

The following is a sample response:

{
    "status": "success",
    "total_results": 1,
    "messages": [
        {
            "message id": 1508323121,
            "data": [
                [
                    {
                        "sent": 0,
                        "viewed": 0,
                        "clicked": 0
                    }
                ]
            ],
            "start_date": "Oct 18, 4:08 PM",
            "device": [
                "Android",
                "iOS",
                "WindowsMobile"
            ],
            "conversion_event": null,
            "labels": [],
            "status": "completed",
            "channel": "InApp",
            "message_name": "in_app_outputs_test",
            "delivery": "Action"
        }
    ]
}

Response Schema

The following table describes the top-level response fields.

FieldTypeDescription
statusstringAlways "success" for successful requests.
total_resultsintegerTotal number of campaigns matching the query.
messagesarrayAn array of message report objects. See the message object fields below.

The following table describes the fields inside each message object in the messages array.

FieldTypeDescription
message idintegerUnique identifier for the message. Note: this field name contains a space, not an underscore. Attempting to access it as message_id will not work.
dataarrayDouble-nested array containing delivery metrics (sent, viewed, clicked). When daily is false, contains a single aggregated entry: [[{"sent": N, "viewed": N, "clicked": N}]]. When daily is true, contains one entry per day in the date range, in the same nested format.
start_datestringThe campaign start date and time, formatted as "MMM D, h:mm AM/PM" (for example, "Oct 18, 4:08 PM"). The year is not included. For queries that span multiple years, use the from and to date range parameters to determine the year context.
devicearray of stringsPlatforms targeted by this campaign (for example, "Android", "iOS"). WindowsMobile may appear for legacy campaigns but is no longer actively supported.
conversion_eventstring or nullThe event is configured as the conversion goal for this campaign. null if no conversion event was set.
labelsarray of stringsLabels assigned to this campaign. Empty array if no labels are set.
statusstringCurrent status of the campaign. Possible values: scheduled, running, stopped, completed.
channelstringThe channel used by this campaign. Response values use display names that differ from input values (for example, input inapp returns as "InApp", input one_time delivery returns as "One Time"). See the input-to-response mapping note below.
message_namestringThe name of the campaign.
deliverystringThe delivery type of the campaign. Response values use display names that differ from input values. See the input-to-response mapping note below.
📘

API Behavior

The Get Message Reports API fetches campaigns based on their start dates. Campaigns that begin before the specified date range but are still active are not included in the results.

For example, you have two email campaigns:

  • Campaign A: Started on June 1, 2023, and is still active, sending emails daily.
  • Campaign B: Started on June 7, 2023, and ended on June 10, 2023.

When you query for June 5, 2023 to June 8, 2023:

  • Campaign A is excluded because it started before the range (June 1), even though it is active during the range.
  • Campaign B is included because its start date falls within the range (June 7).

For more information on request limits, refer to API Request Limit. To understand common queries and concerns related to CleverTap APIs, refer to API FAQs.

Error Codes

The following table lists the error codes returned by this API:

HTTP StatusErrorDescriptionExample Error Response
400"X-CleverTap-Account-ID and X-CleverTap-Passcode are mandatory headers"One or both auth headers missing. Add both required headers.{"status":"fail","error":"X-CleverTap-Account-ID and X-CleverTap-Passcode are mandatory headers","code":400}
400"Content-Type must be application/json"Content-Type header missing or set to the wrong value. Set Content-Type: application/json.{"status":"fail","error":"Content-Type must be application/json","code":400}
400"Empty payload"Request body is empty. Include a JSON body with at least from and to.{"status":"fail","error":"Empty payload","code":400}
400"Invalid JSON body"Request body is not valid JSON. Fix JSON syntax before retrying.{"status":"fail","error":"Invalid JSON body","code":400}
400"Bad Request. Some mandatory parameter was missing"from or to date missing from body. Include both in YYYYMMDD format.{"status":"fail","error":"Bad Request. Some mandatory parameter was missing","code":400}
401"This account has been disabled"Account blocked or not found. Contact CleverTap support.{"status":"fail","error":"This account has been disabled","code":401}
429"Too many concurrent requests"Per-account concurrent request limit exceeded. Retry with exponential backoff.{"status":"fail","error":"Too many concurrent requests","code":429}
429"Too Many Requests"Message report API rate limit exceeded (1 request per hour for some accounts). Wait before retrying.{"status":"fail","error":"Too Many Requests","code":429}
500"An unknown error occurred"Unhandled server error. Retry; contact support if the issue persists.{"status":"fail","error":"An unknown error occurred","code":500}
503"Please retry later"Global throttle limit exceeded. Retry with backoff.{"status":"fail","error":"Please retry later","code":503}


Did this page help you?
CleverTap Ask AI Widget (CSP-Safe)