scheduled_at timestamp to a normal send and mailkube stores the message and transmits it at that instant. You can list, retrieve, reschedule, and cancel scheduled emails any time before they go out, one at a time or a whole batch at once. Scheduling is a REST API feature with no SMTP equivalent; an SMTP submission always transmits right away.
Scheduled sending is a paid plan feature, available on Launch and above. A send that carries
scheduled_at on a plan without the entitlement is rejected with scheduling_not_included (403).The gate sits on the send. Listing, retrieving, rescheduling and canceling are not gated, so a plan change never strands the sends you already have in the queue.Schedule a send
Scheduling reuses the send endpoint. Addscheduled_at (and optionally batch_id) to any send request:
202 Accepted with a scheduled_email acknowledgment:
id is the platform message UUID. It is the handle for every operation below, and the email_id carried by this message’s webhook events.
Quota is charged and the body is rendered once, at schedule time, not when the message finally sends. Everything time-sensitive (suppression, topic opt-out) is re-checked fresh at send time. A recipient who unsubscribes in the interim is not mailed.
The scheduled_at rule
scheduled_at is a full ISO-8601 timestamp with a timezone offset:
- Any offset is accepted (
+02:00,-05:00,Z) and normalized to UTC; responses always echo UTC (Z). - Offset-less (naive) values are rejected.
2026-08-20T09:00:00with no zone is ambiguous and returns avalidation_error. - It must be strictly in the future and no more than 30 days ahead. The 30-day horizon is the same on every plan; no tier extends it.
Grouping with batch_id
An optional batch_id (up to 64 characters) labels a scheduled send so you can cancel or reschedule a whole campaign in one call. It is only valid alongside scheduled_at; sending it on an immediate send is a validation_error.
batch_id is a grouping label, not a multi-send endpoint. Each send is still its own POST /emails request; the label lets the batch operations below address them together.Status vocabulary
A scheduled email moves through four states:A scheduled email’s lifecycle ends at
sent. The delivery outcome (delivered, bounced, opened, clicked) lives on your logs and webhooks, correlated by the same id. Retrieving a scheduled email never turns into a delivery report.Retrieve one
GET /scheduled-emails/{id} returns the full object. The rendered body is never included.
recipients is a short summary: the first recipient, then +N when more follow (for example [email protected] +2). The full address list stays server-side. An unknown or other-tenant id returns scheduled_email_not_found (404), identically either way, so ownership is never disclosed.
List and filter
GET /scheduled-emails lists your scheduled emails with page-number pagination. Every filter is optional; status may be repeated. The list returns only pending, canceled, and failed emails within a rolling 31-day window around now (scheduled_at in [now-31d, now+31d]). Once an email is sent it leaves this collection and appears in your delivery logs and webhooks.
status (scheduled, canceled, or failed), batch_id, scheduled_at_gte / scheduled_at_lte (ISO-8601 with a timezone offset), and page. steps.next and steps.previous are omitted (not null) at the ends of the range.
Every filter is checked before the request is processed, and an invalid one returns validation_error (422). That means status=sent is rejected: a sent email has left this collection, so filtering for it could only ever return nothing. Date bounds must carry a timezone offset (2026-08-20T07:00:00Z, not 2026-08-20). A bound outside the 31-day window in the direction that can never match is rejected too: scheduled_at_gte later than now+31d, or scheduled_at_lte earlier than now-31d. A bound that is merely wider than the window is clipped, so scheduled_at_gte=2020-01-01T00:00:00Z behaves as no lower bound at all. Query parameters this endpoint does not define are ignored.
Reschedule
PATCH /scheduled-emails/{id} changes a scheduled email’s scheduled_at (and optionally batch_id). Content is immutable. No message field can be changed; to change the content, cancel and schedule a new send.
scheduled_at. The new time follows the same rule (tz-aware, future, within 30 days). Only a scheduled email can be rescheduled; an already sent or canceled one returns scheduled_email_not_pending (422).
Cancel
DELETE /scheduled-emails/{id} cancels a scheduled email before it sends. This is a soft delete. The status flips to canceled and the record survives; the message is never transmitted.
scheduled email cancels; an already-sent one returns scheduled_email_not_pending (422), and an unknown id returns scheduled_email_not_found (404).
Batch operations
Act on every still-scheduled member of a batch_id at once. Already-sent or already-canceled members are skipped, and the count reflects the rows actually changed. An unknown batch is a no-op (count 0), not a 404. A batch_id that is empty or longer than 64 characters could never have been stored in the first place, and returns validation_error (422). On a batch reschedule the batch is taken from the URL; a batch_id in the request body is ignored.
Cancel a batch with DELETE /scheduled-emails/batches/{batch_id}:
PATCH /scheduled-emails/batches/{batch_id} with { "scheduled_at": "2026-08-22T09:00:00+02:00" }:
Related events
Subscribe a webhook to follow a scheduled send:email.scheduledfires when the send is accepted for later.email.sentfires when the message is handed off for delivery.email.failedfires if a send-time re-check or the transport drops it. A drop is never silent.
Rate limits
The management endpoints are throttled per API key, separately from the send limit; see Rate limits. Scheduling itself (viaPOST /emails) rides the standard send limit.
Related
- Sending your first email shapes the request that carries
scheduled_at. - Webhooks delivers the
email.scheduled,email.sentandemail.failedevents a scheduled send produces. - Plans & limits lists which plans include scheduled sending.