Scheduled sending

Scheduling a send

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "news@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Your weekly digest",
    "html": "<p>Here is what happened this week...</p>",
    "category": "marketing",
    "scheduled_at": "2026-07-30T09:00:00Z"
  }'

{
  "id": "em_01ky7q24hafjgvzfg02v3m177p",
  "status": "scheduled",
  "scheduled_at": "2026-07-30T09:00:00Z",
  "category": "marketing"
}

Choosing the send time

• It must be between 30 seconds and 30 days in the future. Earlier than 30 seconds from now, or further out than 30 days, is rejected with a 422. The 30-second floor keeps a "schedule" from racing an immediate send; the 30-day ceiling is the maximum horizon.
• It is an exact instant, not a wall-clock time in some timezone. Include a UTC Z (2026-07-30T09:00:00Z) or an explicit offset (2026-07-30T09:00:00-04:00, which is the same instant as 13:00:00Z). Bird compares the instant against the current time; it does not interpret a bare local time or apply a recipient's timezone. To send at "9am in each recipient's local time," compute that instant yourself and schedule one send per timezone.

Viewing scheduled messages

curl "https://us1.platform.bird.com/v1/email/messages?status=scheduled" \
  -H "Authorization: Bearer bk_us1_..."

Canceling a scheduled send

curl -X POST https://us1.platform.bird.com/v1/email/messages/em_01ky7q24hafjgvzfg02v3m177p/cancel \
  -H "Authorization: Bearer bk_us1_..."

• Only a still-scheduled message can be canceled. If the message has already started sending, already sent, or was already canceled, the call returns 409:
  Exemple de code

  {
    "error": {
      "type": "conflict_error",
      "code": "E10005",
      "name": "EmailNotCancelable",
      "message": "This message cannot be canceled. Only scheduled messages that have not started sending can be canceled."
    }
  }

  As the send time arrives, a cancel can also lose the race to the send itself and come back 409: the message was already on its way.
• A large send takes a few seconds to become cancelable. A scheduled send with attachments or a large body is still being stored for a few seconds after the 202, and a cancel in that window returns 409 while the message stays scheduled. If you cancel immediately after scheduling and get a 409, read the message back: if it still shows status: scheduled, retry the cancel.
• Canceling does not refund the scheduled-email allowance. The unit you consumed at schedule time stays consumed, which stops a schedule-then-cancel loop from working around the allowance. Your regular send allowance is untouched, because it is only charged when a message actually sends.
• Cancel is safe to retry with an Idempotency-Key like any other write.

What stays the same, and what happens at send time

• Field and domain validation are up front. Payload validation and the sender-domain check run when you call the API, so a malformed scheduled send fails immediately with a 422; you find out now, not at 9am.
• The sender domain is re-checked at send time. If your from domain is no longer verified when the scheduled time arrives, the message is not sent: its recipients come back rejected with a reason, rather than going out from an unverified domain. Keep the domain verified for the whole window between scheduling and sending.
• Your send allowance is charged at send time. The regular send quota is consumed when the message fires, not when you schedule it, and a quota exhausted at fire time rejects the recipients rather than sending.
• Suppression is evaluated at send time, against your suppression list as it stands then, so a recipient who unsubscribes between scheduling and sending is still honored.
• Category, tags, and metadata are unchanged, and are echoed on the scheduled send's webhook events exactly as on an immediate send.

Limits and constraints

Errors

Webhooks

• email.scheduled fires when a message is accepted with a future scheduled_at, and carries the scheduled_at time.
• email.canceled fires when a scheduled message is canceled before it sends.

Next steps

• Sending email: the full send payload and the async 202 model
• Suppressions: who Bird won't deliver to, and why, evaluated at send time
• Events and webhooks: the delivery pipeline a scheduled message enters when it fires
• Idempotency: safe retries for the schedule and cancel calls
• API reference: the cancel endpoint's full contract