Schedule a message
Add scheduled_at to a send, or to any message of a batch: an ISO 8601 date and time with its offset or Z, within the next 30 days.
The answer is 202 with the status scheduled, in the extended shape:
(Shortened: the answer carries every field of a send’s answer.)
- Dates are exact:
2026-10-22T09:00:00+03:00 or 2026-10-22T06:00:00Z. Words such as “tomorrow at 9” are not read; compute the time on your side.
- Within the next minute the message is sent now (
accepted, scheduled_at kept). More than a minute in the past, or more than 30 days ahead, is refused with 400 invalid_request.
- Charged when you call, at the price and against the free e-mails of that moment, so a balance that runs low shows at once.
- The daily limit of its day: the message counts on the Riyadh day it is due, not the day you scheduled it.
- No attachments: only the body waits, kept encrypted until it is sent. A scheduled message with
attachments is refused (`attachments` cannot be sent with `scheduled_at`).
- Not over SMTP: the SMTP relay sends at once.
Reschedule
PATCH /v1/email/messages/{id} with the new scheduled_at, the only field a message can change:
It answers 200 with the message as it stands. The new day’s limit applies, and a time within the next minute sends it now. Only a scheduled message can move: once it is on its way the answer is 409 message_not_scheduled with its status. Rescheduling takes email:send; another application’s id answers 404 not_found.
Cancel
POST /v1/email/messages/{id}/cancel cancels a scheduled message before its time:
It answers 200 with the message canceled (its recipients too) and canceled_at set. Its price is refunded to your balance, and a free e-mail goes back to the month’s allowance when it is the same month. Only a scheduled message can be canceled: a message already on its way answers 409 message_not_scheduled. No webhook announces a cancel. The console’s Email → Messages can cancel a scheduled message too.Last modified on October 20, 2026
