SPB Git

Repository Public

10 entries at the root
History

Latest commit dev-backend.sh: stop really stops the backend (the recorded PID is the server's own) b414110

NameLast commitUpdated
Config iOS: App Group container entitlement behind SPM_IOS_APP_GROUP (the API key cannot register the...
docs Integration: one dev-backend launcher (AI stub + fake APNs), system package tests in test-core,...
Packages Integration fixes: outbox follow-up of server-tracked sends, kept drafts of a removed mailbox...
Resources Outbox: no floating countdown over the iOS outbox, page-sized composer sheet on iPad, capture...
Scripts dev-backend.sh: stop really stops the backend (the recorded PID is the server's own)
Sources Outbox: no floating countdown over the iOS outbox, page-sized composer sheet on iPad, capture...
Tests Simulator captures of the system layer: UI automation (banners with actions, widget gallery,...
.gitignore SPMailCore: API, JMAP, encrypted store, sync engine, outbox, sanitiser, tests
project.yml project.yml: App Intents extractor notice documented (no clean way to silence it)
README.md Outbox: no floating countdown over the iOS outbox, page-sized composer sheet on iPad, capture...
README.md View source
SP Mail logo



SP Mail icon

# 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

mail.spboucher.ai version platform license author

Swift SwiftUI XcodeGen Xcode SwiftPM dependencies SQLite CryptoKit JMAP WebAuthn WebKit Swift Testing

commits last commit activity language languages size branches tags clones

Swift files Swift lines core system shared UI unit tests integration tests self-test localized strings scripts targets

bundle macOS bundle iOS signing sandbox TestFlight associated domains


# Table of contents


# 🎯 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
Mail 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 the NextStore of NextServices; 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/write on 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/v1 has 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's delivered.
  • Undo send keeps the draft. NextAPI.undoSend(id:) uses POST /api/next/compose/undo/:id (the draft and its attachments stay in Drafts); the former fetch-then-DELETE implementation destroyed them.
  • Search time zone. SearchQuery, parseQuery and AttachmentQuery carry tz (the device's IANA identifier): before: / after: / today are 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.py fails 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_required goes through the composer's « Destinataires sensibles » confirmation, like any send.
  • Mailbox removal. Unsent drafts and queued messages of a mailbox that disappears from /api/me are 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/query with hasKeyword: "$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

text
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 scheme spmail-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.sh checks 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

bash
# 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 English

Test 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#token link. The bearer token is kept in the Keychain, never in preferences or logs. Requests carry no Origin header.
  • 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 ») or deferred / 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 after EmailSubmission/set created the submission) or failed; « remis » per recipient only from EmailSubmission/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 NextStore and 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 / BGProcessingTask are 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

bash
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.spmail needs no registration under Developer ID: the container works.
  • iOS — group.ai.spboucher.spmail must be registered and attached to the four App IDs. The App Store Connect API key used by provision.py and 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.5 beyond). One full self-test sends roughly that much: run node Scripts/dev-bootstrap.mjs fresh between 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-mail checkout: rebuild its dist/ (pnpm build there) when it is older than its last commit.
  • Build products must stay outside ~/Desktop: Scripts/build.sh uses ~/Library/Developer/SPMail/DerivedData.
  • make-strings.py --sync reads the Debug intermediates only (macOS and simulator): build both first.
  • A Release build without the provisioning profiles (Build/profiles/*.provisionprofile, created by Scripts/provision.py) is built unsigned, only to check that it compiles.
  • The Xcode project is generated: edit project.yml, never SPMail.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=1 calls 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 lists webcredentials only.

# 👤 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.

Clone sp-mail-apple

Anonymous clone and fetch. Pushing requires the owner's personal access token.

Snapshot of main

Files main
Menu

Theme