Scheduling and expiry

Publish later, expire automatically, save drafts, and edit, cancel or delete notifications.

All timestamps in the API are epoch milliseconds (UTC).

Publish later

Set publishAt to a future time. More than a minute ahead needs the Growth plan and up (see plan features):

{
  "audience": { "type": "all" },
  "contents": { "en": { "title": "Our autumn sale starts now" } },
  "publishAt": 1793606400000
}

The notification is stored with status scheduled and appears in feeds once publishAt passes. Clients with realtime on are told to refetch at that time; others pick it up on their next fetch.

Omit publishAt to publish immediately. A publishAt in the past backdates the notification: it is published now but sorted (and shown as published) at that time.

Expire automatically

Set expiresAt to remove the notification from every feed at that time, for example for a maintenance window or a limited offer:

{
  "audience": { "type": "all" },
  "contents": { "en": { "title": "Maintenance on 2 November from 22:00 to 22:30 UTC" } },
  "expiresAt": 1793658600000
}

expiresAt must be after publishAt (or after now, when publishing immediately). Expired notifications get the status expired and stay in your history. Feed items include expiresAt, so a UI can show "ends in 2 hours".

Drafts

Send "status": "draft" to save a notification without publishing it. Drafts never appear in feeds. To publish one, update it with "status": "published"; it goes live at its publishAt, or immediately if it has none.

Statuses

Filter by status with GET /v1/notifications?status=scheduled.

Edit, cancel, delete

• Edit drafts and scheduled notifications with PATCH /v1/notifications/{id}. Any field except idempotencyKey can change, including the audience; send null to clear category, actionUrl, imageUrl, data or expiresAt. Editing a published, expired or canceled notification returns 409 conflict.
• Cancel with POST /v1/notifications/{id}/cancel. Works in any status, including published: the notification disappears from every feed but stays in your history with status canceled. Use this to take back a mistake.
• Delete with DELETE /v1/notifications/{id}. Permanently removes the notification and everyone's read/archive state for it.

Cancels and deletes reach users like new notifications do: right away for clients with realtime on, otherwise on their next fetch. For broadcasts this can take up to about 30 seconds longer. See Polling, realtime and performance.

Retention

Feeds only show notifications published within your plan's retention window (30, 90 or 365 days, or your custom plan's, see Billing and limits). Older notifications stay in your history until they are 365 days old (or as old as a longer custom plan window), when they are deleted.