SPB Git

Repository Public

PUSH.md 12.1 KB

# SP Mail Next — push notifications (operator guide)

Scope: APNs push for the native Apple apps, plus the server-side snooze / reminder notifications that ride the same queue. Contract: ARCHITECTURE-NEXT.md §3 D-N1, D-N2, D-N4 and §4.2, §4.3. Code: server/src/next/apns.ts (APNs client and pure functions), server/src/next/push.ts (routes, watcher hook, dispatcher), server/src/next/snooze.ts (snoozes and reminders), migration db/migrations/004_push_snooze.sql.

# 1. Configuration

Variable Meaning
SPMAIL_APNS_KEY_FILE Path of the APNs authentication key (AuthKey_XXXXXXXXXX.p8, ES256 / P-256) downloaded once from the Apple Developer account (Certificates, Identifiers & Profiles → Keys → Apple Push Notifications service). Keep it outside the repository, mode 600, readable by the backend user only
SPMAIL_APNS_KEY_ID The 10-character key identifier shown next to the key
SPMAIL_APNS_TEAM_ID The Apple Developer team identifier (3YM54G49SN for the SP Mail apps)
SPMAIL_PUSH_BACKOFF Retry delays in seconds, default 5,30,120,600,3600
SPMAIL_APNS_HOST_OVERRIDE Tests only. Origin of a fake APNs server (http://127.0.0.1:<port>, cleartext HTTP/2). The backend refuses to start with this variable on an https origin

One key serves both environments and every bundle identifier of the team. The APNs host is chosen per device from the environment it registered with: production → api.push.apple.com, sandbox → api.sandbox.push.apple.com (port 443). The apns-topic is the device's bundle_id.

Without the three SPMAIL_APNS_* values (or if the key file cannot be read or is not a P-256 key) push is disabled: the watcher hook enqueues nothing, the dispatcher does nothing, POST /api/next/push/test answers { "queued": 0 } and GET /api/next/push/status answers configured: false with the reason in last_error. Nothing is ever simulated. Devices can still register; they start receiving once push is configured. A missing key file is re-read at most once per minute, a loaded key is kept until restart (restart the backend after rotating the key).

Network: the backend node needs outbound TCP 443 to api.push.apple.com and api.sandbox.push.apple.com (17.0.0.0/8). Nothing inbound.

# 2. Pipeline

  1. The app registers its token: POST /api/push/register { apns_token, environment, bundle_id, device_name?, locale?, app_version? } → { ok, device_id } (native sessions only). Registering the same token again updates the row and re-enables it. A token that moves to another user loses its per-device preferences and anything still queued for the previous user.
  2. The inbound watcher (workers/inbound.ts) calls the push hook inside its transaction. For each received message that is in an Inbox and not $seen, the hook inserts one push_outbox row per enabled device of every user who can read the mailbox (owner and mailbox_grants.can_read). dedup_key = new:<device>:<mailbox>:<email> is unique: replaying a watcher batch cannot produce a second alert. Messages received more than 24 hours ago (import, watcher stopped for a long time) are not announced.
  3. The dispatcher (push dispatcher worker, every SPMAIL_WORKER_TICK_MS) claims rows with FOR UPDATE SKIP LOCKED and a one-minute lease, computes the badge, signs the provider token (ES256, cached 50 minutes) and posts over a persistent HTTP/2 session per host.
  4. Result handling:
APNs answer Classification Effect
200 ok row sent, apns_id recorded, device last_push_at updated, last_error cleared
429, 5xx, network error or timeout (10 s), 403 ExpiredProviderToken retry next attempt after 5 s, 30 s, 2 min, 10 min, 1 h; failed after 6 attempts or when the row is older than 24 h; the error is visible in the device's last_error
410, 400 BadDeviceToken, 400 DeviceTokenNotForTopic, Unregistered drop-token the device row is deleted (its queued rows go with it); the app registers again on next launch
any other 4xx fail row failed, device last_error and failure_count updated

Rows that are no longer pending are pruned after 7 days.

A device stops receiving as soon as its session ends: revoking the session (DELETE /api/sessions/:id), logging out, removing the passkey that opened it, or DELETE /api/next/push/devices/:id delete the token. As a safety net the dispatcher also deletes the device instead of sending when it finds the session revoked or expired (for example after cli revoke-sessions).

# 3. Preferences

User level (GET / PUT /api/next/push/prefs; PUT applies only the keys present in the body):

Key Default Effect
enabled true false: nothing is queued for this user
preview "sender" none: title SP Mail, generic body; sender: sender name, generic body; full: sender, subject (subtitle), start of the text
quiet_hours null { start: "22:00", end: "07:00", tz: "America/Toronto" }, evaluated on the server in the IANA time zone (the range may span midnight). During quiet hours a new message produces a silent badge-only push instead of an alert
priority_senders [] addresses or @domain (exact domain); they bypass quiet hours and priority_only, and their alerts are time-sensitive. Contacts flagged vip are implicitly priority senders (when the contacts tables exist)
priority_only false only priority senders alert; everything else is a silent badge-only push
mailboxes {} { "<mailbox_id>": false } mutes a mailbox: no alert, and it is left out of the badge
badge "inbox" none: no badge key in any payload and no silent badge pushes

Device level (PATCH /api/next/push/devices/:id): enabled, prefs.mailboxes (mute a mailbox on this device only), prefs.sound (false removes the sound). The generic texts follow the device locale (French when it starts with fr, otherwise English).

# 4. Payloads

Alert (apns-push-type: alert, apns-priority: 10, apns-expiration: now + 24 h, apns-collapse-id: 40 hex characters derived from the dedup key):

json
{ "aps": { "alert": { "title": "Alice Martin", "subtitle": "Budget 2027", "body": "Voici les chiffres…" },
           "badge": 4, "sound": "default", "thread-id": "<mailbox_id>:<thread_id>", "category": "MAIL_NEW",
           "mutable-content": 1, "interruption-level": "active" },
  "mb": "<mailbox_id>", "email": "<jmap email id>", "thread": "<jmap thread id>", "kind": "new" }

subtitle exists only at preview level full. interruption-level is time-sensitive for a priority sender. mb, email, thread are opaque identifiers: the app fetches the message over its authenticated session.

Silent badge update (apns-push-type: background, apns-priority: 5, apns-collapse-id: badge, expiration now + 1 h):

json
{ "aps": { "content-available": 1, "badge": 3 }, "kind": "badge" }

Sent when mail is read, moved out of the Inbox or deleted from another client. Changes are debounced: one row per device (dedup_key = badge:<device>), re-armed by each change and sent 2 seconds after the first one, so a burst produces one push. The dispatcher skips the push when the computed badge equals the last badge sent to that device.

Snooze and reminder (kind: "snooze" or "reminder", category: "MAIL_REMINDER"): same shape as an alert; title = sender (snooze) or counterpart (reminder), body = subject (or the reminder's note). The preview preference applies: sender keeps the title only, none shows generic text. kind: "test" is the notification of POST /api/next/push/test; kind: "alert" is reserved for operator alerts (enqueueUserPush).

Badge = sum of unreadEmails of the Inbox folder of every mailbox the user can read (muted mailboxes excluded), read from the mail server at send time.

# 5. Monitoring

GET /api/next/push/status (any device session; figures are those of the calling user):

json
{ "configured": true, "environment_hosts": { "production": "api.push.apple.com", "sandbox": "api.sandbox.push.apple.com" },
  "queue": { "pending": 0, "failed_24h": 0, "sent_24h": 12 }, "last_error": null }

Whole-installation view, in SQL:

sql
select status, kind, count(*) from push_outbox where created_at > now() - interval '24 hours' group by 1, 2 order by 1, 2;
select id, device_name, bundle_id, environment, enabled, last_registered_at, last_push_at, last_error, failure_count from push_devices order by last_registered_at desc;
select id, kind, attempts, next_attempt_at, last_status, last_error from push_outbox where status = 'pending' order by next_attempt_at limit 50;

Neither device tokens nor payloads are written to the logs. push_outbox.payload holds only the text already reduced to the user's preview level ({"silent": true} for a quiet-hours row).

# 6. Troubleshooting

Symptom Likely cause and action
configured: false, last_error: "APNs is not configured…" one of the three variables is missing in the backend environment
last_error: "the APNs key file cannot be read" wrong path or permissions; fix, the file is re-read within a minute
last_error: "the APNs key is not a P-256 key" the file is not the .p8 from Apple
device last_error: "403 InvalidProviderToken" wrong key identifier or team identifier, or the key was revoked at Apple; rows end failed
device last_error: "403 ExpiredProviderToken" the server clock is wrong (the token is re-signed and the row retried); check NTP
device last_error: "400 TopicDisallowed" / "403 BadCertificateEnvironment" the bundle identifier is not covered by the key's team, or APNs is not enabled for the App ID
devices disappear right after a push BadDeviceToken: a sandbox token registered as production or the reverse (debug builds must register sandbox); DeviceTokenNotForTopic: the app registers a bundle_id that is not its own
device last_error: "0 network" or "0 timeout", rows stay pending no route to APNs on 443 from the backend node; rows retry with backoff and fail after 6 attempts
alerts arrive without a badge the mail server was unreachable when the alert was sent (the alert is not delayed for the badge)
a user gets only silent pushes quiet hours are active in the configured time zone, or priority_only is on
nothing is queued for a new message the message is not in the Inbox (Sieve filed it), is already $seen, the mailbox is muted, the user has no enabled device with a valid session, or push is not configured
a snoozed message did not come back select id, status, until, attempts, locked_until, last_error from snoozes where status = 'active' and until < now(); a last_error means the mail server refused or was unreachable, the worker retries with a growing delay (10 minutes at most)

# 7. Snoozes and reminders (server state)

  • Snooze: the message is moved to a folder named Snoozed at the root of its mailbox (created on first use, no role) and gets the keyword $snoozed; the row keeps the folders it came from. At the due time the snooze waker worker moves it back (Inbox when the origin no longer exists), removes $snoozed, makes it unread and queues a snooze push. DELETE /api/next/snoozes/:id brings it back immediately without touching the read state and without a push (cancelled). A message deleted meanwhile ends missing; a message the user moved out of Snoozed by hand ends done with no push.
  • Reminder: at the due time the reminder evaluator worker sets $followup on the message, marks the row due and queues a reminder push. With only_if_no_reply, it first reads the thread: a message that was not in the thread when the reminder was created (the row keeps the thread's message ids, so no clock is compared) and whose From is not one of the user's own addresses makes the reminder resolved, silently. A reminder on a deleted message ends cancelled.
  • Both workers take a two-minute lease per row and write the final state and the push row in one transaction; the push dedup_key carries the snooze or reminder identifier, so a restart or a second instance cannot notify twice.
Files main
Menu

Theme