How Notify thinks.

A recipient is one of your users, identified by your own user id (external_id, up to 255 of A-Z a-z 0-9 . _ : @ | -). Its profile holds an email address, a phone number (kept for SMS later), a name, a locale, a time zone, quiet hours and your own properties. It can be linked to a ProductCraft Auth end user with auth_user_id, but it does not have to be.

Its devices are APNs tokens, FCM tokens and browser push subscriptions, each with the app it belongs to and when it was last seen. A recipient keeps up to 20. Dead ones are pruned automatically when Apple, Google or a push service says so.

Create recipients with identify (an upsert), inline in a send, in bulk (1,000 per call), or by minting a token for them.

A category (“Billing”, “Security”, “Product updates”) is what users set preferences on. It has a default per channel: on, off (only if the user opts in) or mandatory (users cannot turn that channel off; use it for the few things they must get). A transactional category sends email without a one-click unsubscribe header.

A notification type (invoice.paid) is one kind of message: its category, a template per channel and locale, its routing, a time to live (24 hours by default), an optional per-recipient throttle, and an optional critical flag. There is no workflow builder: the routing fields cover delays, unread checks and fallbacks.

Critical types (security notices) ignore opt-outs and quiet hours and use their own rate budget. They never bypass a hard bounce, a spam complaint, the Mail suppression list or an email pause: those protect your sender reputation.

Channels are inbox, email, push (APNs and FCM together) and webpush. A type’s routing says which ones a message uses:

A notification is one accepted send: one type, 1 to 1,000 recipients, your data. It fans out into deliveries, one per recipient, channel and device or address, each with a state, a reason, its attempts and (for push) the text that was rendered. The console’s Message log shows both; every recipient also has a timeline across notifications.

Each recipient has cells of scope × channel: per category, per type, or for everything, per channel or * for all channels, plus “unsubscribe from everything” (never blocks critical types). The most specific cell wins: type × channel, then type × all, then category × channel, category × all, all × channel, and finally the category’s default.

Users change them through your UI with a recipient token (preferences screen); your support team can change them from your backend. Every change is recorded with its source. The one-click unsubscribe link in an email turns that category’s email off.

• Quiet hours are a window in the recipient’s time zone (22:00–08:00), or the workspace default. Push and web push wait until the window ends (then up to 10 minutes of spread); email waits only if the type says so; the inbox never waits. No time zone means no quiet hours. A held delivery that passes the type’s TTL expires, so a 1-hour TTL means “don’t send at night”.
• Scheduling: send_at or delay_seconds, at most the type’s TTL ahead.
• Cancellation keys: give a send a cancellation_key (invite:inv_77) and cancel it later by that key, without storing our id. Retract removes an item already in the inbox.

Templates use a Mustache subset: {{var}}, {{#section}} and {{^inverted}}, no partials. A missing variable renders empty and is recorded as a warning on the delivery. Links must be https:. Email templates live in ProductCraft Mail; the email channel names one.

Language fallback: the recipient’s exact locale (pt-PT), then its language (pt), then the type’s default_locale.

• tenant (your organisation or team id) on a send lets the inbox show one team’s items. Tenant objects with their own default preferences are planned.
• actor is who caused the notification: their name and avatar appear in the inbox, and they are left out of the recipients unless you say otherwise.
• tags (up to 10 pairs) make a notification searchable in the log.

Browsers and apps call /v1/client/… with a short-lived token your backend mints for one recipient: 1 hour by default, at most 24 hours, with scopes (inbox read and write, devices, preferences, the real-time stream). They are kept in memory by our browser packages, never in storage or URLs. Revoke one user’s tokens, or every token in the workspace, at any time. There is no public key that can act as any user and no shared signing secret in your backend.

The client API only accepts browser calls from the origins you list in Notify settings (while the list is empty, only http://localhost, for development). Native apps send no Origin and are not origin-checked.