Preview a Report Schedule

print_mail.reports.preview_schedule() -> SchedulePreview

POST/print-mail/v1/reports/schedule_previews

Work out when a schedule would actually run, without saving anything. Takes the same fields as the schedule on a report, plus an optional sqlQuery so you can check whether that query is schedulable at all (a parameterized query is not).

ParametersExpand Collapse

interval: int

How many units pass between runs — the 2 in “every 2 weeks”.

formatint32

minimum1

time: str

The 24-hour HH:mm time of day the report runs, in America/Toronto.

unit: Literal["h", "d", "w", 2 more]

The cadence units a report schedule may use: hour, day, week, month, or year.

One of the following:

"h"

"d"

"w"

"m"

"y"

day_of_month: Optional[int]

Monthly and yearly schedules only. Monthly schedules are capped at 28 so a run never skips a short month.

formatint32

minimum1

maximum31

day_of_week: Optional[int]

Weekly schedules only. 0 is Sunday through 6 for Saturday.

formatint32

minimum0

maximum6

month: Optional[int]

Yearly schedules only. 0 is January through 11 for December.

formatint32

minimum0

maximum11

notification_emails: Optional[Sequence[str]]

Up to 10 addresses to email when a run finishes. Each must belong to a user in the same organization as the report; others are skipped. Omit or pass an empty array to send no email.

sql_query: Optional[str]

The query the schedule would run against. Supplying it flags a parameterized query as unschedulable via queryHasParameters. It is only inspected — creating or updating a report always uses the report’s own sqlQuery.

ReturnsExpand Collapse

class SchedulePreview: …

The cadence PostGrid derived from a schedule, returned without saving anything. Useful for confirming when a schedule would actually run.

day_of_month: int

The day of the month the schedule resolved to, clamped to a day that exists.

formatint32

day_of_month_options: List[DayOfMonthOption]

The days of the month this cadence may be anchored to, with display labels.

label: str

The day as an ordinal, for example 15th.

value: int

The day of the month.

formatint32

description: str

The cadence in words, for example Every 2 weeks on Monday at 9:00 AM (America/Toronto).

first_run_label: str

The first run as an absolute instant, for example Monday, June 15, 2026 at 9:00 AM.

frequency: str

The cadence as a number + unit, for example 1h or 2d.

next_run: datetime

When the report would run next.

formatdate-time

query_has_parameters: bool

True if the supplied sqlQuery uses parameters, which makes it unschedulable.

Preview a Report Schedule

import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
schedule_preview = client.print_mail.reports.preview_schedule(
    interval=1,
    time="09:00",
    unit="w",
    day_of_week=1,
    notification_emails=["[email protected]"],
)
print(schedule_preview.day_of_month)

{
  "frequency": "1w",
  "nextRun": "2026-06-15T13:00:00Z",
  "description": "Every week on Monday at 9:00 AM (America/Toronto)",
  "firstRunLabel": "Monday, June 15, 2026 at 9:00 AM",
  "dayOfMonth": 1,
  "dayOfMonthOptions": [
    {
      "value": 1,
      "label": "1st"
    },
    {
      "value": 2,
      "label": "2nd"
    }
  ],
  "queryHasParameters": false
}

Returns Examples

{
  "frequency": "1w",
  "nextRun": "2026-06-15T13:00:00Z",
  "description": "Every week on Monday at 9:00 AM (America/Toronto)",
  "firstRunLabel": "Monday, June 15, 2026 at 9:00 AM",
  "dayOfMonth": 1,
  "dayOfMonthOptions": [
    {
      "value": 1,
      "label": "1st"
    },
    {
      "value": 2,
      "label": "2nd"
    }
  ],
  "queryHasParameters": false
}