Schedules

Schedule a report for delivery by email

Configures the standing delivery of a report by email, or sends it once with frequency now. A report has at most one standing schedule: when it already has an active one the call is refused with 409 SCHEDULE_ALREADY_EXISTS, and when it has a stopped one this call reconfigures it and shows what it looked like before. The message comes either from an email template of the account or from the six email fields, never from both. A template cannot be scheduled. This endpoint ALWAYS asks for a confirmation, and it spends one unit of the daily budget of calls that send email. Refusals: 400 VALIDATION_FAILED, UNKNOWN_PARAM, MISSING_REQUIRED_FIELD or INVALID_VALUE, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND for the report, the email template or the language file it names, 409 SCHEDULE_ALREADY_EXISTS, SCHEDULE_ALREADY_QUEUED, SCHEDULE_QUEUED, NOT_EDITABLE_BY_API, SCHEDULE_USES_SYSTEM_TEMPLATE (when the stopped schedule this call would configure is built on the system email template) or ACCOUNT_HAS_NO_OWNER plus the confirmation and idempotency conflicts, 429 EMAIL_QUOTA_REACHED. Two warnings travel in a successful answer: REPORT_WILL_BE_SHARED_PUBLICLY when the link format will create and enable a public link without a password, and MAY_BE_DELIVERED_AGAIN_TODAY when the hour of the schedule has already passed today.

Every write endpoint reads dry_run and idempotency_key; see the Write guarantees section of the introduction.

post/schedules/create

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/schedules/create
  • Auth: HTTP bearer

Request body

report_keystring required

The report to deliver. It cannot be a template.

frequency'daily' | 'weekly' | 'monthly' | 'now' required

How often to deliver it. now sends it once, as soon as the next delivery pass runs, and leaves no standing order behind. none is not accepted here: use /v1/schedules/delete to stop a delivery.

frequency_detailsstring

REQUIRED with weekly and with monthly, rejected with any other frequency. With weekly it is the weekday in upper case: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY or SUNDAY. With monthly it is the day of the month written as a string, from "1" to "31".

timestring

Hour of the delivery in the time zone of the account, as HH:00. REQUIRED except with frequency now, which rejects it.

recipients_tostring[]

At least one address, at most 20, each at most 255 characters.

recipients_ccstring[]
recipients_bccstring[]
report_format'pdf' | 'xls' | 'link'

How the report travels. Default pdf. link puts a link in the body instead of an attachment and needs the report link token in it.

email_template_keystring nullable

An email template of the account, which then carries the whole message. Explicit null means no template. When a template is named, the six email fields below are rejected by name.

format'html' | 'plain_text'

Body of the email. REQUIRED when no email_template_key is named.

senderstring

Display name of the sender. REQUIRED when no email_template_key is named.

sender_emailstring

REQUIRED when no email_template_key is named. It must be the address of a user of the account, or of a domain the account already sends from.

reply_to_emailstring

REQUIRED when no email_template_key is named, under the same restriction as sender_email.

subjectstring

REQUIRED when no email_template_key is named.

bodystring

REQUIRED when no email_template_key is named.

dry_runboolean

Validate and answer what WOULD happen, without writing anything. Default false.

idempotency_keystring

Makes a retry safe: the answer of the first call is replayed for 24 hours to any later call with the same key and the same body.

confirmation_tokenstring

The token the previous call answered. Sending the same body with it performs the write.

Response

The call succeeded. This endpoint reports its errors with a real HTTP status, so a 200 always carries status=ok.

status'ok' required

Changes

No recorded changes to this operation across all 1 revision of this API.