Scheduling a transactional e-mail with send_at, and cancelling it before it goes out

E-mail·· 84 views· 3 min read

The short answer: add the send_at field to the request, with the date and time in ISO 8601 including the time zone, up to 30 days ahead. Credits are only taken when the e-mail goes out. To change your mind, call POST /v1/email/messages/{id}/cancel before that time.

When scheduling makes sense

Situation Example
A reminder before a deadline The invoice is due on Friday: schedule the reminder for Wednesday morning
Out of hours An order placed at midnight: the confirmation goes at once, but the satisfaction survey can wait until the next day
A set date The notice that a plan ends, the day before

How to write the date

Use ISO 8601 with the time zone at the end, as in the documentation example: 2026-11-20T09:30:00+02:00. The +02:00 is the zone of that example; use your customer’s. Without the zone, the time is ambiguous.

"send_at": "2026-11-20T09:30:00+02:00"

Error reason What to fix
invalid_send_at The date is not ISO 8601 with a time zone
send_at_in_past The date has passed. To send now, leave out send_at
send_at_too_far The date is too far ahead: the most is 30 days

Cancelling

1 Keep the id from the answer to the scheduled send.
2 Before the time, call POST /v1/email/messages/{id}/cancel, or click Cancel the send in the history on the page.
3 The status becomes cancelled and you do not pay for that e-mail.

Only scheduled e-mails that have not gone out can be cancelled. After that, the API answers 409 with the reason not_cancellable.

The balance is checked again when it is time to send. If there are not enough credits then, the e-mail does not go out and becomes failed, with the error insufficient_credits. Credits held for scheduled e-mails show in scheduled_credits, in GET /v1/email/balance.
Cancel when the reason goes away. If the customer pays before the reminder, your system cancels the scheduled reminder. Nobody likes a payment reminder after paying.

Want to automate e-mail reminders at the right time? See the API page.

See the API page

SEE ALSO

Sending a transactional e-mail through the API: the fields of POST /v1/email/messages

Sending transactional e-mails in a batch: one request, many messages and the result of each

Transactional e-mail statuses: sent, delivered, bounced, complained and failed explained

Email Center credits and the daily limit: what a credit pays for and when it comes back

Password reset, order and invoice e-mails: what a good transactional message says, with examples

Transactional e-mail templates with variables: write once, fill in each customer's details

RECOMMENDED PRODUCT

Professional e-mail on your domain

Mailboxes in your company name, no adverts, with spam filtering. from KSh858.00/mo (3-year plan, with coupon)

See plans
Was this answer helpful? Your answer helps us improve this article.

Related Articles

E-mail 2,781 How to access your webmail You don't need to install anything to check your e-mail - the webmail works straight from your browser, on any device. A...
E-mail 2,518 How to set up your e-mail on Android Set your e-mail up once on Android and it keeps syncing in the background, on Wi-Fi or mobile data. Setting it up 1 Open...
E-mail 2,058 How to set up your e-mail on iPhone or iPad The Mail app on iPhone and iPad can hold your professional e-mail alongside any personal accounts, each syncing independ...
E-mail 2,419 How to set up your e-mail in Thunderbird Thunderbird can detect this server's settings automatically - you only need to type your name, e-mail and password. Auto...
E-mail 1,580 How to set up your e-mail in the new Outlook for Windows The new Outlook for Windows tries to configure itself automatically. If it can't, it falls back to the same manual setti...
E-mail 55 Sending transactional e-mails in a batch: one request, many messages and the result of each The short answer: POST /v1/email/messages/batch sends many e-mails in one request. Fields outside messages apply to all...