Schedules

Change a scheduled delivery

Changes a scheduled delivery. The update is partial -- only the fields the body carries are laid over the stored row -- and the result is validated as a whole, so a change that would leave an incomplete row is refused. Two rows cannot be updated at all and answer 409: one whose delivery depends on a condition (NOT_EDITABLE_BY_API) and one built from the system email template (SCHEDULE_USES_SYSTEM_TEMPLATE); a schedule created from the client portal is refused the same way. The confirmation is CONDITIONAL: it is asked for only when the body touches the recipients, the frequency, the day of the week or of the month, the hour, the attachment format, the email template, the body format or any of the six email fields -- that is, everything except report_key. if_version is not accepted. Refusals: 400 VALIDATION_FAILED, UNKNOWN_PARAM or INVALID_VALUE, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND, 409 NOT_EDITABLE_BY_API, SCHEDULE_USES_SYSTEM_TEMPLATE, SCHEDULE_QUEUED or ACCOUNT_HAS_NO_OWNER plus the confirmation and idempotency conflicts. It does NOT spend the daily email budget, so it never answers EMAIL_QUOTA_REACHED. The same two warnings a creation can carry apply here.

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

post/schedules/update

Request

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

Request body

schedule_keystring required

The schedule to change, from /v1/schedules/list.

report_keystring

The report of the schedule. Optional, and when sent it must be the one the schedule already delivers; it cannot be moved to another report and cannot be null.

frequency'daily' | 'weekly' | 'monthly'

How often to deliver it. An update cannot send a report once (now belongs to /v1/schedules/create) and cannot stop a delivery (none belongs to /v1/schedules/delete).

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.

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. 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.