Skip to main content
If your backend already knows when an email must go out, you can skip the rules and schedule a single send with sendAt.

Schedule an email

Add sendAt to POST /public/v1/transactionals or POST /public/v1/templates/email/send (scope transactional):
The answer is HTTP 201 with status: 202 inside (scheduled, not sent):
  • transactional: the template uid (7 characters). Send the master: the tenant’s copy is picked when the email goes out.
  • sendAt: ISO 8601 with its UTC offset, in the future, at most 90 days ahead (422 INVALID_SEND_AT otherwise, with a userMessage that says what is wrong). Without sendAt nothing changes: the email goes now and the response is the usual one.
  • Checked now: the template exists, tenant, replyTo, the sender (from/senderId under a verified domain). Checked again when it goes out, like any send: the tenant’s version of the template (picked at that moment), the sender, bounces, marketing consent (marketing templates only: a utility email is never blocked by consent) and the tenant’s sending limits.
  • idempotencyKey: the same key again returns the send already scheduled (duplicate: true), nothing new is planned. On /templates/email/send it is a UUID.
  • Goes out once, at most a minute late; more than 5 minutes late (e.g. an outage) it is skipped, never sent late.
  • Never for sign-in, verification or system emails and never with a one-time code or sign-in link in the fields (422 SEND_AT_NOT_ALLOWED). On /templates/email/send it schedules the template content: no html, subject, text or attachments.
Send the DELETE calls without a body and without a Content-Type: application/json header (an empty JSON body is refused with 400). These sends are separate from the rules: a booking.cancelled event does not cancel them and /public/v1/scheduled-sends does not list them.

Move a scheduled email

There is no “move” call. Cancel the email, then schedule it again with the new sendAt and a new idempotencyKey (the old key still points to the cancelled email, so reusing it returns that one):
With the rules you do not need this: a booking.updated event moves the pending emails for you.

If something fails

422 INVALID_SEND_AT (no UTC offset, in the past, or more than 90 days ahead), 422 SEND_AT_NOT_ALLOWED (sign-in or one-time-code emails), 409 SCHEDULED_SEND_NOT_CANCELLABLE (already sending or sent). Every code: Errors and limits. Reference: Send Transactional Email.

Next step

Senders and domains