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
- 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. - The inbound watcher (
workers/inbound.ts) calls thepushhook inside its transaction. For each received message that is in an Inbox and not$seen, the hook inserts onepush_outboxrow per enabled device of every user who can read the mailbox (owner andmailbox_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. - The dispatcher (
push dispatcherworker, everySPMAIL_WORKER_TICK_MS) claims rows withFOR UPDATE SKIP LOCKEDand 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. - 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):
{ "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):
{ "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):
{ "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:
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
Snoozedat 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 thesnooze wakerworker moves it back (Inbox when the origin no longer exists), removes$snoozed, makes it unread and queues asnoozepush.DELETE /api/next/snoozes/:idbrings it back immediately without touching the read state and without a push (cancelled). A message deleted meanwhile endsmissing; a message the user moved out ofSnoozedby hand endsdonewith no push. - Reminder: at the due time the
reminder evaluatorworker sets$followupon the message, marks the rowdueand queues areminderpush. Withonly_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 whoseFromis not one of the user's own addresses makes the reminderresolved, silently. A reminder on a deleted message endscancelled. - Both workers take a two-minute lease per row and write the final state and the push row in one transaction; the push
dedup_keycarries the snooze or reminder identifier, so a restart or a second instance cannot notify twice.