SP Mail — intégrations (applications, grappe, agents IA)
Comment 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 (en anglais) et OPENAPI.yaml ; ce document ne le répète pas, il montre comment s'en servir.
Sommaire : 1 Principes · 2 Une clé par application · 3 Recettes par type d'application · 4 SDK · 5 Recevoir des webhooks · 6 Agents IA (MCP) · 7 Exploitation
| Paquet | Rôle | Documentation |
|---|---|---|
packages/sdk-ts — @spboucher/spmail |
SDK TypeScript (Node 20+, navigateurs, edge), sans dépendance | README |
packages/sdk-python — spmail |
SDK Python ≥ 3.10, bibliothèque standard seule | README |
packages/swift-example — SPMailClient |
client Swift d'exemple (macOS 15+, iOS 18+) | README |
packages/mcp — @spboucher/spmail-mcp |
serveur MCP (stdio) pour les agents IA | README |
Aucun de ces paquets n'est publié dans un registre : ils se construisent depuis ce dépôt.
1. Principes
- De service à service, en HTTPS. Une application appelle
https://mail.spboucher.ai/api/v1avecAuthorization: Bearer spm_…. Elle ne parle jamais au serveur de courrier (SMTP, JMAP) et n'a aucun mot de passe de boîte. - 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.
- 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.sendsur une adresse d'expédition : elle ne lit aucun courriel. - L'expéditeur est imposé par le serveur. L'en-tête
Fromest 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). - 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éponse202 pending_approval).denyl'interdit,allowle laisse partir. - 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'environnementSPMAIL_API_KEY, trousseau macOS/iOS, ou secrets du manifestemld.
2. Une clé par application
Cré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.
cli key-create <nom> --scopes mail.send --addresses notifications@spboucher.ai \
[--external allow|approval|deny] [--rate N] [--daily N] [--expires ISO] [--description "…"]
cli key-revoke <id de clé | spm_préfixe>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.
Vérifier ce qu'une clé peut faire, depuis l'application elle-même :
curl -s https://mail.spboucher.ai/api/v1/me -H "Authorization: Bearer $SPMAIL_API_KEY"
# → portées, adresses (can_send, read: full | restricted | none), plafonds, politique d'envoi externe, usage du jour| Besoin de l'application | Portées |
|---|---|
| envoyer des notifications | mail.send |
| envoyer avec pièces jointes | mail.send, mail.attachments.write |
| suivre ses envois par webhook | + mail.webhooks.manage |
| lire et chercher | mail.read, mail.search (+ mail.attachments.read) |
| classer (lu, étoile, archive, corbeille) | + mail.modify |
| préparer des brouillons | + mail.drafts |
À ne donner à aucune application courante : mail.admin, mail.delete, mail.addresses.manage, mail.aliases.manage.
Lecture : 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).
3. Recettes par type d'application
Les 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é.
3.1 Application de notifications seules — VQuant
VQuant envoie des alertes et des rapports au propriétaire ; elle ne lit rien.
cli key-create vquant --scopes mail.send --addresses notifications@spboucher.ai,alerts@spboucher.ai \
--external deny --rate 30 --daily 100 --description "VQuant : notifications et alertes"notifications@pour l'ordinaire (rapport prêt, tâche terminée),alerts@pour ce qui demande une action.--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.- Les deux adresses peuvent être de type
send_onlyounotification: personne ne leur répond. - Clé d'idempotence = identifiant métier de l'événement (
alert-<id>), pour qu'une reprise du processus ne double jamais une alerte.
# VQuant (backend Python)
from spmail import SPMail, SPMailError
mail = SPMail() # SPMAIL_API_KEY dans l'environnement du processus PM2
def alert(alert_id: str, title: str, body: str) -> None:
try:
sent = mail.messages.send(from_="alerts@spboucher.ai", to=["simon@spboucher.ai"], subject=title, text=body,
priority="high", headers={"X-App": "vquant"}, idempotency_key=f"alert-{alert_id}")
except SPMailError as e:
log.error("alerte non envoyée: %s %s (requête %s)", e.status, e.code, e.request_id)
raise
if sent["status"] not in ("sent", "delivered"):
log.warning("alerte %s : état %s (%s)", alert_id, sent["status"], sent.get("last_error"))3.2 Application de portefeuille — SP Wallet
Codes de vérification, confirmations d'opération : un seul expéditeur, des messages par modèle, aucun droit de lecture.
cli key-create sp-wallet --scopes mail.send --addresses wallet@spboucher.ai --external approval --rate 20 --daily 50- 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.
--daily 50borne les dégâts d'un emballement ou d'une clé volée ; au-delà :429 daily_send_limit_exceeded.- Un courriel de sécurité doit arriver : suivre l'état final (
waitForDelivery, ou webhookmessage.bounced/message.failed) et proposer un autre canal en cas d'échec. - Ne jamais mettre de secret durable (phrase de récupération, clé privée) dans un courriel.
// SP Wallet (backend TypeScript)
import { SPMail } from "@spboucher/spmail"
const mail = new SPMail({ apiKey: process.env.SPMAIL_API_KEY! })
export async function sendVerificationCode(to: string, firstName: string, code: string, attemptId: string) {
const sent = await mail.messages.send(
{ from: "wallet@spboucher.ai", to: [to], template_id: process.env.SPMAIL_TEMPLATE_CODE!, variables: { first_name: firstName, code } },
{ idempotencyKey: `wallet-code-${attemptId}` },
)
if (sent.status === "pending_approval") throw new Error("destinataire externe : en attente d'approbation, rien n'est parti")
const final = await mail.waitForDelivery(sent.id, { timeoutMs: 30_000 })
if (final.status !== "delivered") throw new Error(`code non remis : ${final.status}`)
}3.3 La grappe MacLustr
Les gardiens de la grappe (mld heal, sondes, sauvegardes) écrivent au propriétaire : cluster@ pour les comptes rendus, alerts@ pour les pannes.
cli key-create maclustr --scopes mail.send --addresses cluster@spboucher.ai,alerts@spboucher.ai --external deny --rate 30 --daily 150- 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é.
- 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. - 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). - Depuis un script shell,
curlsuffit :
curl -sS -X POST https://mail.spboucher.ai/api/v1/messages/send \
-H "Authorization: Bearer $SPMAIL_API_KEY" -H 'Content-Type: application/json' \
-H "Idempotency-Key: heal-$INCIDENT-$(date -u +%Y%m%d%H)" \
-d "$(jq -n --arg s "[$NODE] $TITLE" --arg t "$BODY" '{from:"alerts@spboucher.ai",to:["simon@spboucher.ai"],subject:$s,text:$t,priority:"high"}')"3.4 Agents IA
Un agent lit, cherche et prépare ; l'envoi reste derrière une approbation humaine. Il passe par le serveur MCP (§6), qui n'a que la clé.
# agent de lecture (tri, résumés) — lancer aussi le serveur MCP avec SPMAIL_MCP_READONLY=1
cli key-create agent-lecture --scopes mail.read,mail.search,mail.attachments.read --addresses contact@spboucher.ai
# agent rédacteur : lit, classe, prépare des brouillons qu'un humain envoie depuis le webmail
cli key-create agent-brouillons --scopes mail.read,mail.search,mail.attachments.read,mail.drafts,mail.modify --addresses contact@spboucher.ai
# agent expéditeur : l'interne part, tout envoi externe attend l'approbation du propriétaire
cli key-create agent-envoi --scopes mail.read,mail.search,mail.attachments.read,mail.drafts,mail.modify,mail.send \
--addresses contact@spboucher.ai --external approval --daily 50- 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. - Pour ne montrer à un agent qu'une partie d'une boîte, lui donner un alias (vue restreinte), pas l'adresse principale.
- Les approbations se traitent dans Administration → Approbations (clé d'accès exigée pour approuver) ; elles expirent après 7 jours.
3.5 Applications natives du propriétaire (macOS, iOS)
Le 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). Une application distribuée à d'autres personnes ne doit jamais embarquer de clé : elle passe par son propre serveur.
4. SDK
Les 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é.
4.1 TypeScript
import { SPMail, PermissionDeniedError } from "@spboucher/spmail"
const mail = new SPMail({ apiKey: process.env.SPMAIL_API_KEY! })
const sent = await mail.messages.send({ from: "notifications@spboucher.ai", to: ["simon@spboucher.ai"], subject: "Rapport prêt", text: "Le rapport hebdomadaire est prêt." })
const final = await mail.waitForDelivery(sent.id) // delivered | bounced | failed | cancelled
for await (const m of mail.messages.iterate({ folder: "inbox", unread: true })) console.log(m.subject)
try { await mail.messages.get(id) } catch (e) { if (e instanceof PermissionDeniedError) { /* e.code, e.details */ } }4.2 Python
from spmail import SPMail, NotFoundError
mail = SPMail() # SPMAIL_API_KEY
sent = mail.messages.send(from_="notifications@spboucher.ai", to=["simon@spboucher.ai"], subject="Rapport prêt", text="…")
final = mail.wait_for_delivery(sent["id"], timeout=60)
for m in mail.messages.iterate(folder="inbox", unread=True):
print(m["subject"])4.3 Swift
import SPMailClient
let mail = try SPMailClient(apiKey: keyFromKeychain)
let sent = try await mail.send(SendRequest(from: "notifications@spboucher.ai", to: ["simon@spboucher.ai"], subject: "Sauvegarde terminée", text: "42 Go en 12 min."))
if sent.status == .pendingApproval { /* rien n'est parti : approbation requise */ }
let unread = try await mail.listUnread(limit: 10)4.4 Sans SDK
L'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é.
5. Recevoir des webhooks
Pour réagir à une réception ou connaître le sort d'un envoi sans interroger l'API en boucle.
- Créer le webhook avec la clé de l'application (
mail.webhooks.manage) ; le secret (whsec_…) n'est montré qu'une fois. - L'URL doit être en
httpssur le port 443 et résoudre vers des adresses publiques. Pour un récepteur interne à la grappe, un administrateur ajoute sonhôte:portexact à la liste d'autorisation interne (Administration, ouPOST /api/admin/webhook-allowlist). - 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.
const hook = await mail.webhooks.create({ name: "wallet-suivi", url: "https://wallet.spboucher.ai/hooks/spmail", events: ["message.delivered", "message.bounced", "message.failed"] })
// hook.secret → à ranger tout de suite dans les secrets de l'application// Récepteur Fastify (TypeScript)
import { constructWebhookEvent } from "@spboucher/spmail"
app.addContentTypeParser("application/json", { parseAs: "buffer" }, (_req, body, done) => done(null, body)) // garder les octets bruts
app.post("/hooks/spmail", async (req, reply) => {
let event
try {
event = await constructWebhookEvent({ payload: req.body as Buffer, header: req.headers["spmail-signature"] as string, secret: process.env.SPMAIL_WEBHOOK_SECRET! })
} catch { return reply.code(400).send() }
if (await dejaVu(event.id)) return reply.code(204).send() // livraison « au moins une fois »
if (event.type === "message.bounced" || event.type === "message.failed") await signalerEchec(event.data)
return reply.code(204).send()
})# Récepteur Flask (Python)
import os, spmail
@app.post("/hooks/spmail")
def hook():
try:
event = spmail.construct_event(request.get_data(), request.headers.get("SPMail-Signature"), os.environ["SPMAIL_WEBHOOK_SECRET"])
except spmail.SignatureVerificationError:
return "", 400
file_attente.put(event) # dédoublonner sur event["id"], traiter hors requête
return "", 204// Récepteur Swift (Vapor, Hummingbird…) : même vérification
guard SPMailWebhook.verify(payload: rawBody, header: request.headers["SPMail-Signature"].first, secret: secret) else { return .badRequest }Les 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 }).
6. Agents IA (MCP)
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.
cd packages/sdk-ts && pnpm install --ignore-workspace
cd ../mcp && pnpm install --ignore-workspace && pnpm build # → packages/mcp/dist/index.js
claude mcp add spmail --env SPMAIL_API_KEY=spm_xxxxxxxxxx_… -- node /chemin/absolu/vers/sp-mail/packages/mcp/dist/index.js
# agent de lecture : ajouter --env SPMAIL_MCP_READONLY=1Forme JSON (.mcp.json, Claude Desktop) :
{ "mcpServers": { "spmail": { "command": "node", "args": ["/chemin/absolu/vers/sp-mail/packages/mcp/dist/index.js"],
"env": { "SPMAIL_API_KEY": "${SPMAIL_API_KEY}", "SPMAIL_MCP_READONLY": "1" } } } }Ce 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.
Garde-fous (détail dans le README du paquet) :
- 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 ; - rien de ce que contient un courriel n'est exécuté, suivi ou ouvert ;
- chaque outil d'envoi redit l'expéditeur et les destinataires et dit en clair si le message est parti ;
- destinataire externe + politique
approval: l'outil répond « NOT SENT », le message attend dans Administration → Approbations, et le serveur ne réessaie jamais ; - pas de suppression définitive, pas de gestion d'adresses ni de clés, pas de pièce jointe sortante.
7. Exploitation
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).
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à).
Plafonds.
| Plafond | Défaut | Dépassement |
|---|---|---|
requêtes par minute et par clé (rate_per_minute) |
60 | 429 rate_limited + Retry-After — les SDK attendent et réessaient |
envois par jour UTC et par clé (daily_send_limit) |
200 | 429 daily_send_limit_exceeded (details: {limit, used}) — jamais réessayé |
| serveur de courrier, par couple domaine expéditeur → destinataire | ≈ 25 / heure | le destinataire finit failed (452 4.4.5) |
| destinataires par message · messages par lot · pièces jointes | 100 · 50 · 30 (50 Mo chacune) | 400 |
Les 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.
Ce que prouve chaque état de remise (API.md §7).
| État | Ce qui est établi | Définitif |
|---|---|---|
queued |
accepté par SP Mail, pas encore remis au serveur de courrier (injoignable) ; SP Mail réessaie seul | non |
scheduled |
attend send_at |
non |
pending_approval |
attend un administrateur ; rien n'est parti | non |
sent |
remis à la file sortante du serveur de courrier ; pas encore de réponse du serveur destinataire | non |
deferred |
échec temporaire (4xx) chez le destinataire ; nouvel essai automatique | non |
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 |
bounced |
rejet permanent (5xx) par le serveur du destinataire | oui |
failed |
jamais parti : refusé à la soumission, adresse ou clé devenue invalide, limite du serveur de courrier | oui |
cancelled |
annulé avant soumission (appelant, administrateur, approbation refusée ou expirée) | oui |
Un message à plusieurs destinataires porte le pire de leurs états ; delivered signifie donc « accepté pour tous ».
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.
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.