Skip to content
Mail
Docs

Scheduling

Give an email a scheduled_at and it waits in the queue until then. Until it goes, you can move it or cancel it.

Send later

Add scheduled_at to POST /emails, or to any email of a batch: an ISO 8601 date and time with its zone (Z or +01:00), at most 72 hours ahead. A time already past sends it straight away.

{
  "from": "Acme <reminders@acme.ng>",
  "to": [
    "ada@example.com"
  ],
  "subject": "Your appointment is tomorrow",
  "text": "See you at 10:00.",
  "scheduled_at": "2026-10-07T09:00:00+01:00"
}

The answer is its id, as for any email; its status is queued until our sender takes it at that time. Everything is checked twice: when you queue it, and again when it goes — the domain still verified, the key not revoked, the account not paused, no recipient suppressed. If something changed, it is not sent, and its status says why.

It counts against your caps on the day it is to go (Lagos time), and is refused with 429 quota_exceeded if that day is already full — however many days ahead you queue it.

Move it

PATCH /emails/{id} with a new scheduled_at, with a full-access key. The answer is the email’s id, status and new time.

curl -X PATCH https://emails.mydomainshub.com/api/v1/emails/6f1d3a52-2a0e-4f0b-9d55-0c1f2a3b4c5d \
  -H "Authorization: Bearer $MDH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "2026-10-07T11:00:00+01:00"}'

Its recipients move to the new time’s day. If that day is full, the move is refused with 429 quota_exceeded and the email keeps its old time.

Cancel it

POST /emails/{id}/cancel, with a full-access key. Its recipients are given back to your caps and its body is deleted at once. Cancelling it again answers the same.

curl -X POST https://emails.mydomainshub.com/api/v1/emails/6f1d3a52-2a0e-4f0b-9d55-0c1f2a3b4c5d/cancel \
  -H "Authorization: Bearer $MDH_API_KEY"

Until when

You can move or cancel an email while it waits in the queue — scheduled, or not yet picked up. Once our sender has tried it, it may already be on its way, so both answer 409 with the email’s status. An email sent without scheduled_at is picked up soon after it is queued, so in practice it is scheduled emails you cancel.

The Emails log shows each scheduled email and when it is due.