SPB Git

Repository Public

INTEGRATIONS.md 22.5 KB

# 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/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.
  • 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.send sur une adresse d'expédition : elle ne lit aucun courriel.
  • 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).
  • 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.
  • 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.

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

bash
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 :

bash
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.

bash
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_only ou notification : 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.
python
# 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.

bash
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 50 borne 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 webhook message.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.
ts
// 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.

bash
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, curl suffit :
bash
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é.

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

ts
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

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

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.

  1. Créer le webhook avec la clé de l'application (mail.webhooks.manage) ; le secret (whsec_…) n'est montré qu'une fois.
  2. 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).
  3. 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.
ts
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
ts
// 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()
})
python
# 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
swift
// 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.

bash
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=1

Forme JSON (.mcp.json, Claude Desktop) :

json
{ "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.

Files main
Menu

Theme