SP Mail — macOS and iOS / iPadOS
Native clients (Swift 6, SwiftUI) of the self-hosted SP Mail platform: two apps, three extensions each, two UI-free packages — passkey sign-in, JMAP delta sync, encrypted offline cache, a rich-text composer with undo send, labels, snooze and follow-ups, operator search, a Command Center, optional intelligence, notifications, widgets and a share extension.
Author: Simon-Pierre Boucher
Table of contents
- Overview
- Features per platform
- What 2.0 adds — « SP Mail Next »
- Architecture
- Stack
- Repository layout
- Configurations
- Build, develop and test
- Keyboard shortcuts
- Server routes used
- Local data model and at-rest decisions
- Security model
- Sending states
- Sync and background behaviour
- Testing
- Release
- The App Group situation
- Never verified on a physical device
- Gotchas
- Not implemented / partial
- Author
- License
🎯 Overview
Native clients (Swift 6, SwiftUI) of the self-hosted SP Mail platform (https://mail.spboucher.ai). Two apps, six extensions, two packages:
- SP Mail for macOS —
ai.spboucher.spmail, App Sandbox + hardened runtime, Developer ID. - SP Mail for iOS / iPadOS —
ai.spboucher.spmail.ios, iPhone and iPad (TARGETED_DEVICE_FAMILY 1,2), distributed through App Store Connect / TestFlight. - Three extensions per app — widgets (WidgetKit), a share extension, a notification service extension.
SPMailCore— a UI-free Swift package (macOS 15 / iOS 18, no third-party dependency): API and JMAP clients, sync engine, sealed cache, the SP Mail Next client (NextAPI) and its offline store (NextStore), the composer's rich-text model.SPMailSystem— a UI-free package shared by the apps and the extensions: deep links, notification routing / categories / dedup, badge maths, APNs environment detection, the sealed shared state and share queue.
The apps speak standard JMAP and the platform's REST routes to the SP Mail backend gateway, never to the mail server, and hold no mailbox password: sign-in is a passkey, the session is a bearer token in the Keychain. Every SP Mail Next surface is capability-gated (GET /api/next/capabilities): against an older server the Next entries stay hidden and the composer sends as 1.1 did.
The SP Mail family
| Piece | spbgit repository | Role |
|---|---|---|
| Backend, webmail, REST API, MCP server, SDKs | sp-mail | https://mail.spboucher.ai (Stalwart mail server + Fastify backend) |
| macOS and iOS / iPadOS apps | sp-mail-apple (this repository) | native clients |
Administration (addresses and aliases, API keys, approvals, webhooks, API explorer) is web only: Settings › Comptes › « Administration (web) » opens https://mail.spboucher.ai/admin in the default browser. Creating Sieve filters and automation rules is web only too (the apps list them, switch rules on and off and show their history).
✨ Features per platform
| Area | macOS | iPhone | iPad |
|---|---|---|---|
| Sign-in | passkeys (RP mail.spboucher.ai), enrollment from a pasted /enroll#token link |
same | same |
| Layout | three columns + inspector, one window per message / composer / studio, menu bar extra, Dock menu | stack navigation, swipe actions, floating compose button | split view, several scenes (Stage Manager), hardware-keyboard commands |
threads, flags, archive, junk, delete, move, drag and drop, Quick Look, .eml export, mailto: handler, Services menu « Nouveau message SP Mail avec la sélection » |
same actions, swipe and context menus | same | |
| Reader | isolated web view (JavaScript off, every load blocked, remote images on request through the backend proxy), link prompt with the real destination, three themes (light, dark, midnight) | same | same |
| Composer | rich text on every OS version (TextKit): headings, lists, quotes, links (⇧⌘K), inline images with size presets, attachment tray with Quick Look and reorder, recipient tokens with autocomplete and groups, managed signatures, ;shortcut snippets, templates, split send button (send · send later · send and remind), server-side undo send, honest draft states |
same, formatting bar as keyboard accessory, photo picker | same as macOS, sheet presentation |
| Writing assistant | improve, fix spelling and grammar, shorten, expand, change tone, translate, suggest subject lines — on the selection or the authored text, preview then accept / cancel; hidden when intelligence is off | same | same |
| Organise | labels (colour dots, filter = label: search), pin (pinned first across the whole folder), snooze (server-side), « Me le rappeler » follow-ups, saved searches / smart folders |
same | same |
| Search | operator search across mailboxes (from: label: is: before: … evaluated in the device's time zone), chips from the server's parse, optional search by meaning |
same | same |
| Unified inbox | « Toutes les boîtes »: inbox, unread, flagged, drafts, sent across mailboxes, bulk actions on a multi-selection | same | same |
| Outbox | local drafts and queued messages, server-tracked sends (held, scheduled, accepted, delivered, deferred, bounced, failed — per recipient with the SMTP reply), unsent items of a removed mailbox (export .eml / delete) |
same | same |
| Contacts · attachments | contacts (favourites, VIP, groups, duplicates, vCard import / export, history), attachment gallery (filters, ZIP download, drag out) | same, without drag out | same |
| Command Center | dashboard widgets (inboxes, needs attention, scheduled sends, awaiting replies, recent attachments, important contacts, storage, delivery problems, sync status), layout synchronised between devices; never the default screen | same | same |
| Intelligence (optional, off by default) | summary, reply suggestions, writing assistant, smart triage, semantic index; provider « MacLustr local » or Anthropic with explicit consent; every surface names its provider | same | same |
| Settings | accounts and devices, signatures, composing, appearance, privacy, security, intelligence, out of office (vacation responder through Sieve), filters and rules (read, enable / disable), storage, notifications | same | same |
| Template studio | library with live thumbnails, « Créer avec l'IA », editor, versions, export, send a template (its own window) | tabs | split |
| System | notifications with actions (reply, mark as read, archive, snooze a reminder), widgets, share extension, Spotlight (opt-in), Handoff, App Shortcuts (4 intents), Services and Dock menus | notifications with actions, widgets (Home and Lock Screen), share extension, Spotlight, App Shortcuts, background refresh | same as iPhone |
| App lock | Touch ID with passcode fallback, idle auto-lock, every window gated | Face ID / Touch ID, content hidden in the app switcher | same |
| Languages | French (development language) and English — 1 420 strings in three catalogs, all translated | same | same |
🆕 What 2.0 adds — « SP Mail Next »
2.0.0 (1) is the merge of three branches developed in parallel on the Next design foundation (tokens, per-window MailScene, command palette, message windows):
Productivity and intelligence (Sources/Shared/Next/) — NextServices (one NextAPI + NextStore per session, mirrors of labels, saved searches, snoozes, reminders, AI settings, dashboard), labels, pin, snooze and reminders, operator search and saved searches, bulk actions in the unified inbox, contacts, attachment gallery, Command Center, the optional intelligence layer, Settings › Intelligence / Absence / Règles / Stockage.
Composer (Sources/Shared/Compose/ + Compose.swift) — a TextKit rich-text editor on every OS version (semantic attributes ⇄ e-mail-safe HTML + text alternative; the quoted original is an untouched block, kept byte for byte), inline images as cid: parts, attachment tray, token recipients, managed signatures and snippets, sending through POST /api/v1/messages/send under an Idempotency-Key with the server-side undo hold, send later, send and remind; offline the message goes through the durable JMAP outbox (no undo window). Settings › Rédaction.
System (Sources/Shared/System/, Packages/SPMailSystem, the extensions) — push registration lifecycle, notification categories / actions / routing / dedup, deep links and Handoff, Spotlight, background tasks, Settings › Notifications, App Intents, widgets, share and notification-service extensions, signing scripts for the nested bundles.
Integration work done at the merge —
- One store per session. The composer (
ComposeCenter) reads and writes theNextStoreofNextServices; its former private directory (…/next-compose) is deleted at launch. Sign-out and a revoked session wipe the store, the composer's mirrors and the tracked sends. - AI → composer. A reply suggestion opens the composer through
AppModel.openReply(to:body:all:in:)with the text inserted for review — nothing is sent. The writing assistant lives in the composer (formatting bar and « Plus » menu):POST /api/next/ai/writeon the selection or on what was written above the signature — never the quoted original, never the signature —, a preview sheet labelled with the provider, « Remplacer » / « Annuler », one undoable edit. - Delivery follow-up. A message sent through
/api/v1has no local item once the server took it; « Boîte d'envoi » now lists what the server tracks (GET /api/v1/messages/outbound): « Envoi dans N s » with « Annuler l'envoi », « Programmé pour le … », « Accepté pour livraison », « Remis au serveur du destinataire », deferred / bounced / failed per recipient with the SMTP reply. Refreshed when the outbox opens, after a sync, and on a schedule derived from the rows (when a hold ends, 15 s then 60 s for a fresh send, 2 min for a deferred one) — never a tight poll. « Remis » is shown only for the server'sdelivered. - Undo send keeps the draft.
NextAPI.undoSend(id:)usesPOST /api/next/compose/undo/:id(the draft and its attachments stay in Drafts); the former fetch-then-DELETEimplementation destroyed them. - Search time zone.
SearchQuery,parseQueryandAttachmentQuerycarrytz(the device's IANA identifier):before:/after:/todayare evaluated in the user's zone. - Shortcuts. ⌘K is the command palette; the composer's link is ⇧⌘K on every platform. The template studio moved from ⌥⌘M (the system's « Minimize All ») to ⇧⌘M.
Scripts/check-shortcuts.pyfails when a combination is declared twice or belongs to the system. - Template + sensitive recipient. A template sent from the composer that the server answers with
confirmation_requiredgoes through the composer's « Destinataires sensibles » confirmation, like any send. - Mailbox removal. Unsent drafts and queued messages of a mailbox that disappears from
/api/meare kept sealed on the device and listed in the outbox as « Boîte retirée », with « Exporter en .eml… » and « Supprimer ». - Pins across the folder. Pinned conversations are asked from the server (
Email/querywithhasKeyword: "$pinned"in the mailbox) and merged above the loaded window, so a pinned old conversation is never buried.
What 1.1 added (template studio, unified inbox, sender identities)
Template studio — « Modèles » (sidebar entry, menu « Modèles », ⇧⌘M; its own window on macOS, full screen on iOS / iPadOS): library with live thumbnails, « Créer avec l'IA » (brief, brand kit stored under templateBrand, progress as the server reports it, cancel closes the stream), editor (desktop / phone and light / dark preview, variables with a debounced live preview, « Retoucher avec l'IA », HTML and text source, versions, export), send a template (template_id + variables through POST /api/v1/messages/send, layout kept), previews in the same isolated renderer as message bodies.
Unified inbox — « Toutes les boîtes » (⌘0) from GET /api/v1/messages, each row with the receiving address as a coloured chip; a row opens in the regular reader through the sync engine of ITS mailbox; offline, the merge of the local caches.
Sender identities — the From picker lists every mailbox and its sendable aliases (GET /api/v1/addresses), grouped by mailbox; a reply starts from the address the message was sent to; an alias message leaves with the alias in From.
🏗 Architecture
flowchart TB
subgraph Apps["Two app targets (project.yml)"]
MAC["SPMail — macOS<br/>Sources/macOS · windows, menus, Dock"]
IOS["SPMail-iOS — iPhone + iPad<br/>Sources/iOS · scenes, background tasks"]
end
subgraph Ext["Three extensions per app — never open the mail database"]
W["Widgets"]
SE["Share extension"]
NS["Notification service"]
end
SH["Sources/Shared — SwiftUI<br/>AppModel · MailScene · Reader · Compose/ · Next/ · System/ · Studio/ · SelfTest"]
subgraph Core["Packages/SPMailCore — UI-free, no dependency"]
API["APIClient<br/>sessions, passkey routes, /api/v1"]
JMAP["JMAPClient + EventSource"]
SYNC["SyncEngine + Outbox"]
STORE[("MailStore<br/>system SQLite · AES-256-GCM")]
NEXT["Next/ — NextAPI (typed /api/next/*)<br/>NextStore (sealed offline cache + mutation queue)"]
RICH["Next/ — rich-text model ⇄ HTML · NextCompose · SieveConfig"]
end
subgraph Sys["Packages/SPMailSystem — shared with the extensions"]
DL["DeepLink · NotificationRouting · Dedup · BadgeMath"]
SS[("SharedStore · ShareQueue<br/>sealed files, shared keychain group")]
end
KC[("Keychain<br/>bearer token · cache key · shared group")]
BE["SP Mail backend<br/>https://mail.spboucher.ai"]
MS["Stalwart mail server<br/>(never reached by the apps)"]
APNS["APNs"]
MAC --> SH
IOS --> SH
SH --> Core
SH --> Sys
Ext --> Sys
SE -->|"send directly when it must"| API
SYNC --> JMAP
SYNC --> STORE
NEXT --> API
API --> KC
STORE --> KC
SS --> KC
API -->|HTTPS, bearer token, no Origin| BE
JMAP -->|"/api/jmap/{mailbox}/…"| BE
BE --> MS
BE -->|push pipeline| APNS
APNS --> NS
Session wiring — AppModel owns the session (token, mailboxes, one SyncEngine per mailbox) and four services passed explicitly: next (NextServices: the one NextAPI + NextStore of the session), compose (ComposeCenter: signatures, snippets, compose preferences and autocomplete read from that same store; undo holds), outbound (OutboundTracker: server-tracked sends), system (SystemServices: push, notifications, shared state, Spotlight, deep links, background work). Everything a window navigates lives in its own MailScene.
Extensions — app and extensions share two channels written by the app only: the keychain access group 3YM54G49SN.group.ai.spboucher.spmail[.dev] (session token, extension state, key of the sealed snapshot) and an App Group container (sealed widget snapshot, share queue). See The App Group situation and docs/SYSTEM-INTEGRATION.md.
Sending from the composer
sequenceDiagram
autonumber
participant C as Composer
participant O as Local outbox (sealed)
participant B as Backend
participant T as OutboundTracker
C->>O: save the draft (always first)
alt online and the server has the Next API
C->>B: GET /api/next/compose/prefs (undo delay, read now)
C->>B: POST /api/v1/files (attachments)
C->>B: POST /api/v1/messages/send + Idempotency-Key
B-->>C: scheduled + undo_until (held) · sent · queued
C->>O: discard the local draft
T->>B: GET /api/v1/messages/outbound (on open, after sync, when a hold ends…)
Note over T: « Envoi dans N s » → « Accepté » → « Remis » per recipient
else the server was not reached
C->>O: queue (JMAP, client Message-ID) — no undo window
end
Passkey sign-in and the offline JMAP replay are unchanged from 1.1: POST /api/login/options → platform assertion → POST /api/login/verify → bearer token in the Keychain; queued messages leave through Email/set + EmailSubmission/set when the network returns, and « Remis » comes from EmailSubmission/get → deliveryStatus.
🧱 Stack
| Layer | Technology | Version (read in the repository) | Role |
|---|---|---|---|
| Language | Swift | 6.0 (SWIFT_VERSION, tools 6.0) |
apps, extensions, packages |
| UI | SwiftUI (+ TextKit for the composer, WebKit for bodies) | macOS 15 / iOS 18 SDK | Sources/Shared |
| Project | XcodeGen | project.yml, xcodeVersion: 16.0 |
project generated, never committed |
| Core | Swift packages SPMailCore, SPMailSystem |
.macOS(.v15), .iOS(.v18) |
API, JMAP, cache, sync, Next client; system logic |
| Storage | system sqlite3 (linked library) |
— | local cache |
| Crypto | AES-256-GCM (CryptoKit), Keychain | system frameworks | cache at rest, token, shared state |
| Auth | AuthenticationServices | — | passkeys |
| System | UserNotifications, WidgetKit, AppIntents, CoreSpotlight, BackgroundTasks | — | notifications, widgets, shortcuts, Spotlight, refresh |
| Tests | Swift Testing (@Test) |
— | SPMailCoreTests, SPMailSystemTests |
| Tooling | Node.js (.mjs dev scripts), Python (provision.py, asc.py, make-strings.py, check-shortcuts.py) |
— | dev stack, provisioning, strings, shortcut check |
🗂 Repository layout
project.yml XcodeGen: SPMail (macOS), SPMail-iOS, 3 extensions per platform, SPMailSystemUITests
Config/ Info plists and entitlements (app / extensions × macOS / iOS × Release / Dev / iOS App Group)
Packages/SPMailCore/ UI-free package — 30 source files, 9 800 lines
Sources/SPMailCore/ APIClient · JMAPClient · EventSource · MailStore · SyncEngine · Outbox · SyncStatus · OfflineReading
HTMLSanitizer · AuthResults · Compose · OutgoingEML · Templates · TemplateGeneration · Unified · SenderIdentity
Next/ NextAPI · NextStore · NextModels* · NextHelpers (PinOrder…) · NextError · SharedContainer
NextRichText · NextCompose · SieveConfig
Tests/SPMailCoreTests/ unit (in-memory JMAP double `FakeMailServer`, stub URLProtocol) and integration suites
Packages/SPMailSystem/ UI-free package shared with the extensions — 9 source files, 925 lines
Sources/Shared/ SwiftUI shared by both apps — 63 files, 20 100 lines
AppModel.swift session, engines, mailboxes, outbox, composers
Model/ MailScene (per-window state) · OutboundTracker · AppServices · SceneStates
Compose.swift Compose/ ComposeModel · ComposeCenter · RichTextEditor · FormatBar · RecipientTokens · ComposeViews
ComposeManagers (signatures, snippets, templates, settings) · WritingAssistant
Next/ NextServices · MailScene+Next · Organize / Search / Contacts / Dashboard / Intelligence views
AttachmentGallery · RemoteListView · NextSettings · NextFixtures · NextSelfTest
System/ SystemServices · PushRegistrar · NotificationCoordinator · NotificationSettings · DeepLinkRouter
SharedStateWriter · SpotlightIndex · BackgroundWork · SystemShare
Studio/ StudioModel · StudioViews · StudioEditor · StudioPreview
Design/ tokens (SPColor, SPMetrics…) and components
SelfTest*.swift the DEBUG end-to-end scenario (base, +Compose, +System, +Integration, Next/NextSelfTest)
Sources/macOS/ Sources/iOS/ app entry points, menu bar extra, Dock menu, touch observer
Sources/Intents/ App Intents and App Shortcuts (compiled into the apps)
Sources/Widgets/ ShareExtension/ NotificationService/ ExtensionShared/ the extensions and their shared catalog
Resources/ Assets.xcassets, Localizable.xcstrings, AppShortcuts.xcstrings
Tests/SystemUITests/ simulator-only UI automation behind Scripts/system-shots.sh
Scripts/ build, dev stack, self-test launchers, strings, shortcut check, provisioning, release, archive
docs/ SYSTEM-INTEGRATION.md, brand/The Xcode project is generated (xcodegen generate) and not committed. Build products live outside ~/Desktop, in ~/Library/Developer/SPMail/ (SPMAIL_DD overrides the derived-data path).
🔀 Configurations
- Debug = « SP Mail Dev » (
…spmail.dev/…spmail.ios.dev, extensions….dev.widgets…): no Associated Domains, no push entitlement, its own shared group and the URL schemespmail-dev, plain HTTP to a local backend allowed, DEBUG launch arguments compiled in (-spmBaseURL,-spmDevToken,-spmSelfTest YES,-spmNoPrompts YES,-spmDemo YES,-spmScene …,-spmComposeDemo …,-spmOpenSettings YES,-spmSettingsTab n,-spmFakePushToken YES). It never makes Apple's CDN look up the AASA file, so it can be launched at any time. Passkeys cannot work in this variant. - Release = « SP Mail »: App Sandbox, hardened runtime,
webcredentials:mail.spboucher.ai, keychain groups, push entitlement. Server fixed to production;Scripts/verify-release.shchecks that no development switch is in the binaries (app and extensions).
| Debug | Release | |
|---|---|---|
| Display name | SP Mail Dev | SP Mail |
| macOS bundle id | ai.spboucher.spmail.dev |
ai.spboucher.spmail |
| iOS bundle id | ai.spboucher.spmail.ios.dev |
ai.spboucher.spmail.ios |
| Compilation conditions | DEBUG SPM_DEV (+ SPM_EXTENSION in extensions) |
whole-module |
| App Transport Security | NSAllowsLocalNetworking added by a post-build script |
no exception |
| macOS signing | manual, Developer ID Application | + --timestamp, one Developer ID profile per bundle |
🚀 Build, develop and test
# ONE dev stack: a private backend from the shared sp-mail checkout, with the scripted AI stub as its « local » provider and its push
# pipeline pointed at a local fake APNs. Nothing leaves the Mac (no AI call, no push).
Scripts/dev-backend.sh start # idempotent; run-dev.sh, run-sim.sh and test-core.sh --integration call it themselves
node Scripts/dev-bootstrap.mjs up # admin + two apple-*@stg.spboucher.ai mailboxes + one alias + native tokens → Build/dev-env.sh
Scripts/test-core.sh # SPMailCore unit tests, then SPMailSystem unit tests
Scripts/test-core.sh --integration # + integration tests against the dev backend and the real staging mail server
Scripts/check-shortcuts.py # no key combination declared twice in the menus, none taken from the system
Scripts/build.sh mac Debug && Scripts/run-dev.sh --selftest --shot Build/selftest.png # app self-test on macOS (JSON report)
Scripts/build.sh ios Debug && Scripts/run-sim.sh --device <udid> --shot Build/ios.png # the same in an iPhone or iPad simulator
node Scripts/dev-bootstrap.mjs fresh # new pair of mailboxes (the mail server allows ~25 messages per sender per hour)
node Scripts/dev-bootstrap.mjs purge # delete the test mailboxes and their mail
Scripts/make-strings.py --sync # re-extract UI strings from the Debug builds, apply English; exit 1 if a key has no EnglishTest mail only ever travels between the apple-*@stg.spboucher.ai mailboxes and alias created by the bootstrap script. The self-tests talk to Scripts/dev-replay-proxy.mjs: it relays everything to the dev backend except POST /api/templates/generate, which it answers by replaying a recorded stream.
Environment overrides
| Variable | Default | Used by |
|---|---|---|
SPMAIL_DEV_PORT · SPMAIL_DEV_DB |
8821 · postgres://127.0.0.1/sp_mail_apple2dev |
dev-backend, dev-bootstrap, replay proxy |
SPMAIL_REPLAY_PORT |
8822 |
run-dev, run-sim (the app talks to this port during a self-test) |
SPMAIL_AI_STUB_PORT · SPMAIL_AI_STUB=0 · SPMAIL_AI_STUB_MODE |
8853 · stub on · ok |
dev-backend, dev-ai-stub (down, slow) |
SPMAIL_FAKE_APNS_PORT · SPMAIL_FAKE_APNS=0 |
8857 · fake on |
dev-backend, dev-fake-apns (requests logged in Build/fake-apns.jsonl) |
SPMAIL_BACKEND_DIR |
~/Desktop/Cluster/projets/sp-mail |
where the backend's dist/ is run from |
SPMAIL_DD |
~/Library/Developer/SPMail/DerivedData |
build, run, strings, release scripts |
SPMAIL_SPM_SCRATCH |
~/Library/Developer/SPMail/spm-build |
test-core (one scratch path per concurrent run) |
SPMAIL_TEST_SHARED_TOKENS=1 |
private tokens per run | test-core --integration |
SPMAIL_TEST_REAL_AI=1 |
off | ONE real generation + revision (costs money) |
SPMAIL_IOS_APP_GROUP=1 |
off | ios-archive: sign with the App Group container entitlement |
| Script | Purpose |
|---|---|
build.sh [mac|ios] [Debug|Release] |
xcodegen generate + xcodebuild (app and its three extensions), errors only on the console, log in Build/ |
run-dev.sh · run-sim.sh |
launch the Dev app on macOS / in a simulator, optional self-test and stage captures (its own window / the simulator screen only) |
test-core.sh |
package tests (unit, --integration, --filter) |
dev-backend.sh · dev-ai-stub.mjs · dev-fake-apns.mjs · dev-bootstrap.mjs · dev-replay-proxy.mjs |
the dev stack and its fixtures |
system-shots.sh |
simulator captures of banners, widget gallery and share sheet (drives Tests/SystemUITests) |
make-strings.py · check-shortcuts.py |
three string catalogs; shortcut clash check |
window-shot.swift |
captures one window of a named app (smallest, or by title) |
make-icon.sh · make-icon.swift |
app icon set |
provision.py (--check = dry run) · asc.py |
bundle ids, capabilities, one Developer ID profile per macOS bundle; App Store Connect helper |
release.sh · verify-release.sh · notarize.sh |
macOS release pipeline (nested bundles handled) |
ios-archive.sh archive|export|upload + ExportOptions.plist |
iOS archive, export (app-store-connect), upload |
⌨️ Keyboard shortcuts
Declared in Sources/Shared/Commands.swift (menus) and Sources/Shared/Compose/FormatBar.swift (menu « Format »); the same commands are listed on iPad while ⌘ is held. Scripts/check-shortcuts.py verifies that none is declared twice and none belongs to the system.
| Shortcut | Command |
|---|---|
| ⌘N · ⌘O | Nouveau message · Ouvrir dans une nouvelle fenêtre (macOS) |
| ⌘K · ⌘F | Palette de commandes · Rechercher dans le courrier |
| ⌥⌘↓ · ⌥⌘↑ | Conversation suivante · précédente |
| ⌘R · ⇧⌘R · ⇧⌘F | Répondre · Répondre à tous · Transférer |
| ⇧⌘L · ⇧⌘U · ⇧⌘P | Drapeau · Marquer comme lu / non lu · Épingler / désépingler |
| ⌃⌘Z · ⌃⌘R | Mettre en veille… · Me le rappeler… |
| ⌃⌘A · ⇧⌘J · ⌘⌫ | Archiver · Indésirable · Supprimer |
| ⇧⌘N | Relever le courrier |
| ⌘0 · ⌘1…⌘9 | Toutes les boîtes · Dossier n |
| ⇧⌘C · ⌥⌘C · ⌥⌘J | Centre de commande · Contacts · Pièces jointes |
| ⇧⌘M · ⌥⌘G | Studio de modèles · Créer un modèle avec l'IA… |
| ⌘S | Enregistrer le brouillon (a composer in front) · Enregistrer le modèle (otherwise) |
| ⌥⌘0 | Corps (a composer in front) · Fenêtre principale (otherwise, macOS) |
| ⌥⌘S | Partager le message… |
| ⌃⌘L | Verrouiller SP Mail |
| ⌘B · ⌘I · ⌘U · ⇧⌘X | Gras · Italique · Souligné · Barré |
| ⌥⌘1…3 · ⇧⌘7 · ⇧⌘8 · ⌘] · ⌘[ · ⌘' | Titre / Sous-titre / Intertitre · Liste numérotée · Liste à puces · retrait · Citation |
| ⇧⌘K · ⌘\ | Lien… · Effacer la mise en forme |
| ⌥⌘I · ⇧⌘A · ⌥⌘E · ⌃⌘T | Insérer une image… · Joindre un fichier · Insérer un extrait… · Insérer un modèle… |
| ⇧⌘D · ⌥⇧⌘Z | Envoyer · Annuler l'envoi (while the countdown is shown) |
Moved in 2.0: link ⌘K → ⇧⌘K (⌘K is the palette), template studio ⌥⌘M → ⇧⌘M (system « Minimize All »), Command Center ⌥⌘D → ⇧⌘C (system « Show / Hide Dock »), snooze ⌃⌘S → ⌃⌘Z and share ⌃⌘S → ⌥⌘S (⌃⌘S is « Show / Hide Sidebar »), insert template ⌥⌘T → ⌃⌘T (⌥⌘T is « Show / Hide Toolbar »).
🔌 Server routes used
All on https://mail.spboucher.ai; contracts live in the sister repository (sp-mail: docs/api-contract.md, docs/templates-api.md, docs/API.md, docs/next/ARCHITECTURE-NEXT.md).
| Route | Used for |
|---|---|
/api/login/*, /api/enroll/* |
passkey sign-in, enrollment from a pasted link |
GET /api/me, PATCH /api/prefs |
session, mailboxes, preferences (templateBrand, dashboard) |
/api/jmap/{mailbox}/… |
JMAP session, API, upload, download, EventSource (mail, drafts, keywords $pinned / lbl_…, Sieve, quota) |
GET /api/img |
remote images, on request, with the bearer token |
/api/templates… |
template studio, live preview, generation stream |
GET /api/v1/messages, GET /api/v1/addresses |
unified inbox, sender identities |
POST /api/v1/files, POST /api/v1/messages/send |
attachments of a send; send with undo_seconds, send_at, reminder, confirm_sensitive, or a template |
GET /api/v1/messages/outbound[/{id}] |
server-tracked sends: status and per-recipient delivery with SMTP replies |
GET /api/v1/messages/scheduled (+ DELETE) |
« Programmés » |
GET /api/next/capabilities |
which Next features this server has |
/api/next/labels, /searches, /snoozes, /reminders |
labels, saved searches, snooze, follow-ups |
/api/next/search, /search/parse, /attachments (+ /zip) |
operator search (with tz), parse for chips, attachment gallery |
/api/next/contacts…, /contact-groups |
contacts, suggestions, groups, vCard, duplicates |
/api/next/compose/prefs, /compose/undo/:id, /signatures, /snippets |
undo delay and warnings, undo send keeping the draft, signatures, snippets |
/api/next/dashboard, /inbox/insights |
Command Center, model-free inbox insights |
/api/next/ai/* |
settings and consent, summarize, replies, write, triage, semantic search and index, usage |
/api/next/rules… |
automation rules (list, enable / disable, history) |
POST /api/push/register, /api/next/push/* |
APNs token, devices, notification preferences, status, test |
🗄 Local data model and at-rest decisions
MailStore is a system-SQLite cache inside the app container, with a versioned schema (PRAGMA user_version + ordered migrations). The decisions below are explicit and tested (StoreTests.previewsBodiesAndOutboxAreSealedAtRest, SchemaTests.clearTextColumnsAreExactlyTheDocumentedOnes); the header of MailStore.swift is the reference.
| Data | At rest |
|---|---|
| Previews, bodies, the outbox (drafts, queued messages and their attachments), key/value blobs (identities, tracked-send subjects…), cached attachments | sealed with AES-256-GCM under a per-install key kept in the Keychain, each value bound to its row |
emails.search_text (subject + sender / recipient names and addresses, lower-cased), emails.meta (header-level summary: subject, addresses, ids, keywords, dates), mailbox names, correspondents, pending patches |
clear inside the app container |
NextStore (labels, saved searches, signatures, snippets, favourite contacts, suggestions, compose / push / AI preferences, dashboard, queued mutations) |
sealed files in …/next, same key; ONE store per session |
| Widget snapshot, share queue | sealed files in the shared container, key in the shared keychain group |
| Bearer token, cache key | Keychain (AfterFirstUnlockThisDeviceOnly) |
Why headers are not sealed: offline search is a SQL LIKE over search_text, and list / thread queries sort and group on indexed columns. AES-GCM values are randomised, so a sealed column can be neither searched nor indexed; a searchable encryption scheme would be new cryptography, which this project does not invent. The trade-off: headers readable by whoever can read the app container, content never.
File protection (iOS): the database, its -wal / -shm files and the cache directory carry completeUntilFirstUserAuthentication. complete and completeUnlessOpen are deliberately not used for the database — background refresh and the silent-push path open the store while the device is locked, and SQLite cannot recreate its WAL files under those classes. Decrypted attachment files handed to Quick Look or the share sheet are short-lived, written with completeUnlessOpen, and removed by every wipe.
🔐 Security model
- Auth: passkeys →
/api/login/*; enrollment from a pasted/enroll#tokenlink. The bearer token is kept in the Keychain, never in preferences or logs. Requests carry noOriginheader. - 401 (session revoked elsewhere): back to sign-in, synced mail and the Next store removed, unsent drafts and queued messages kept sealed for the same person's next sign-in (another user signing in on the device does not inherit them). Sign-out: session revoked and push device deleted on the server; cache files, cache key, Next store, shared token, widget snapshot, share queue and Spotlight items destroyed.
- No web UI. The only web views render a message body or a template preview: JavaScript off, non-persistent store, a content rule list that blocks every load, CSP
default-src 'none', HTML sanitised by an allow-list first. - Intelligence is off by default. Nothing is sent to a model until the owner picks a provider and a feature; the external provider requires an explicit, recorded consent; every AI surface names the provider; a model only proposes — it never sends, moves or deletes.
- Notifications and widgets follow the account's preview level; while SP Mail is locked they never show the sender or the subject. Reply and delete actions require the device to be unlocked.
- Sensitive recipients: the server refuses to queue a message (or a template) to a listed address or domain until the person confirms.
- App lock (optional): Touch ID / Face ID with passcode fallback, idle auto-lock, every window gated.
📤 Sending states
Two paths, one rule: the interface only claims what a server said.
- Through
/api/v1(online, Next server) — the composer shows « Envoi au serveur… », then the countdown « Envoi dans N s » while the server holds the message (« Annuler l'envoi » takes it back with its draft and attachments). Afterwards the outbox section « Suivi par le serveur » carries the server's status:queued→sent(« Accepté pour livraison ») →delivered(« Remis au serveur du destinataire ») ordeferred/bounced/failed, per recipient, with the SMTP reply when delivery did not succeed. An answer that never comes is asked again under the same Idempotency-Key; the draft stays locked until the server has said what it did. - Through the JMAP outbox (offline, or an older server) —
OutboxState:draft→queuedOffline(« En attente (hors ligne) ») →sending→accepted(only afterEmailSubmission/setcreated the submission) orfailed; « remis » per recipient only fromEmailSubmission/get → deliveryStatus. No undo window.
🔄 Sync and background behaviour
- JMAP delta sync (
Email/changes,Mailbox/changes) with anchor paging for older pages, a joinable sync pass, pending-operation classification (a refused operation is dropped and recorded, a burst of 5xx keeps the queue), lossless drafts with conflict detection (both versions kept), idempotent submission (client Message-ID: a resubmission after a lost answer never sends twice), body prefetch and a sealed attachment cache with a budget. - EventSource while the app is active (reconnect with exponential backoff, woken by
NWPathMonitor). Flag / move / keyword operations are applied locally at once and replayed when offline — the server's answer always wins. - The Next collections refresh on launch, on return to the foreground and after a sync (throttled); mutations made offline are queued in
NextStoreand replayed. Snooze and reminders are server-side and are never queued silently. - The mailbox list is re-read on return to the foreground: a new mailbox gets its engine; a removed one is detached — its cache is wiped, its unsent items are kept (see the outbox).
- Push: the APNs token is registered once a session exists; with an active server pipeline the app posts no local notification (one notification per message, deduplicated against a ledger and Notification Centre). Without server credentials the app announces new mail itself, while it runs or during a background refresh.
- iOS background:
BGAppRefreshTask/BGProcessingTaskare registered and rescheduled, but iOS alone decides if and when they run; nothing stays connected while the app is suspended.
🧪 Testing
| Suite | Where | Count (run on 2026-11-20) | Needs |
|---|---|---|---|
| Core unit tests | Packages/SPMailCore/Tests (in-memory JMAP double, stub URLProtocol, recorded AI stream) |
209 (the runner reports 248 with the 39 integration tests, skipped without the dev backend) | nothing |
| Core integration tests | same target, enabled by Scripts/test-core.sh --integration |
39 | dev backend + real staging mail server |
| System unit tests | Packages/SPMailSystem/Tests |
26 | nothing |
| App self-test, macOS | Scripts/run-dev.sh --selftest |
146 steps | Debug build + dev stack |
| App self-test, iPhone / iPad simulator | Scripts/run-sim.sh --device <udid> |
145 steps (one system step is macOS only) | Debug build + dev stack |
| Shortcut clash check | Scripts/check-shortcuts.py |
58 menu shortcuts | nothing |
| String catalogs | Scripts/make-strings.py --sync |
1 420 keys, all with English | Debug builds |
The self-test (-spmSelfTest YES, Debug only, JSON report) is one scenario in one pass: the 1.1 base (launch, compose, send, receive, reader, renderer isolation, studio, unified inbox, lock, cache at rest, sign-out), the Next design foundation (themes, windows, palette, scenes), the composer steps (SelfTest+Compose.swift), the feature steps (Next/NextSelfTest.swift), the integration steps (SelfTest+Integration.swift: shared store, writing assistant, outbox follow-up, template + sensitive recipient, removed mailbox) and the system steps (SelfTest+System.swift: push registration against the fake APNs stack, notification routing and actions, widgets per privacy level, share hand-off, Spotlight, sign-out).
📦 Release
python3 Scripts/provision.py --check # dry run: what would be registered
python3 Scripts/provision.py # bundle ids (app + 3 extensions per platform), capabilities, one Developer ID profile per macOS bundle
Scripts/release.sh # universal Developer ID build → dist/SP Mail.app (app + three extensions, each with its profile)
Scripts/verify-release.sh # signatures, entitlements, versions, no dev switch — app and extensions
Scripts/notarize.sh # notarytool (keychain profile MacLustr-Notarize), staple, DMG
Scripts/ios-archive.sh archive # archive (automatic signing; SPMAIL_IOS_APP_GROUP=1 adds the container entitlement)
Scripts/ios-archive.sh export # .ipa (ExportOptions.plist: app-store-connect)
Scripts/ios-archive.sh upload # sends it to App Store Connect| macOS | iOS / iPadOS | |
|---|---|---|
| Bundle ids | ai.spboucher.spmail + .widgets .share .notifications |
ai.spboucher.spmail.ios + .widgets .share .notifications |
| Version | 2.0.0 (1) | 2.0.0 (1) |
| Deployment target | macOS 15.0 | iOS 18.0 |
| Signing | manual, Developer ID Application, hardened runtime, App Sandbox | automatic |
| Distribution | notarized, stapled DMG | App Store Connect / TestFlight |
2.0.0 (1) has been built, signed and verified (release.sh, verify-release.sh, ios-archive.sh archive + export); it has not been notarised nor uploaded at the time of writing.
Before launching a build that carries the Associated Domains entitlement, check Apple's view of the AASA file: nscurl -i https://app-site-association.cdn-apple.com/a/v1/mail.spboucher.ai (a failed lookup is cached for about an hour).
🧩 The App Group situation
App and extensions share a keychain access group and an App Group container (decision D-N10, docs/SYSTEM-INTEGRATION.md).
- macOS — the Team-ID-prefixed group
3YM54G49SN.group.ai.spboucher.spmailneeds no registration under Developer ID: the container works. - iOS —
group.ai.spboucher.spmailmust be registered and attached to the four App IDs. The App Store Connect API key used byprovision.pyand automatic signing can enable the capability but cannot create or attach the group. Until that manual step is done in the Apple Developer account, the iOS Release build ships on the shared keychain group only: token, extension state and widget snapshot go through the keychain (widgets, notification service and share extension all work); the one loss is that a share with files cannot be queued for the app — the share extension sends it directly through the API (text-only drafts can still be queued). Once the group is registered:SPMAIL_IOS_APP_GROUP=1 Scripts/ios-archive.sh archive.
📵 Never verified on a physical device
Everything above was exercised on a Mac (Debug build) and in iPhone / iPad simulators, against a local dev backend with staging mailboxes. Never verified, by anyone, on real hardware:
- sign-in with a real Touch ID / Face ID passkey (the Dev variant signs in with a development token; the Release build was built and verified, never launched);
- real APNs delivery (token, environment, topic) — the self-test registers against a local fake APNs, and a simulator cannot receive those pushes;
- the notification service extension on a device (it is not launched for
simctl push), widgets on a real Home or Lock Screen, Handoff between devices, Siri phrases; - background refresh timing, behaviour under Low Power Mode, real memory pressure;
- touch gestures, the software keyboard with the formatting accessory, the photo picker, VoiceOver and Dynamic Type beyond simulator captures;
- the macOS Release build launched from a notarised copy, and the iOS build installed from TestFlight.
🧯 Gotchas
- AASA lookups are cached by Apple's CDN: a failed lookup sticks for about an hour. Use the Dev variant (no Associated Domains) for everyday work.
- Passkeys cannot work in the Dev variant — it signs in with a development token (
-spmDevToken). - Mail-server rate limit: about 25 messages per sender per hour (
452 4.4.5beyond). One full self-test sends roughly that much: runnode Scripts/dev-bootstrap.mjs freshbetween runs. - Run one self-test at a time against a dev stack (two at once made a session drop).
- The dev backend runs from the shared
sp-mailcheckout: rebuild itsdist/(pnpm buildthere) when it is older than its last commit. - Build products must stay outside
~/Desktop:Scripts/build.shuses~/Library/Developer/SPMail/DerivedData. make-strings.py --syncreads the Debug intermediates only (macOS and simulator): build both first.- A Release build without the provisioning profiles (
Build/profiles/*.provisionprofile, created byScripts/provision.py) is built unsigned, only to check that it compiles. - The Xcode project is generated: edit
project.yml, neverSPMail.xcodeproj. - Headless undo grouping: without a text view in front (self-test), the undo manager groups everything since the last event; in the interface each command is its own event.
- Screen locked during a macOS capture: WebKit stops painting message bodies — a blank body in a capture taken then is not a rendering bug.
- A real AI generation costs money: tests and self-tests use the scripted stub and a recorded stream; only
SPMAIL_TEST_REAL_AI=1calls a model.
🧭 Not implemented / partial
- Creating or editing Sieve filters and automation rules, and administration, are web only.
- Template studio and « Programmés » need the server; sending a template is online only.
- The server's outbound object carries no subject: a tracked send shows the subject this device noted when it sent the message (or the stored copy in the local cache), else its recipients.
- A conversation is « pinned » by its newest message: a reply arriving in a pinned thread shows the thread unpinned until it is pinned again.
- English outside the three Next blocks of
make-strings.py(the 1.1 strings) still uses title case in places. - The writing assistant replaces text as plain text (formatting inside the replaced range is not kept); over an inline image it inserts under the text instead.
- Unified « Non lus » / « Avec drapeau » leave out Trash, Junk (and Drafts / Sent for unread) on the client, so a page can hold fewer rows than asked.
- The HTML source editor of the studio has no syntax colouring.
- iOS Release without the registered App Group: shares with files are sent directly instead of being queued (see above). Communication notifications (sender avatar) need a capability the API key cannot enable.
- Universal links (
applinks:) are not used: the server's AASA listswebcredentialsonly.
👤 Author
Simon-Pierre Boucher — design, development, operations
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
📄 License
All rights reserved © 2026 Simon-Pierre Boucher (NSHumanReadableCopyright in project.yml). No license file is published in this repository.