Scheduling

Set scheduledAt to an ISO 8601 date-time with a time zone offset. The response has status: "scheduled" instead of queued.

const { id, status } = await flaresend.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  subject: 'Your trial ends tomorrow',
  text: 'Upgrade any time from your account page.',
  scheduledAt: '2026-10-01T09:00:00Z',
});
// status === 'scheduled'

RulesCopy Anchor Link

• The time must have an offset: 2026-10-01T09:00:00Z or 2026-10-01T11:00:00+02:00. A time without one fails validation.
• It must be in the future and at most 30 days ahead. Otherwise the request fails with 400 invalid_schedule.
• All other checks (sender, recipients, suppressions, template, size, limits) run when you make the request, not when the email is sent. A request that succeeds is stored with its body, ready to go.
• The daily limit counts the email on the day you schedule it.

How it is sentCopy Anchor Link

• Emails due within 12 hours go on the send queue straight away, with a delay until scheduledAt.
• Emails due later wait in D1. A cron job runs every 5 minutes and queues any scheduled email due in the next 12 hours.

So an email goes out at scheduledAt, give or take the queue's own timing. It is not sent early.

CancelCopy Anchor Link

Only an email with status scheduled can be canceled.

await flaresend.emails.cancel(id);
// { id, status: 'canceled' }

Canceling sets the email and its recipients to canceled and adds an email.canceled event, which webhooks can subscribe to. Canceling any other status fails with 409 not_cancelable. If the queue picked the email up at the same moment, the cancel loses and also fails with 409 not_cancelable ("the email is already being sent").

RescheduleCopy Anchor Link

Move a scheduled email with PATCH /v1/emails/:id:

await flaresend.emails.reschedule(id, '2026-10-02T09:00:00Z');

The new time follows the same rules (future, at most 30 days ahead). It works on scheduled emails only; anything else fails with 409 not_cancelable. The response is the updated email record. Rescheduling adds another email.scheduled event with rescheduled: true in its data. The RPC client has no reschedule method.

EventsCopy Anchor Link

A scheduled email starts with an email.scheduled timeline event (with scheduledAt in its data) instead of email.queued. No email.queued webhook is sent for it. Once it is sent, the usual email.sent, email.delivered and so on follow. See Statuses and events.

Test keysCopy Anchor Link

With an fs_test_ key, scheduledAt is still validated, but the email is stored with status test and never sent or scheduled. See Test mode.