Create Email Schedule

A created email schedule detail would be responded if the payload is valid or an error if invalid or missing required fields. By default, all email schedules in Holistics are based on UTC timezone. The created email schedule will be matched with the assigned source ID and cannot change it later.

Request#

POST /api/v1/email_schedules

Payload examples#

Create email schedule with subject Company Report, start at 4:00 AM (UTC) every day for dashboard ID 5995, with format in Excel and date filter from 2019-03-25 only:

{
  "title": "Company Report",
  "recipients": [
    "[email protected]",
    "[email protected]"
  ],
  "bcc": [
    "[email protected]"
  ],
  "body_text": "sample text",
  "format": "excel",
  "source": {
    "type": "Dashboard",
    "id": 5995
  },
  "schedule": {
    "repeat": "0 4 * * *",
    "paused": false
  },
  "filter_values": {
    "start_date": "2019-03-25"
  }
}

Create email schedule start at 4:00 AM (UTC) every day for dashboard ID 5995, with format in Excel and password protected:

{
  "title": "Daily at 0:40 (UTC+0000)",
  "recipients": [
    "[email protected]",
    "[email protected]"
  ],
  "bcc": [
    "[email protected]"
  ],
  "body_text": "sample text",
  "format": "excel",
  "password": "1110291343546767",
  "source": {
    "type": "Dashboard",
    "id": 5995
  },
  "schedule": {
    "repeat": "0 4 * * *",
    "paused": true
  }
}

Fields#

General#

id: Numeric. Unique email schedule identifier
recipients: Array. List of email addresses.
bcc: Array. List of BCC addresses.
title: Text. Email subject. In default, source title will be used if title is not available.
body_text: Text. Text content inside email body.
format: Attachment format. Available values are txt, csv, excel, pdf or none. Default is excel.
source: Object. the source that this email schedule is referred to. Available only on retrieving data.
options: Object. Optional fields. Please see the Options for detail.
schedule: Object. Please see the Schedule for detail.
filter_values: Object. Filter values applied in this report/dashboard. Please see the Filter Values reference for detail.

Options#

preview: Include preview inside email content. Default value true
include_pdf: Include a PDF of a report or the whole dashboard. The default value is false.
include_header: Include column headers in an attached file. The default is false. Not available if the format is none
password: false (or null) if Password Protection disabled, string value ≥ 4 characters if enabled. The delivery file format will be a password-protected zip file that contains the data generated for CSV attachment(s), or a password-protected Excel file for Excel attachment(s). Available only on creating and updating email schedule. Not available if format is none
selected_widgets: List of widget IDs are selected to include in the email. _all for selecting all widgets.
include_report_link: Include link to report / dashboard. The default is false.
dont_send_when_empty: Just send the email when data is available. The default is false.

Schedule#

repeat: Crontab expression. Example: 0 4 * * * will start a job at 4:00 AM everyday. You can check your crontab expression by using https://crontab.guru
We recommend that you should change the repeat time to prevent anti-spam filter from your email provider. For example 0 4 * * * (job start at 4:00 AM UTC) could be 1 4 * * * (job start at 4:01 AM UTC) or 5 4 * * *(job start at 4:05 AM UTC) . This will also help your database does not get overload when there are many email schedules that execute at the same time.
paused: Pause execution temporarily. The default is false.

Source#

id: current source ID. You could find the Source ID via our docs.
type: current source type. You could find the Source Type via our docs.
title: source title, this will be used for field title if it is blank

Filter Values#

This object is mainly matched by the filter variable that you created inside Holistics. The default value will be used if you do not input any specific data to it.

For example, we need to update an email schedule that have time_period filter with the default value is week, category filter with the default value is all and date_range filter default is 2 days ago. The filter_values in the payload would be:

"filter_values": {
    "time_period": "week",
    "category": "_all",
    "date_range": "2 days ago"
  }

Tips and Tricks#

In case that you need to send the same dashboard/report to many recipients with custom filters, our recommendation is creating an email schedule using our UI first, then copy these values to create multiple email schedules with your desired filters.