Notifications and usage alerts

Email that the deployment sends to people (console users) about their workspace: usage alerts, new mail in inboxes they follow, and a daily list of things that need a person. Agents keep using webhooks and the API; this page is about the humans behind them.

1. Kinds

There are no browser or desktop alerts: the console has no JavaScript (FR-CON-1). The Overview banners (Cloud sign-up §8) show the same states when someone is signed in.

Nothing in a notification comes from mail content. A new_mail email names the inbox and counts messages (“3 new messages in bookings.brightwell@pylotamail.com, 2 waiting for a reply”). It never includes a subject, a sender, a snippet or an attachment name. Untrusted text stays out of notifications, and the notification is safe to read on a lock screen.

2. Preferences

Set per person and per workspace at /console/settings/notifications. API keys are not people, so there is no REST endpoint for preferences.

CREATE TABLE notification_prefs (
  user_id      TEXT NOT NULL REFERENCES users(id),
  tenant_id    TEXT NOT NULL,
  kind         TEXT NOT NULL CHECK (kind IN ('usage','new_mail','needs_person')),
  mode         TEXT NOT NULL CHECK (mode IN ('off','instant','hourly','daily')),
  filter       TEXT NOT NULL DEFAULT 'all' CHECK (filter IN ('all','needs_reply')),   -- new_mail only
  identity_ids TEXT,                                -- JSON array; NULL = every inbox (new_mail only)
  paused_reason TEXT CHECK (paused_reason IN ('bounce','complaint')),
  updated_at   INTEGER NOT NULL,
  PRIMARY KEY (user_id, tenant_id, kind)
);

• A missing row means the default: usage = instant and needs_person = daily for owners and admins, off for members and viewers; new_mail = off for everyone.
• usage accepts only off and instant. needs_person accepts only off and daily.
• Removing a member deletes their rows for that workspace, and pending notifications for them are dropped (O19). Person erasure deletes all their rows.

3. How notifications are produced

A Notifier Durable Object, one per tenant (binding NOTIFY), owns coalescing, schedules and caps. It is SQLite-backed like the other objects.

Which messages count for new_mail. Only messages that become visible in the inbox: status received, not quarantined, not hidden, not marked spam, not loopback, and not on a test tenant (O15). A message released from quarantine counts when it is released.

Coalescing for new_mail (O14):

With filter = needs_reply, a message waits up to 5 minutes for triage. If triage says needs_reply, or triage was skipped (no allowance, or disabled), it is counted. Otherwise it is not (O16).

Caps (O24). At most 50 notification emails per person per day, and 200 per workspace per day, across all kinds except account. Past a cap, further items for that day go into the next daily digest, and the person’s settings page says so.

4. Usage alerts

• Features: every allowance in the plan catalog (inboxes, sends, triage, custom_domains, storage_gb, seats). On a deployment with PM_BILLING=off, alerts use the operator quotas in tenant policy, and features with no quota send none (O23).
• Thresholds: 80% and 100% of granted, including top-ups.
• Once per threshold per period (O20). For allowances that reset (sends, triage), each threshold alerts at most once per billing period, even if holds are released and the usage crosses again. For counts that do not reset (inboxes, custom_domains, seats, storage_gb), a threshold alerts when it is crossed upwards, with a 24-hour cooldown per feature and threshold (O21). TenantQuota.meta keys alerted:{feature}:{threshold}:{period} record it: for sends and triage, {period} is the period’s period_start and the value is 1; for the count features, {period} is the literal count and the value is the time of the last alert, which the cooldown compares with.
• Content: the feature in plain words, used and granted, the reset date (or “does not reset”), what happens at 100% (“sends return 402 billing_limit until 1 November”), and links to Plan and usage and to buying a top-up (owners only).
• Webhooks are unchanged. quota.warning and billing.limit_reached events still go to endpoints, so agents learn about limits by the same route as before.

5. The emails

• Sent from the reserved system identity at PM_SYSTEM_FROM, through the normal outbound pipeline with kind: "transactional". They take part in suppressions and bounce handling like any message.
• Subjects: [Pylota Mail] Sends at 80% for Brightwell, [Pylota Mail] 3 new messages in bookings.brightwell@…, [Pylota Mail] 4 things need you in Brightwell.
• Plain text and a minimal HTML part with no images and no tracking.
• Every usage, new_mail and needs_person email carries List-Unsubscribe: <https://{PM_CONSOLE_HOST}/console/notifications/unsubscribe?t={token}> and List-Unsubscribe-Post: List-Unsubscribe=One-Click (RFC 8058). The token is a MAC under the current link key with its kid, binding the user, workspace and kind, valid for 90 days. A POST sets that kind to off for that person and workspace, without sign-in. An expired or foreign token changes nothing and shows a page linking to settings (O18). account emails have no unsubscribe header; they link to settings instead.
• The unsubscribe routes (GET shows a confirmation page with a one-click form, POST turns the kind off) need no session and are exempt from the console’s CSRF token and Origin check (W16): a mail provider sends the RFC 8058 POST without either. The token is their only authority, and it can only turn one kind off. They are served even with PM_CONSOLE=off, like the invitation-accept pair, so the header of every email works. The token verifies under any link key still inside its verify window, so after a link rotation an older token stops working once its key leaves the 7-day window, even inside its 90 days, and gets the expired-token page; every new email carries a token under the current key.
• Bounces and complaints (O17). A hard bounce or complaint on a notification sets paused_reason on every preference of that person, in every workspace (a kind with no row gets its default row first, so the pause is recorded), and suppresses the address as usual (FR-DLV-2). The system identity’s mailbox recognises a notification by the message’s metadata.notify_user_id, which the Notifier sets on every send (mailboxes keep only a hash of the idempotency key, so the key cannot be used for this). While a person is paused, the Notifier sends them nothing but account emails, and the console shows a banner asking them to confirm their address. Confirming it clears paused_reason and removes the system identity’s suppression of that address, which is the person’s own. It needs a session but not a recent sign-in: while the address is suppressed, the system identity’s mail to it, sign-in and re-authentication codes included, is not delivered, so the person confirms from a session they already have, or after signing in with Google or GitHub.

6. Time zones and schedules

Daily items run at 09:00 in the tenant’s time zone (tenants.timezone). A time-zone change takes effect from the next day; a day is never sent twice or skipped (O22). Across a daylight-saving change, 09:00 local is computed for each day with the time-zone database.

7. When the platform domain is failing

System mail uses the platform domain, which has no fallback (Fallback behaviour). While the platform domain is failing, notification sends fail like any other send from it. The Notifier keeps the items and retries hourly for 24 hours, and the operator is alerted by the existing platform domain alert (O25). A suspended tenant gets account emails only (O26).

8. Notifier object

The object’s ID is minted with the tenant row and stored in tenants.notify_do_id, like quota_do_id for TenantQuota, and the object takes NotifierRequest::Init before anything else (Design § 5). Its single alarm is set to the earlier of alarm:send and alarm:daily (Design § 4, rule 5) and drives sending. Each send is idempotent: the outbound request uses an Idempotency-Key of notify:{user_id}:{kind}:{ref}:{window start}, so a retried alarm cannot send twice, and two different items due in the same window never share a key (which would be refused as 409 idempotency_conflict).

9. Configuration

10. Tests