Scheduling email
Scheduling is supported. Add send_at with an RFC3339 timestamp:
{
"from": "receipts@yourcompany.com",
"to": ["alice@example.com"],
"subject": "Your weekly summary",
"text": "Here is this week.",
"send_at": "2026-11-01T09:00:00Z"
}
The response comes back immediately with the message accepted and waiting:
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"message_id": "<d290f1ee-6c54-4b01-90e6-d701748f0851@lockally.com>",
"status": "scheduled"
}
The rules
| Format | RFC3339, for example 2026-11-01T09:00:00Z |
| Maximum | 30 days ahead |
| A past time | Not an error. The message sends now |
| Omitted or empty | Sends now |
| Counts against your allowance | At the moment you submit it, not at delivery |
A time further than 30 days out is rejected:
{
"status": 400,
"title": "Invalid send_at",
"detail": "send_at cannot be more than 30 days in the future."
}
An unparseable one is rejected the same way, with a detail naming the format.
Cancelling
While a scheduled message is still waiting, delete it:
DELETE /v1/messages/{id}
Use the id from the send response. A successful cancel returns 204 with no
body, and the message is removed outright rather than marked cancelled: it will
not appear in GET /v1/messages afterwards.
The window closes at the scheduled time, not at delivery. Once send_at
passes, the message is eligible for the worker and can no longer be cancelled,
whether or not it has actually left yet.
Two failures, and they mean different things:
| Status | Meaning |
|---|---|
409 Not cancellable |
The message exists, but it is already sending or sent. You were too late. |
404 Message not found |
No message with that id on your account, or it was cancelled already. |
Treat 409 as an ordinary race rather than a bug in your code: between reading
a message as scheduled and cancelling it, the time can simply pass.
There is no way to reschedule. Cancel and send again with a new send_at.
Why the status says scheduled when the record says queued
Worth knowing if you read the database through an export, or compare surfaces.
scheduled is a derived status, not a stored one. The row is stored as
queued with its queued_at set to the future time, because the worker drains
on status = 'queued' and the column’s check constraint has no scheduled
member. Storing scheduled would both fail the constraint and hide the row
from the worker forever.
So “scheduled” means exactly one thing: queued, with a queued_at still in
the future. Every caller-facing surface computes it the same way, from a
single shared definition.
That consistency was not always there. POST /v1/send once answered
scheduled while GET /v1/messages/{id} reported queued for the same
message, which made a scheduled send look like it had already been picked up.
Both now agree.
Checking on a scheduled message
GET /v1/messages/{id} reports scheduled until the time passes, then moves
through the ordinary states as the worker handles it:
scheduled -> queued -> sending -> delivered
There is no sent status. See Message IDs and
tracking for the full set, including
the two outcomes that are neither delivered nor bounced.