Repository Public
1# SP Mail — intégrations (applications, grappe, agents IA)23Comment les applications du propriétaire se branchent sur SP Mail par l'API REST `/api/v1` : une clé par application, le moins de droits possible, des SDK prêts à l'emploi et un serveur MCP pour les agents. Le contrat de l'API est dans [`API.md`](API.md) (en anglais) et [`OPENAPI.yaml`](OPENAPI.yaml) ; ce document ne le répète pas, il montre comment s'en servir.45Sommaire : [1 Principes](#1-principes) · [2 Une clé par application](#2-une-clé-par-application) · [3 Recettes par type d'application](#3-recettes-par-type-dapplication) · [4 SDK](#4-sdk) · [5 Recevoir des webhooks](#5-recevoir-des-webhooks) · [6 Agents IA (MCP)](#6-agents-ia-mcp) · [7 Exploitation](#7-exploitation)67| Paquet | Rôle | Documentation |8|---|---|---|9| `packages/sdk-ts` — `@spboucher/spmail` | SDK TypeScript (Node 20+, navigateurs, edge), sans dépendance | [README](../packages/sdk-ts/README.md) |10| `packages/sdk-python` — `spmail` | SDK Python ≥ 3.10, bibliothèque standard seule | [README](../packages/sdk-python/README.md) |11| `packages/swift-example` — `SPMailClient` | client Swift d'exemple (macOS 15+, iOS 18+) | [README](../packages/swift-example/README.md) |12| `packages/mcp` — `@spboucher/spmail-mcp` | serveur MCP (stdio) pour les agents IA | [README](../packages/mcp/README.md) |1314Aucun de ces paquets n'est publié dans un registre : ils se construisent depuis ce dépôt.1516---1718## 1. Principes1920- **De service à service, en HTTPS.** Une application appelle `https://mail.spboucher.ai/api/v1` avec `Authorization: Bearer spm_…`. Elle ne parle jamais au serveur de courrier (SMTP, JMAP) et n'a aucun mot de passe de boîte.21- **Une clé par application**, jamais partagée. Une clé compromise ou bavarde se révoque sans toucher aux autres, et le journal d'usage (Administration → Clés d'API) dit qui a fait quoi.22- **Le moins de droits possible.** Une clé = des portées (*quoi*) + une liste d'adresses (*pour qui*) + des plafonds (débit, envois par jour) + une politique d'envoi externe. Une application qui notifie n'a que `mail.send` sur une adresse d'expédition : elle ne lit aucun courriel.23- **L'expéditeur est imposé par le serveur.** L'en-tête `From` est construit par SP Mail à partir de l'adresse autorisée ; une application ne peut ni usurper une autre adresse, ni se créer une identité (une adresse créée par API n'entre dans la liste d'aucune clé tant qu'un administrateur ne l'y ajoute pas).24- **L'envoi vers l'extérieur est gardé.** Par défaut (`external_send_policy: approval`), un message dont un destinataire est hors des domaines hébergés n'est **pas envoyé** : il attend l'approbation d'un administrateur dans SP Mail (réponse `202 pending_approval`). `deny` l'interdit, `allow` le laisse partir.25- **La clé reste côté serveur.** Jamais dans un navigateur, une application distribuée à des tiers, un dépôt git ou une URL (un jeton dans une URL est refusé : `400 token_in_url`). Variable d'environnement `SPMAIL_API_KEY`, trousseau macOS/iOS, ou secrets du manifeste `mld`.2627---2829## 2. Une clé par application3031Création par un administrateur dans le webmail (**Administration → Clés d'API**, réauthentification par clé d'accès) ou sur le nœud avec le CLI d'exploitation (`scripts/prod-cli.sh` en production). **Le jeton n'est affiché qu'une fois.**3233```bash34cli key-create <nom> --scopes mail.send --addresses notifications@spboucher.ai \35 [--external allow|approval|deny] [--rate N] [--daily N] [--expires ISO] [--description "…"]36cli key-revoke <id de clé | spm_préfixe>37```3839`allowed_recipient_domains` (restreindre les domaines des destinataires) se règle dans l'écran des clés ou par `PATCH /api/admin/api-keys/{id}` ; le CLI n'a pas d'option pour ce champ.4041Vérifier ce qu'une clé peut faire, depuis l'application elle-même :4243```bash44curl -s https://mail.spboucher.ai/api/v1/me -H "Authorization: Bearer $SPMAIL_API_KEY"45# → portées, adresses (can_send, read: full | restricted | none), plafonds, politique d'envoi externe, usage du jour46```4748| Besoin de l'application | Portées |49|---|---|50| envoyer des notifications | `mail.send` |51| envoyer avec pièces jointes | `mail.send`, `mail.attachments.write` |52| suivre ses envois par webhook | + `mail.webhooks.manage` |53| lire et chercher | `mail.read`, `mail.search` (+ `mail.attachments.read`) |54| classer (lu, étoile, archive, corbeille) | + `mail.modify` |55| préparer des brouillons | + `mail.drafts` |5657À ne donner à aucune application courante : `mail.admin`, `mail.delete`, `mail.addresses.manage`, `mail.aliases.manage`.5859Lecture : si la liste de la clé contient l'adresse principale d'une boîte, la clé voit **toute** la boîte ; si elle ne contient qu'un alias, elle ne voit que le courrier de cet alias (vue restreinte, [API.md §4](API.md#4-address-level-authorization)).6061---6263## 3. Recettes par type d'application6465Les adresses ci-dessous sont des exemples de la répartition visée ; chacune doit exister (boîte ou alias) avant de créer la clé.6667### 3.1 Application de notifications seules — VQuant6869VQuant envoie des alertes et des rapports au propriétaire ; elle ne lit rien.7071```bash72cli key-create vquant --scopes mail.send --addresses notifications@spboucher.ai,alerts@spboucher.ai \73 --external deny --rate 30 --daily 100 --description "VQuant : notifications et alertes"74```7576- `notifications@` pour l'ordinaire (rapport prêt, tâche terminée), `alerts@` pour ce qui demande une action.77- `--external deny` : les destinataires sont des adresses hébergées ; toute tentative vers l'extérieur échoue net (`403 external_send_denied`) au lieu d'attendre une approbation.78- Les deux adresses peuvent être de type `send_only` ou `notification` : personne ne leur répond.79- Clé d'idempotence = identifiant métier de l'événement (`alert-<id>`), pour qu'une reprise du processus ne double jamais une alerte.8081```python82# VQuant (backend Python)83from spmail import SPMail, SPMailError8485mail = SPMail() # SPMAIL_API_KEY dans l'environnement du processus PM28687def alert(alert_id: str, title: str, body: str) -> None:88 try:89 sent = mail.messages.send(from_="alerts@spboucher.ai", to=["simon@spboucher.ai"], subject=title, text=body,90 priority="high", headers={"X-App": "vquant"}, idempotency_key=f"alert-{alert_id}")91 except SPMailError as e:92 log.error("alerte non envoyée: %s %s (requête %s)", e.status, e.code, e.request_id)93 raise94 if sent["status"] not in ("sent", "delivered"):95 log.warning("alerte %s : état %s (%s)", alert_id, sent["status"], sent.get("last_error"))96```9798### 3.2 Application de portefeuille — SP Wallet99100Codes de vérification, confirmations d'opération : un seul expéditeur, des messages par modèle, aucun droit de lecture.101102```bash103cli key-create sp-wallet --scopes mail.send --addresses wallet@spboucher.ai --external approval --rate 20 --daily 50104```105106- Les messages sont des **modèles** rédigés dans le studio du webmail (gabarit, variables obligatoires) : l'application n'envoie que des valeurs, échappées par le serveur ; elle ne compose pas de HTML.107- `--daily 50` borne les dégâts d'un emballement ou d'une clé volée ; au-delà : `429 daily_send_limit_exceeded`.108- Un courriel de sécurité doit arriver : suivre l'état final (`waitForDelivery`, ou webhook `message.bounced` / `message.failed`) et proposer un autre canal en cas d'échec.109- Ne jamais mettre de secret durable (phrase de récupération, clé privée) dans un courriel.110111```ts112// SP Wallet (backend TypeScript)113import { SPMail } from "@spboucher/spmail"114115const mail = new SPMail({ apiKey: process.env.SPMAIL_API_KEY! })116117export async function sendVerificationCode(to: string, firstName: string, code: string, attemptId: string) {118 const sent = await mail.messages.send(119 { from: "wallet@spboucher.ai", to: [to], template_id: process.env.SPMAIL_TEMPLATE_CODE!, variables: { first_name: firstName, code } },120 { idempotencyKey: `wallet-code-${attemptId}` },121 )122 if (sent.status === "pending_approval") throw new Error("destinataire externe : en attente d'approbation, rien n'est parti")123 const final = await mail.waitForDelivery(sent.id, { timeoutMs: 30_000 })124 if (final.status !== "delivered") throw new Error(`code non remis : ${final.status}`)125}126```127128### 3.3 La grappe MacLustr129130Les gardiens de la grappe (`mld heal`, sondes, sauvegardes) écrivent au propriétaire : `cluster@` pour les comptes rendus, `alerts@` pour les pannes.131132```bash133cli key-create maclustr --scopes mail.send --addresses cluster@spboucher.ai,alerts@spboucher.ai --external deny --rate 30 --daily 150134```135136- Une seule clé pour l'orchestrateur (nœud passerelle), pas une par nœud : c'est lui qui envoie. Un script isolé sur un autre nœud reçoit sa propre clé.137- Une panne déclenche vite une tempête : regrouper (un message par incident, pas par sonde), poser une clé d'idempotence par incident et par période (`heal-<incident>-<AAAAMMJJHH>`), et compter sur le plafond quotidien comme garde-fou.138- Le serveur de courrier limite lui-même à environ 25 messages par heure pour un même couple domaine expéditeur → destinataire ; au-delà le destinataire finit `failed` (`452 4.4.5`).139- Depuis un script shell, `curl` suffit :140141```bash142curl -sS -X POST https://mail.spboucher.ai/api/v1/messages/send \143 -H "Authorization: Bearer $SPMAIL_API_KEY" -H 'Content-Type: application/json' \144 -H "Idempotency-Key: heal-$INCIDENT-$(date -u +%Y%m%d%H)" \145 -d "$(jq -n --arg s "[$NODE] $TITLE" --arg t "$BODY" '{from:"alerts@spboucher.ai",to:["simon@spboucher.ai"],subject:$s,text:$t,priority:"high"}')"146```147148### 3.4 Agents IA149150Un agent lit, cherche et prépare ; l'envoi reste derrière une approbation humaine. Il passe par le serveur MCP ([§6](#6-agents-ia-mcp)), qui n'a que la clé.151152```bash153# agent de lecture (tri, résumés) — lancer aussi le serveur MCP avec SPMAIL_MCP_READONLY=1154cli key-create agent-lecture --scopes mail.read,mail.search,mail.attachments.read --addresses contact@spboucher.ai155156# agent rédacteur : lit, classe, prépare des brouillons qu'un humain envoie depuis le webmail157cli key-create agent-brouillons --scopes mail.read,mail.search,mail.attachments.read,mail.drafts,mail.modify --addresses contact@spboucher.ai158159# agent expéditeur : l'interne part, tout envoi externe attend l'approbation du propriétaire160cli key-create agent-envoi --scopes mail.read,mail.search,mail.attachments.read,mail.drafts,mail.modify,mail.send \161 --addresses contact@spboucher.ai --external approval --daily 50162```163164- Garder `--external approval`. Le contenu d'un courriel peut chercher à manipuler un modèle : les seules limites dures sont les portées, la liste d'adresses, le plafond quotidien et l'approbation. Choisir la clé comme si l'agent pouvait être convaincu de faire tout ce qu'elle permet.165- Pour ne montrer à un agent qu'une partie d'une boîte, lui donner un **alias** (vue restreinte), pas l'adresse principale.166- Les approbations se traitent dans **Administration → Approbations** (clé d'accès exigée pour approuver) ; elles expirent après 7 jours.167168### 3.5 Applications natives du propriétaire (macOS, iOS)169170Le webmail et les applications natives SP Mail utilisent la session du propriétaire (clés d'accès), pas une clé d'API. Une *autre* application native qui veut seulement envoyer une notification peut utiliser une clé restreinte, rangée dans le trousseau — voir le client Swift ([§4.3](#43-swift)). Une application distribuée à d'autres personnes ne doit jamais embarquer de clé : elle passe par son propre serveur.171172---173174## 4. SDK175176Les trois offrent les mêmes comportements : erreurs typées (statut, code, message, détails, identifiant de requête), clé d'idempotence automatique sur les créations, reprises sûres (429 avec `Retry-After`, 502/503/504 et pannes réseau, uniquement pour les requêtes idempotentes ou porteuses d'une clé d'idempotence), pagination par curseur, attente de l'état final d'un envoi, vérification de la signature des webhooks. Aucun ne journalise la clé.177178### 4.1 TypeScript179180```ts181import { SPMail, PermissionDeniedError } from "@spboucher/spmail"182183const mail = new SPMail({ apiKey: process.env.SPMAIL_API_KEY! })184185const sent = await mail.messages.send({ from: "notifications@spboucher.ai", to: ["simon@spboucher.ai"], subject: "Rapport prêt", text: "Le rapport hebdomadaire est prêt." })186const final = await mail.waitForDelivery(sent.id) // delivered | bounced | failed | cancelled187188for await (const m of mail.messages.iterate({ folder: "inbox", unread: true })) console.log(m.subject)189190try { await mail.messages.get(id) } catch (e) { if (e instanceof PermissionDeniedError) { /* e.code, e.details */ } }191```192193### 4.2 Python194195```python196from spmail import SPMail, NotFoundError197198mail = SPMail() # SPMAIL_API_KEY199sent = mail.messages.send(from_="notifications@spboucher.ai", to=["simon@spboucher.ai"], subject="Rapport prêt", text="…")200final = mail.wait_for_delivery(sent["id"], timeout=60)201202for m in mail.messages.iterate(folder="inbox", unread=True):203 print(m["subject"])204```205206### 4.3 Swift207208```swift209import SPMailClient210211let mail = try SPMailClient(apiKey: keyFromKeychain)212let sent = try await mail.send(SendRequest(from: "notifications@spboucher.ai", to: ["simon@spboucher.ai"], subject: "Sauvegarde terminée", text: "42 Go en 12 min."))213if sent.status == .pendingApproval { /* rien n'est parti : approbation requise */ }214let unread = try await mail.listUnread(limit: 10)215```216217### 4.4 Sans SDK218219L'API est du JSON sur HTTPS : `curl` ou n'importe quel client HTTP convient. Reprendre alors à la main ce que font les SDK : en-tête `Idempotency-Key` sur chaque `POST` qui crée ou envoie, reprise sur 429 (attendre `Retry-After`) et 5xx avec la **même** clé, jamais de reprise aveugle d'un `POST` sans clé.220221---222223## 5. Recevoir des webhooks224225Pour réagir à une réception ou connaître le sort d'un envoi sans interroger l'API en boucle.2262271. Créer le webhook avec la clé de l'application (`mail.webhooks.manage`) ; le **secret** (`whsec_…`) n'est montré qu'une fois.2282. L'URL doit être en `https` sur le port 443 et résoudre vers des adresses publiques. Pour un récepteur interne à la grappe, un administrateur ajoute son `hôte:port` exact à la liste d'autorisation interne (Administration, ou `POST /api/admin/webhook-allowlist`).2293. Vérifier la signature sur le **corps brut**, refuser hors fenêtre de 5 minutes, dédoublonner sur l'identifiant d'événement, répondre 2xx en moins de 10 s et traiter ensuite.230231```ts232const hook = await mail.webhooks.create({ name: "wallet-suivi", url: "https://wallet.spboucher.ai/hooks/spmail", events: ["message.delivered", "message.bounced", "message.failed"] })233// hook.secret → à ranger tout de suite dans les secrets de l'application234```235236```ts237// Récepteur Fastify (TypeScript)238import { constructWebhookEvent } from "@spboucher/spmail"239240app.addContentTypeParser("application/json", { parseAs: "buffer" }, (_req, body, done) => done(null, body)) // garder les octets bruts241app.post("/hooks/spmail", async (req, reply) => {242 let event243 try {244 event = await constructWebhookEvent({ payload: req.body as Buffer, header: req.headers["spmail-signature"] as string, secret: process.env.SPMAIL_WEBHOOK_SECRET! })245 } catch { return reply.code(400).send() }246 if (await dejaVu(event.id)) return reply.code(204).send() // livraison « au moins une fois »247 if (event.type === "message.bounced" || event.type === "message.failed") await signalerEchec(event.data)248 return reply.code(204).send()249})250```251252```python253# Récepteur Flask (Python)254import os, spmail255256@app.post("/hooks/spmail")257def hook():258 try:259 event = spmail.construct_event(request.get_data(), request.headers.get("SPMail-Signature"), os.environ["SPMAIL_WEBHOOK_SECRET"])260 except spmail.SignatureVerificationError:261 return "", 400262 file_attente.put(event) # dédoublonner sur event["id"], traiter hors requête263 return "", 204264```265266```swift267// Récepteur Swift (Vapor, Hummingbird…) : même vérification268guard SPMailWebhook.verify(payload: rawBody, header: request.headers["SPMail-Signature"].first, secret: secret) else { return .badRequest }269```270271Les charges ne contiennent par défaut que des identifiants, adresses, dates et états — ni sujet, ni corps. Avec `include_content: true` (clé avec `mail.read`), `message.received` porte en plus sujet et aperçu ; le corps se lit par `GET /messages/{id}`. Un échec est réessayé après 1 min, 5 min, 30 min, 2 h, 6 h et 24 h ; l'historique et le rejeu sont dans `webhooks.deliveries`. Faire tourner le secret : `webhooks.update(id, { rotate_secret: true })`.272273---274275## 6. Agents IA (MCP)276277`packages/mcp` est un serveur MCP en stdio : Claude Code (ou tout client MCP) le lance, il parle à l'API avec la clé reçue par l'environnement. **Il a exactement les droits de la clé**, rien de plus : pas d'accès à la base ni au serveur de courrier.278279```bash280cd packages/sdk-ts && pnpm install --ignore-workspace281cd ../mcp && pnpm install --ignore-workspace && pnpm build # → packages/mcp/dist/index.js282283claude mcp add spmail --env SPMAIL_API_KEY=spm_xxxxxxxxxx_… -- node /chemin/absolu/vers/sp-mail/packages/mcp/dist/index.js284# agent de lecture : ajouter --env SPMAIL_MCP_READONLY=1285```286287Forme JSON (`.mcp.json`, Claude Desktop) :288289```json290{ "mcpServers": { "spmail": { "command": "node", "args": ["/chemin/absolu/vers/sp-mail/packages/mcp/dist/index.js"],291 "env": { "SPMAIL_API_KEY": "${SPMAIL_API_KEY}", "SPMAIL_MCP_READONLY": "1" } } } }292```293294Ce que l'agent obtient : `spmail_list_accounts`, `spmail_list_messages`, `spmail_search`, `spmail_get_message`, `spmail_get_thread`, `spmail_list_attachments`, `spmail_download_attachment`, `spmail_delivery_status`, `spmail_list_templates` (lecture) ; `spmail_create_draft`, `spmail_send`, `spmail_send_template`, `spmail_reply`, `spmail_forward`, `spmail_archive`, `spmail_mark_read`, `spmail_move` (écriture). Les outils dont la clé n'a pas la portée ne sont pas enregistrés ; `SPMAIL_MCP_READONLY=1` retire tous les outils d'écriture.295296Garde-fous (détail dans le [README du paquet](../packages/mcp/README.md#security-model)) :297298- le contenu des courriels (sujets, noms, corps, liens, pièces jointes) est rendu comme **donnée non fiable** sous une clé `untrusted`, précédé d'un avertissement fixe ; le HTML est converti en texte, les caractères invisibles retirés, les liens montrés avec leur vraie destination ;299- rien de ce que contient un courriel n'est exécuté, suivi ou ouvert ;300- chaque outil d'envoi redit l'expéditeur et les destinataires et dit en clair si le message est parti ;301- destinataire externe + politique `approval` : l'outil répond « NOT SENT », le message attend dans **Administration → Approbations**, et le serveur ne réessaie jamais ;302- pas de suppression définitive, pas de gestion d'adresses ni de clés, pas de pièce jointe sortante.303304---305306## 7. Exploitation307308**Rotation.** Depuis l'écran Administration → Clés d'API (ou `POST /api/admin/api-keys/{id}/rotate` avec `grace_seconds`, 7 jours au plus ; réauthentification exigée) : une nouvelle clé reprend les mêmes réglages et les webhooks de l'ancienne ; l'ancienne est révoquée tout de suite, ou à la fin du délai de grâce — le temps de redéployer l'application avec le nouveau jeton. Faire tourner à intervalle régulier, et aussitôt qu'un jeton a pu fuir (journal, capture d'écran, dépôt).309310**Révocation.** `cli key-revoke <préfixe>` ou le bouton de l'écran des clés : effet à la requête suivante (`401 key_revoked`), sans réauthentification — révoquer ne fait que réduire ce qui peut arriver. Les webhooks d'une clé révoquée ne reçoivent plus rien. Les envois déjà remis au serveur de courrier suivent leur cours ; ceux qui sont programmés ou en attente d'approbation échouent à la soumission (la clé est revérifiée à ce moment-là).311312**Plafonds.**313314| Plafond | Défaut | Dépassement |315|---|---|---|316| requêtes par minute et par clé (`rate_per_minute`) | 60 | `429 rate_limited` + `Retry-After` — les SDK attendent et réessaient |317| envois par jour UTC et par clé (`daily_send_limit`) | 200 | `429 daily_send_limit_exceeded` (`details: {limit, used}`) — jamais réessayé |318| serveur de courrier, par couple domaine expéditeur → destinataire | ≈ 25 / heure | le destinataire finit `failed` (`452 4.4.5`) |319| destinataires par message · messages par lot · pièces jointes | 100 · 50 · 30 (50 Mo chacune) | `400` |320321Les en-têtes `X-RateLimit-Limit`, `-Remaining`, `-Reset` accompagnent chaque réponse authentifiée par clé. Le compteur par minute est en mémoire (il repart avec le processus) ; le plafond quotidien, les files d'envoi, les envois programmés et les livraisons de webhooks sont persistants.322323**Ce que prouve chaque état de remise** ([API.md §7](API.md#7-delivery-status-vocabulary)).324325| État | Ce qui est établi | Définitif |326|---|---|---|327| `queued` | accepté par SP Mail, pas encore remis au serveur de courrier (injoignable) ; SP Mail réessaie seul | non |328| `scheduled` | attend `send_at` | non |329| `pending_approval` | attend un administrateur ; **rien n'est parti** | non |330| `sent` | remis à la file sortante du serveur de courrier ; pas encore de réponse du serveur destinataire | non |331| `deferred` | échec temporaire (4xx) chez le destinataire ; nouvel essai automatique | non |332| `delivered` | le serveur du destinataire a accepté le message (2xx). **Pas une preuve d'arrivée en boîte de réception** : il peut encore être classé en indésirable ou rejeté plus tard par un avis de non-remise, qui arrive alors comme un courriel ordinaire | oui |333| `bounced` | rejet permanent (5xx) par le serveur du destinataire | oui |334| `failed` | jamais parti : refusé à la soumission, adresse ou clé devenue invalide, limite du serveur de courrier | oui |335| `cancelled` | annulé avant soumission (appelant, administrateur, approbation refusée ou expirée) | oui |336337Un message à plusieurs destinataires porte le pire de leurs états ; `delivered` signifie donc « accepté pour tous ».338339**Diagnostic.** Chaque réponse porte `X-Request-Id` (`req_…`, exposé par les SDK : `requestId`, `request_id`, `requestID`) : le citer en cas de problème. L'usage par clé (requêtes, erreurs, routes, envois par état) est dans Administration → Clés d'API ; il ne contient ni corps, ni jeton, ni identifiant de message. `GET /api/v1/health` (public) dit si la base et le serveur de courrier répondent.340341**Secrets.** Aucun jeton dans le dépôt, les exemples, les journaux ou les tickets : les exemples utilisent `spm_xxxxxxxxxx_…` et la variable `SPMAIL_API_KEY`. Un jeton collé par erreur quelque part se révoque, il ne se « nettoie » pas.342