Skip to main content

Scheduling

Add scheduled_at to any send and we hold the message until then.

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Your appointment is tomorrow",
  "html": "<p>See you at 10.</p>",
  "scheduled_at": "2026-08-20T09:00:00Z"
}

The response has status: "scheduled" and the id you use to change or cancel it.

The 72 hour ceiling​

scheduled_at must be in the future and no more than 72 hours ahead. Outside that range is invalid_schedule.

The limit is deliberate. A message scheduled weeks ahead is a message whose content, recipient and reason for sending have all had weeks to become wrong, and neither of us can tell whether it should still go. For anything further out, keep it in your own system and submit it closer to the time. You keep the ability to change your mind.

Use UTC​

scheduled_at is RFC 3339 and we recommend sending UTC. If you send an offset we honour it, but the failure mode is silent: a server whose timezone differs from the one you developed against will schedule for a different moment, and nothing about the response reveals it.

Reschedule​

curl -X PATCH https://api.epostix.com/v1/emails/{id} \
  -H "Authorization: Bearer $EPOSTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "2026-08-20T11:00:00Z"}'

Only before it sends. After that you get email_not_cancellable, which is the same answer you get for trying to cancel a message that has already gone.

Cancel​

curl -X POST https://api.epostix.com/v1/emails/{id}/cancel \
  -H "Authorization: Bearer $EPOSTIX_API_KEY"

A scheduled message is not a reservation​

Sending quota is consumed when the message is sent, not when it is scheduled. Scheduling a thousand messages does not reserve a thousand, so a schedule can still meet daily_quota_exceeded when it fires.

Pair it with idempotency​

The usual reason to schedule is a job that may run more than once. Give it an idempotency key derived from what you are reacting to, and a redelivered job reschedules nothing rather than queueing a second copy.