Scheduling

Send a notification later with sendAt or delay, and cancel it before it goes out.

Add sendAt or delay to a normal send and Push holds the notification until then. Either one must be 10 seconds to 3 days (259,200 seconds) ahead.

The two fields#

Field	Value
sendAt	An ISO 8601 date and time with a zone, like `2026-10-05T18:00:00Z` or `2026-10-05T21:00:00+03:00`.
delay	Whole seconds from now, 10 to 259,200.

{  "recipient": "ops",  "title": "Standup in 10 minutes",  "sendAt": "2026-10-05T18:00:00Z"}

Send one or the other. Both together, a time without a zone or a value out of range fails with 400 VALIDATION_ERROR.
The recipient needs at least one connected browser when you schedule, or the request fails with 422 INVALID_RECIPIENT.
ttl counts from the release time, not from the request.

The response#

A scheduled send answers 202 Accepted with status: "scheduled", the release time in sendAt, and attempts: 0, because no attempt exists yet:

⫻

202 Accepted

HTTP/1.1 202 AcceptedContent-Type: application/jsonX-Request-Id: req_0199b1c27a4e7c3d9f1e2b6a8d4c5e11
{  "id": "0199b1c2-7a4e-7c3d-9f1e-2b6a8d4c5e10",  "status": "scheduled",  "attempts": 0,  "mode": "live",  "sendAt": "2026-10-05T18:00:00.000Z"}

At release time#

Push plans the notification with the browsers and delivery policy the recipient has at that moment, so browsers connected after scheduling are included.
The attempts are created and counted toward usage then, not when you scheduled.
The notification's state changes from scheduled to sent, and its attempts start like any other send.
If a release is ever missed, the hourly cleanup releases any notification more than a minute past its sendAt.

Notification states#

state	Meaning
scheduled	Waiting for its `sendAt`. It can still be cancelled.
sent	Released, or sent at once. Its attempts carry their own statuses.
cancelled	Cancelled before release. Nothing was sent or charged.
dropped	Push could not release it: the recipient had no connected browsers left (`no_browsers`), or the free allowance and credits could not cover it (`quota_exceeded`). Nothing was sent or charged. The dashboard shows the reason.

Cancelling#

Cancel a scheduled notification with DELETE /v1/notifications/{id} and an API key from the same project:

⫻

curl

curl -X DELETE https://api.meslzy.com/push/v1/notifications/0199b1c2-7a4e-7c3d-9f1e-2b6a8d4c5e10 \  -H "Authorization: Bearer $PUSH_API_KEY"

⫻

200 OK

HTTP/1.1 200 OKContent-Type: application/jsonX-Request-Id: req_0199b1c27a4e7c3d9f1e2b6a8d4c5e11
{  "id": "0199b1c2-7a4e-7c3d-9f1e-2b6a8d4c5e10",  "state": "cancelled"}

Code	HTTP	When
NOT_SCHEDULED	409	The notification is not `scheduled` any more: it was released, cancelled or dropped.
NOT_FOUND	404	No notification with this id in the key's project.

Good to know#

An Idempotency-Key works the same for scheduled sends; a replay returns the scheduled result.
A scheduled test-key send is released like any other, and its attempts are recorded as accepted without sending.
Hooks always send at once; scheduling needs the API.

NoteRead a scheduled notification with Get a notification: state and sendAt show where it stands.