Scheduled messages

A scheduled message is stored until its time comes, then sent by a worker that runs every five minutes. That storage is what makes it cancellable — and what makes it visible in the dashboard beside messages a person scheduled there.

One queue, two ways in. A key with Scheduled → Read sees everything queued under your organization, including messages someone scheduled in the web app. Each row’s scheduled_by says which.

Private mailboxes cannot schedule. Queuing means storing the message body until the clock comes round, and a Private mailbox’s guarantee is that the plaintext never rests anywhere Ruber can read. Encrypting it at schedule time would only move the problem — the worker would then need the key to send it.from must be a Smart mailbox. This is a permanent design decision, not a missing feature.

List scheduled messages

GET https://app.ruber.me/api/v1/scheduled

Required permission: Scheduled → Read (scheduled:read) Takes no parameters. Returns everything queued, sending, or failed for your organization, soonest first, up to 200.

curl https://app.ruber.me/api/v1/scheduled \
  -H "Authorization: Bearer rk_your_key_here"

{
  "data": [
    {
      "id": "9f2c1e40-9d7a-4b3e-8c11-0a2f6b7d9e10",
      "from": "you@yourdomain.com",
      "to": ["customer@example.com"],
      "cc": [],
      "bcc": [],
      "subject": "Following up",
      "send_at": "2026-09-09T09:00:00.000Z",
      "status": "pending",
      "last_error": null,
      "attachment_count": 0,
      "scheduled_by": "api_key",
      "created_at": "2026-09-07T14:02:11.000Z"
    }
  ]
}

`status`	Meaning
`pending`	Waiting for its time. Cancellable.
`sending`	The worker has claimed it. No longer cancellable.
`failed`	Gave up after three attempts. `last_error` says why.

Delivered messages leave this list — look in the Sent folder with GET /v1/messages?folder=sent.

Schedule a message

POST https://app.ruber.me/api/v1/scheduled

Required permission: Scheduled → Write (scheduled:write) The same body as sending, plus send_at.

curl -X POST https://app.ruber.me/api/v1/scheduled \
  -H "Authorization: Bearer rk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": ["customer@example.com"],
    "subject": "Following up",
    "text": "Just checking in on the quote.",
    "send_at": "2026-09-09T09:00:00Z"
  }'

Field	Type
`send_at`	string	required. RFC 3339. Now to one month ahead.
`from`	string	required. A Smart mailbox you own.
`to`	array or string	required. Up to 25 recipients.
`cc`, `bcc`	array or string	Up to 25 each.
`subject`, `text`, `html`	string	As for sending.
`in_reply_to`, `references`	string, array	Threading.
`attachments`	array	Up to 10, 8 MB total. Stored until the send.

{
  "id": "9f2c1e40-9d7a-4b3e-8c11-0a2f6b7d9e10",
  "send_at": "2026-09-09T09:00:00.000Z",
  "status": "pending"
}

201 Created. Keep the id — it is the only way to cancel.

Sending happens within about five minutes of send_at, not to the second. The worker runs on a five-minute cycle. Nobody schedules mail for 09:00 meaning 09:00:00, and running every minute would be twelve times the work to move the worst case from five minutes late to one.Your plan’s daily allowance is claimed when the message sends, not when you schedule it — so a message queued today against tomorrow’s quota is charged tomorrow. A scheduled message can therefore fail on allowance if the day it lands on is already full.

The one-month window

send_at must be between now and one month ahead. Anything earlier is rejected as That time has already passed, anything later as Messages can be scheduled up to a month ahead. There is a minute of slack on the floor so a request that takes a moment to arrive is not refused for it.

Cancel a scheduled message

DELETE https://app.ruber.me/api/v1/scheduled/{id}

Required permission: Scheduled → Write (scheduled:write)

curl -X DELETE https://app.ruber.me/api/v1/scheduled/9f2c1e40-9d7a-4b3e-8c11-0a2f6b7d9e10 \
  -H "Authorization: Bearer rk_your_key_here"

{ "cancelled": true, "id": "9f2c1e40-9d7a-4b3e-8c11-0a2f6b7d9e10" }

Only a pending message can be cancelled. Once the worker has claimed it the status is sending and the message may already be in the mail server’s hands — there is no un-sending it, so the call is refused rather than reporting a success you would act on.

Cancelling through the API deletes the message. The body and any attachments are removed from storage.This differs from cancelling in the web app, which returns the message to Drafts — someone who cancels at nine in the morning meant “not yet”, and there is a Drafts folder in front of them to put it in. An API caller has no drafts view, so cancel means cancel. Keep your own copy if you need one.

Errors

Code	HTTP	Cause
`invalid_request`	`400`	Malformed JSON, a bad address, a `send_at` outside the window, attachments over 8 MB, `from` is a Private mailbox, or the message is no longer `pending`.
`unauthorized`	`401`	Missing, malformed, unknown or revoked key.
`forbidden`	`403`	The key lacks `scheduled:read` or `scheduled:write`.
`not_found`	`404`	No scheduled message with that id — or it is not yours.
`rate_limited`	`429`	Over 600 requests in a minute.
`internal_error`	`500`	Storage was unreachable. Nothing was queued.

See Errors for the full response shape.

Start here

Using Ruber

API

Reference

Scheduled messages

List scheduled messages

Schedule a message

The one-month window

Cancel a scheduled message

Errors

​List scheduled messages

​Schedule a message

​The one-month window

​Cancel a scheduled message

​Errors

List scheduled messages

Schedule a message

The one-month window

Cancel a scheduled message

Errors