Schedule custom reports

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

The endpoint allows scheduling a custom report of a specific type for a given time period. Depending on the report type, you can also narrow down the data using appropriate filters.

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

Important

The reports you can generate depend on your pricing plan.

subscription_rejections

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

{
  "name": "Subscription rejections - may 2024",
  "type": "subscription_rejections",
  "scheduling": {
    "frequency": "one_time",
    "startDate": "2024-05-01",
    "endDate": "2024-05-31"
  }
}

message_stats

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

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

unsubscribe_contacts_lists_report

Generate an unsubscribe contacts lists report just once for the timeframe spanning from 2024-05-01 to 2024-05-31

{
  "name": "unsubscribe contacts lists - may 2024",
  "type": "unsubscribe_contacts_lists_report",
  "scheduling": {
    "frequency": "one_time",
    "startDate": "2024-05-01",
    "endDate": "2024-05-31"
  }
}

standard_subscriber_activity_report

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

{
  "name": "Standard subscriber activity - may 2024",
  "type": "standard_subscriber_activity_report",
  "scheduling": {
    "frequency": "one_time",
    "startDate": "2024-05-01",
    "endDate": "2024-05-31"
  }
}

bounces

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"
   }
}

account_summary_report

Generate an account summary report just once for the timeframe spanning from 2024-05-01 to 2024-05-31

{
   "name": "Account summary - may 2024",
   "type": "account_summary_report",
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-05-01",
      "endDate": "2024-05-31"
   }
}

user_activity

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

{
   "name": "User activity - may 2024",
   "type": "user_activity",
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-05-01",
      "endDate": "2024-05-31"
   }
}

list_summary_report

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

{
   "name": "List summary - may 2024",
   "type": "list_summary_report",
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-05-01",
      "endDate": "2024-05-31"
   }
}

isp_message_stats_report

Generate an isp message stats report just once for the timeframe spanning from 2024-05-01 to 2024-05-31

{
   "name": "ISP message stats - may 2024",
   "type": "isp_message_stats_report",
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-05-01",
      "endDate": "2024-05-31"
   }
}

webinar_participants_report

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

{
   "name": "Webinar participants - may 2024",
   "type": "webinar_participants_report",
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-05-01",
      "endDate": "2024-05-31"
   }
}

import_error_report

Generate an import error report just once for the timeframe spanning from 2024-05-01 to 2024-05-31

{
   "name": "Import errors - may 2024",
   "type": "import_error_report",
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-05-01",
      "endDate": "2024-05-31"
   }
}

message_clicks_report

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

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

unconfirmed_contacts_stats_report

Generate an unconfirmed contacts stats report just once for the timeframe spanning from 2024-05-01 to 2024-05-31

{
   "name": "Unconfirmed contacts stats - may 2024",
   "type": "unconfirmed_contacts_stats_report",
   "scheduling": {
      "frequency": "one_time",
      "startDate": "2024-05-01",
      "endDate": "2024-05-31"
   }
}

transactional_email_bounce_report

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

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

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"
   }
}