Quiet hours and delivery

Zona separates two things that are easy to blur: storing an alert and pushing it to a phone. /notify answers for the first. The second happens afterwards, and it is best effort.

1. Zona checks the token, the key, the payload and the limits.
2. It commits the inbox record and one delivery job for each eligible phone.
3. It responds: 202 for a new alert, or 200 for a replay.
4. A background worker sends the queued jobs to the push service, retries temporary failures with bounded backoff, and later checks the push service’s receipts.

Steps 1 to 3 are what your request waits for. Step 4 is why a 202 can never promise a banner.

pushQueued in the response is the number of delivery jobs created. It can be 0 on a perfectly healthy request:

• quiet hours are active for the account or the source,
• push is switched off in the app,
• no phone is registered for push, or
• every registration is disabled.

Quiet hours are set in the app for the whole account, and each source can have its own schedule. Neither ever turns a request away:

• The request returns 202 and a notificationId, exactly as it would outside quiet hours.
• The alert is stored and searchable in the inbox straight away.
• The phone push and, if Zona is open, the in-app banner are skipped for that window, so pushQueued is 0.
• The alert’s details record the outcome as quiet hours, not as a delivery failure.

A sender does not need to know about quiet hours at all. Send every alert as it happens and let the schedule decide what buzzes.

The worker’s receipt check reports what the push service did with each job, and an alert’s details in the Zona app can show the outcome:

Mixed outcomes show as sent, with the per-phone counts still visible. Sent is the push service’s receipt, not proof that the phone displayed the alert or that anyone saw it. Delivery status lives in the app; a sender needs nothing beyond the response to its own request.

These are chosen in the app. No request field can override them.

• Push notifications: when off, alerts are still stored but no push is sent.
• Notification sound: each source has its own sound, and a global switch can silence all of them.
• Message previews: when off, the push and the in-app banner show generic text and the full alert stays in the inbox.
• In-app banners: while Zona is open, a new alert shows as a banner at the top of the screen in place of the system one, and several at once combine into one. It works with push off too, and the switch is saved on each phone.

Alerts, their checklists and their images stay in the inbox for the plan’s retention window: one day for guest accounts and seven days for standard accounts by default, and thirty days on Zona Plus. After that they expire. Keep anything you need for longer in your own logs, keyed by the notificationId from the response.

The title, body, data, source name and images can all reach a phone and its lock screen. Send what someone needs to act, link to the rest, and never include credentials or secrets. Always call the endpoint over HTTPS, and never call Zona’s database directly from a sender.