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. Zona starts sending the queued jobs to the push service immediately after the response. A background worker handles unsent jobs, 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:

• the alert is held by account or source quiet hours,
• 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.
• Unless a critical alert is allowed through, the phone push and, if Zona is open, the in-app banner are skipped for that window, so pushQueued is 0. Skipped pushes are not sent when the window ends.
• The alert’s details record the outcome as quiet hours, not as a delivery failure.

Zona Plus members can turn on Let critical alerts through for each schedule. An alert its sender marked critical can then push and show an in-app banner during that window. Every active schedule must allow it; a source’s schedule can still hold it even when the account schedule lets it through. The phone’s Focus, silent switch and notification settings still apply.

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 use the retention window of the plan they arrived on: one day for guest accounts, seven days for Standard and thirty days on Zona Plus by default. Moving to a longer plan extends alerts already in the inbox; a downgrade does not shorten them.

On Standard and Zona Plus, pinning can keep an alert and its images past that window until it is unpinned or its pin expires. The default kept-pin limits are 20 on Standard and 100 on Zona Plus. A guest’s pin ends with the alert’s retention. Keep anything you need independently 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.