SP Mail Next — system integration
Server contract: sp-mail/docs/next/ARCHITECTURE-NEXT.md §3 D-N4, D-N10, §4.2 and docs/next/PUSH.md. Code: Sources/Shared/System/ (app side), Packages/SPMailSystem (logic shared with the extensions, unit-tested), Sources/Widgets, Sources/ShareExtension, Sources/NotificationService, Sources/Intents.
Targets and identifiers
| Target | macOS (Developer ID) | iOS / iPadOS (App Store Connect) |
|---|---|---|
| App | ai.spboucher.spmail |
ai.spboucher.spmail.ios |
| Widgets | ai.spboucher.spmail.widgets |
ai.spboucher.spmail.ios.widgets |
| Share extension | ai.spboucher.spmail.share |
ai.spboucher.spmail.ios.share |
| Notification service | ai.spboucher.spmail.notifications |
ai.spboucher.spmail.ios.notifications |
Debug builds insert .dev after the app identifier (ai.spboucher.spmail.dev.widgets, …), use their own shared group and the URL scheme spmail-dev.
Shared state (decision D-N10)
Two channels, both written by the app only (SharedStateWriter), read by the extensions through SharedStore:
- Shared keychain access group
3YM54G49SN.group.ai.spboucher.spmail— the session token (copied withSharedContainer.migrateToken, the app's own entry is kept), the extension state (signed in, preview level, app lock, mailboxes) and the key of the sealed snapshot. Any build signed by the team can declare this group: nothing to register at Apple. - App Group container — the sealed widget snapshot and the share queue (sealed files, 1 MiB chunks). macOS uses the Team-ID-prefixed group
3YM54G49SN.group.ai.spboucher.spmail(no registration under Developer ID). iOS needsgroup.ai.spboucher.spmailregistered and attached to the four App IDs.
The mail database stays in the app container; no extension opens it. Sign-out and a revoked session clear both channels.
App Group on iOS — the one manual step
The App Store Connect API key used by Scripts/provision.py and by automatic signing can turn the App Groups capability on (done for the four iOS App IDs), but it cannot create a group identifier nor attach it to an App ID: an archive signed with the group entitlement fails with « Provisioning profile … doesn't support the group.ai.spboucher.spmail App Group ».
Until that step is done, the iOS Release build is signed without the container entitlement and degrades cleanly: token, state and widget snapshot go through the shared keychain group (widgets, the notification service and the share extension all work); the only loss is that a share with files cannot be queued for the app — the share extension sends it directly through the API instead (text-only drafts can still be queued).
To enable the container, once, in the Apple Developer account (Certificates, Identifiers & Profiles):
- Identifiers → App Groups → + → identifier
group.ai.spboucher.spmail. - On each of
ai.spboucher.spmail.ios,.ios.widgets,.ios.share,.ios.notifications: App Groups → Configure → select that group → Save. - Archive with
SPMAIL_IOS_APP_GROUP=1 Scripts/ios-archive.sh archive(selectsConfig/*-iOS-AppGroup.entitlements).
Optional, same place: enabling « Communication Notifications » on ai.spboucher.spmail.ios (not a capability type of the API either) and adding com.apple.developer.usernotifications.communication to the app entitlements lets the notification service show the sender monogram as an avatar. Without it the notification is delivered as a normal one.
Push and notifications
- Registration: asked once a session exists (never before sign-in); the APNs environment is read from the signature (
PushEnvironmentDetector), not from the build configuration; re-registration on token, session, app version or locale change; the device is deleted on sign-out. A server without APNs credentials is shown as « Non configuré sur le serveur » and the app announces new mail by itself. - One notification per message: when the server's push pipeline is active for this device the app posts no local notification; otherwise it posts one, never for a message already announced (ledger + what is in Notification Centre), under the same request identifier as the server's
apns-collapse-id. - Categories
MAIL_NEW(reply with text, mark as read, archive, delete on iOS),MAIL_REMINDER(open, remind in one hour, done),MAIL_ALERT. Actions run through the sync engine / the normal send path. Reply and delete always require the device to be unlocked; with the app lock on, every mail action does. - Privacy: the server applies the account's preview level; the notification service extension lowers it further when SP Mail is locked or the device hides senders and subjects. Widgets and Spotlight follow the same level.
- Background work: iOS decides if and when
BGAppRefreshTask/BGProcessingTaskrun; nothing stays connected while the app is suspended. With an active push pipeline the app asks for a sparse refresh only (cache and widgets), none in Low Power Mode or Low Data Mode.
Deep links
spmail://conversation?mb=<mailbox>&email=<id>[&thread=<id>], spmail://inbox[?mb=], spmail://compose, spmail://search?q=, spmail://reminders, spmail://share; mailto: on both platforms. Identifiers are opaque; a link never carries content. Universal links (applinks:) are not used: the server's apple-app-site-association lists webcredentials only.
Signing and release
Scripts/provision.py --check # dry run
Scripts/provision.py # bundle ids, capabilities, one Developer ID profile per macOS bundle → Build/profiles/
Scripts/release.sh && Scripts/verify-release.sh # macOS: app + three extensions, each with its own profile
Scripts/ios-archive.sh archive && Scripts/ios-archive.sh exportDevelopment stack with push
Scripts/dev-backend.sh start runs a private backend whose APNs host is the local fake (Scripts/dev-fake-apns.mjs, requests logged in Build/fake-apns.jsonl). A simulator cannot receive those pushes: Scripts/system-shots.sh delivers the same payloads with xcrun simctl push and drives the UI (Tests/SystemUITests).
What only a physical device can verify
Real APNs delivery (token, environment, topic), the notification service extension (not launched for simctl push), widgets on a real Lock Screen, Handoff between devices, background refresh timing, Siri phrases, the macOS Release build launched from a notarised copy.