SP Mail — contrat d'API (v1)
Base : https://mail.spboucher.ai (dev : http://localhost:8731, lancé par scripts/dev.sh node dist/server.mjs).
Erreurs : statut HTTP + {"error":"code","message":"…"}. Toutes les routes /api/* répondent cache-control: no-store.
Authentification des requêtes
| Client | Session | Requêtes non-GET |
|---|---|---|
| Web | cookie __Host-spmail_session (HttpOnly, SameSite=Strict), posé par le serveur |
en-têtes Origin = origine du site et X-SPMail: 1 |
| Natif (macOS/iOS) | Authorization: Bearer <jeton> — rendu une fois par login/verify ou enroll/verify quand client.kind = "native" ; à ranger au trousseau |
aucune en-tête Origin ; avant connexion ajouter X-SPMail-Client: native |
client (optionnel, dans les corps de login/verify et enroll/verify) : {"kind":"web"|"native","deviceName":"MacBook de …","platform":"macOS 27"}.
Identité (passkeys WebAuthn ; RP ID = mail.spboucher.ai)
| Route | Corps → Réponse |
|---|---|
POST /api/login/options |
{} → {challenge_id, options} (options = PublicKeyCredentialRequestOptions JSON, identifiant découvrable, aucun nom d'utilisateur) |
POST /api/login/verify |
{challenge_id, response, client?} → {ok, token?} (response = AuthenticationResponseJSON, champs en base64url) |
POST /api/enroll/check |
{token} → `{purpose: "bootstrap" |
POST /api/enroll/options |
{token, handle?, display_name?} (requis sauf recover) → {challenge_id, options} (création) |
POST /api/enroll/verify |
{challenge_id, response, label?, client?} → {ok, token?} (RegistrationResponseJSON) |
POST /api/logout |
→ {ok} |
GET /api/me |
→ {user:{id,handle,display_name,role,prefs}, session:{id,kind}, mailboxes:[{id,address,display_name,position}], version} |
PUT /api/profile |
{display_name} |
GET /api/usage |
[{id,address,used_bytes}] pour les boîtes de l'utilisateur |
PUT /api/prefs |
objet JSON libre (≤ 20 ko) remplaçant user.prefs |
GET /api/passkeys · POST /api/passkeys/options · POST /api/passkeys/verify {challenge_id,response,label} · DELETE /api/passkeys/:id |
gestion des clés (la dernière ne peut pas être retirée) |
GET /api/sessions · DELETE /api/sessions/:id |
appareils connectés [{id,kind,device_name,platform,ip,user_agent,created_at,last_seen_at,current}], révocation |
POST /api/push/register |
natif : `{apns_token (hex), environment: "production" |
Apps Apple : Associated Domains webcredentials:mail.spboucher.ai ; /.well-known/apple-app-site-association liste les App ID autorisés.
Courrier : JMAP standard (RFC 8620/8621) par la passerelle
Une « boîte » SP Mail (mailboxes[].id, UUID, noté {mb}) = un compte du serveur Stalwart. Le client ne voit jamais d'identifiant Stalwart.
| Route | Rôle |
|---|---|
GET /api/jmap/{mb}/session |
objet Session JMAP ; ses URL pointent déjà vers la passerelle |
POST /api/jmap/{mb}/api |
requête JMAP {using, methodCalls} (≤ 10 Mo, ≤ 16 appels) |
POST /api/jmap/{mb}/upload/{accountId}/ |
corps binaire brut, Content-Type du fichier (≤ 50 Mo) → {accountId, blobId, type, size} |
GET /api/jmap/{mb}/download/{accountId}/{blobId}/{name}?accept={type}[&inline=1] |
toujours attachment + CSP: sandbox, sauf inline=1 pour `image/png |
GET /api/jmap/{mb}/eventsource?types=*&closeafter=no&ping=30 |
SSE event: state (changements d'état, jamais de contenu) |
Capacités utilisables : urn:ietf:params:jmap:core, :mail, :submission, :vacationresponse, :sieve, :blob, :quota, :contacts, :calendars. Refusés (403) : urn:stalwart:jmap et toute méthode x:*. Pas de WebSocket.
accountId = session.primaryAccounts["urn:ietf:params:jmap:mail"].
Recettes vérifiées par tests/integration/api.test.ts :
- Dossiers :
Mailbox/get(rôlesinbox,drafts,sent,trash,junk,archive),Mailbox/set. - Liste :
Email/query(filter.inMailbox,filter.text,sort: [{property:"receivedAt",isAscending:false}],collapseThreads) +Email/getpar référence de résultat ; fil :Thread/get. - Synchro delta :
Email/changes,Mailbox/changes,Thread/changesà partir dustateconservé ; sicannotCalculateChanges→ resynchronisation complète. - Drapeaux :
Email/set update {"keywords/$seen": true},$flagged,$draft,$answered,$forwarded; déplacement = patch demailboxIds. - Envoi :
Email/set create(brouillon,bodyValues+textBody/htmlBody,attachments:[{blobId,type,name,disposition}]) puisEmailSubmission/set create {identityId, emailId}aveconSuccessUpdateEmail(brouillons → envoyés). Création acceptée = « accepté pour livraison », pas « remis » : l'état réel se lit dansEmailSubmission/get → deliveryStatus[destinataire].{delivered: "queued"|"yes"|"no"|"unknown", smtpReply}. - Identités / signatures :
Identity/get|set(name,email,textSignature,htmlSignature). - Règles :
SieveScript/get|set; réponse automatique :VacationResponse/get|set. - Recherche plein texte :
Email/query filter {text|from|to|subject|body|hasAttachment|before|after}.
Images distantes
GET /api/img?u=<url encodée> — seulement sur action explicite (« afficher les images »). Refuse toute destination privée/locale, tout ce qui n'est pas une image matricielle (pas de SVG), > 10 Mo.
Administration (role = admin)
| Route | Rôle |
|---|---|
GET /api/admin/overview |
{server:{reachable,latency_ms}, domains, accounts:[{id,address,description,used_bytes,aliases}], queue:[…enveloppes], certificates, backup, counts} |
GET /api/admin/dns |
par domaine : {mx,spf,dkim,dmarc,mxHost,ptr} chacun avec ok et les enregistrements lus en direct |
GET /api/admin/users |
utilisateurs + boîtes |
POST /api/admin/mailboxes {address, display_name?, user_id?} |
crée le compte de courrier et le rattache (409 si l'adresse existe) |
POST /api/admin/mailboxes/adopt |
rattache un compte de courrier existant |
PUT /api/admin/mailboxes/:id/aliases {aliases:[…]} |
alias |
DELETE /api/admin/mailboxes/:id[?purge=delete-all-mail] |
détache ; supprime le courrier seulement avec purge |
POST /api/admin/queue/:id/retry · GET /api/admin/audit |
file d'attente, journal d'audit |
GET /api/health/live, GET /api/health/ready : sans authentification.