Schedule a message

Check environment and feature availability before following this guide.

A scheduled message is a template send that happens later. You give the API a template, the data for its placeholders, one destination and a time; the evaluator sends it when the time comes. Creating and changing scheduled messages needs the scheduled:write scope, reading needs scheduled:read. Both are available to members and up. Credits are spent when the send happens, not when you schedule it. A scheduled send costs 2 credits.

Schedule one

curl -X POST https://api.lithoblocks.com/v1/scheduled-messages \
  -H "Authorization: Bearer $LITHOBLOCKS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reminder-2026-09-14-standup" \
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "data": { "date": "Monday 14 Sep", "updates": [{ "who": "Pat", "doing": "Billing migration" }] },
    "destination": { "channel_id": "C0AS92CQ04D" },
    "schedule": { "send_at": "2026-09-14T09:00:00+02:00", "timezone": "Europe/Brussels" }
  }'

Field	Required	Meaning
`template_id`	yes	A template in your organization. The send renders the template as it is at send time.
`data`	yes	Values for the template’s placeholders, the same object a direct send takes.
`destination`	yes	Exactly one of `channel_id`, `recipient_email` or `recipient_slack_id`.
`schedule.send_at`	yes	The earliest send time, ISO 8601 with an offset (`2026-09-14T09:00:00+02:00` or `…T07:00:00Z`).
`schedule.timezone`	no	An IANA zone such as `Europe/Brussels`. Used by time-window conditions that do not name their own.
`recurrence`	no	Repeat the message; see Recurring messages.
`delivery_conditions`	no	Hold the message until conditions allow; see Delivery conditions.

The response is 201 with the scheduled message:

{
  "id": "0f3c…",
  "status": "scheduled",
  "template_id": "6b1e…",
  "template_version_id": "9a2d…",
  "queue_policy_id": null,
  "destination": { "channel_id": "C0AS92CQ04D" },
  "data": { "date": "Monday 14 Sep", "updates": [{ "who": "Pat", "doing": "Billing migration" }] },
  "schedule": { "send_at": "2026-09-14T07:00:00.000Z", "timezone": "Europe/Brussels" },
  "recurrence": null,
  "repeat_count": 0,
  "delivery_conditions": null,
  "max_delay_at": null,
  "source": "api",
  "error_message": null,
  "created_at": "2026-09-06T10:12:44.318Z",
  "processed_at": null
}

send_at comes back normalised to UTC. template_version_id records the version that was live when you scheduled, and it is the version that sends: activating a newer version later does not change a message already scheduled, including recurring ones. queue_policy_id is only set on messages created through the older policy-driven path and is null for anything you create here.

Following the live version instead

Pass "follow_live": true when you schedule, and the message is not pinned: it sends whichever version of the template is live at send time, and each recurrence does the same. template_version_id comes back null. To change an existing message, PATCH /v1/scheduled-messages/{id} with "follow_live": true to unpin it, or "follow_live": false to pin it to the version live now. Pinning a template that has no live version answers 409 with template_not_activated. Leaving follow_live out never changes the pin.

Retrying safely

Send an Idempotency-Key header with any unique string. Repeating the request with the same key and body within 24 hours replays the original response, marked Idempotency-Replayed: true, instead of scheduling a second message. The same key with a different body answers 409.

What can go wrong

Status	`code`	Why
`404`		No template with that id in your organization.
`422`		The body does not validate: a missing field, two destinations, a `send_at` without an offset, a presence condition.
`400`	`invalid_data`	The database refused the row; `details` carries the reason.
`403`	`tier_limit`	The organization’s tier does not include scheduling; the message names the tier.

Lifecycle

Status	Meaning
`scheduled`	Waiting for `send_at`, or for its delivery conditions. The only status you can change.
`processing`	The evaluator has picked it up and is sending.
`sent`	Delivered; `processed_at` is when.
`failed`	The send did not happen; `error_message` says why, for example `insufficient_credits` or `no_slack_connection`.
`cancelled`	You cancelled it before it was sent.
`expired`	Its conditions were still unmet at `max_delay_at` and `on_miss` was `expire`.

The last four are terminal. Delivery is checked on a roughly minute-based cadence; load, conditions, and service availability can delay it. The due time is not a guaranteed delivery deadline.

Manage it

Do	Call
List	`GET /v1/scheduled-messages`, soonest first; `?status=` and `?template_id=` filter, `limit` and `offset` page
Read one	`GET /v1/scheduled-messages/{id}`
Reschedule or edit	`PATCH /v1/scheduled-messages/{id}`
Cancel	`DELETE /v1/scheduled-messages/{id}`
Send now	`POST /v1/scheduled-messages/{id}/send-now`

All three changes are only possible while the status is scheduled. Afterwards the API answers 409 with code: "invalid_state" and the current status in details.

Reschedule

PATCH takes any of data, destination, schedule, recurrence and delivery_conditions; send only what changes. recurrence: null removes the recurrence and delivery_conditions: null removes the conditions. The deadline max_delay_at is recomputed from the new send_at and conditions.

curl -X PATCH https://api.lithoblocks.com/v1/scheduled-messages/{id} \
  -H "Authorization: Bearer $LITHOBLOCKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "schedule": { "send_at": "2026-09-15T09:00:00+02:00" } }'

Cancel

DELETE is a soft cancel: the row stays, with status: "cancelled", and the response is the message. Cancelling a recurring message stops the later occurrences too.

Send now

send-now makes the message due immediately and removes its delivery conditions; the evaluator attempts it on a subsequent tick. The response is 202 with the message, still scheduled until that tick.

See what happened

Every attempt the evaluator made appears in GET /v1/queue-executions, filterable by scheduled_message_id. A scheduled_send with result: "success" is the delivery; a constraint_check with result: "deferred" is a tick where the conditions held the message back, with the reasons in error_message.

In the web app

The Scheduled page at /scheduled lists your organization’s scheduled messages with a status filter, shows each one’s destination, recurrence and conditions, and offers reschedule (a new time and zone), cancel and send now for anything still scheduled. It also shows the create request above as a copy-paste curl. Creating a scheduled message is an API call; the page manages what the API created. Manage in the app · Execution logs

Send and interact

Manage sent messages (preview)

Collect form input

Schedule and batch (preview)

Schedule one

Following the live version instead

Retrying safely

What can go wrong

Lifecycle

Manage it

Reschedule

Cancel

Send now

See what happened

In the web app

​Schedule one

​Following the live version instead

​Retrying safely

​What can go wrong

​Lifecycle

​Manage it

​Reschedule

​Cancel

​Send now

​See what happened

​In the web app

Schedule one

Following the live version instead

Retrying safely

What can go wrong

Lifecycle

Manage it

Reschedule

Cancel

Send now

See what happened

In the web app