Schedule custom reports

To schedule a report, use POST /custom-reports.

Example request

POST /v3/custom-reports

{
   "name": "Activity Europe",
   "type": "message_activity_report",
   "filters": {
      "activityType": ["click", "open", "send"],
      "messageId": ["XYZ"]
   },
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-07-01",
      "endDate": "2024-08-01"
   }
}

Basic structure

Payload

{
   "name": "{customReportName}",
   "type": "{customReportType}",
   "filters": "{filters}",
   "scheduling": "{scheduling}"
}

Description

• name - Report name
• type - Report type
• filters - Filters used. Filter options depend on the type of report you select.
• scheduling - Frequency and time at which the report is generated. Check the table below for allowed fields and values.

Explanation of {scheduling} parameters:

Fields	Allowed values	Description
frequency	one_time	Frequency at which the report is generated
startDate	UTC date format RFC3339, e.g. "2018-04-10". Only for "frequency": "one_time".	The date from which data is collected
endDate	UTC date format RFC3339, e.g. "2018-05-10". Only for "frequency": "one_time".	The date to which the data is collected

Example:

Generate a report just once for the timeframe spanning from 2024-07-01 to 2024-08-01

{
   "name": "Activity Europe",
   "type": "message_activity_report",
   "filters": {
      "activityType": ["click", "open", "send"],
      "messageId": ["XYZ"]
   },
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-07-01",
      "endDate": "2024-08-01"
   }
}

Report types

message_activity_report

Explanation of {filters} parameters:

Fields	Allowed values	Description
activityType	click, open, send	Activities the report can include. You can select multiple activities.
messageId	Newsletter IDs for which the report is generated. To get messageId, use GET /v3/newsletters	Filter that narrows down the data collected to specific newsletters.

Example:

Generate a newsletter activity report that focuses on clicks or sends for newsletter IDs abX or xyZ

{
   "name": "Activity Test",
   "type": "message_activity_report",
   "filters": {
      "activityType": ["click", "send"],
      "messageId": ["abX", "xyZ"]
   },
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-07-01",
      "endDate": "2024-08-01"
   }
}

bounces

For this report type, {filters} are not used; therefore, the submitted payload should not include them.

Example:

Generate a bounces report just once for the timeframe spanning from 2024-05-01 to 2024-05-31

{
   "name": "Message bounces - may 2024",
   "type": "bounces",
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-05-01",
      "endDate": "2024-05-31"
   }
}