SP Mail — studio de modèles : API de session
Routes pour le webmail et les apps (session cookie ou jeton natif ; non-GET : Origin + X-SPMail: 1 côté web). Un modèle appartient à un utilisateur ; celui d'un autre répond 404.
Implémentation : server/src/templates.ts, templates-ai.ts, template-sanitize.ts. Tests : server/src/template-sanitize.test.ts, tests/integration/templates.test.ts.
Objets
Template {
"id": "uuid", "name": "…", "category": "transactional|notification|newsletter|announcement|personal|invitation|receipt|security|other",
"subject": "Bonjour {{first_name}}", "preheader": "…",
"variables": [{ "name": "first_name", "description": "…", "example": "Zoé", "required": true }],
"brand": { "name"?: "…", "accent"?: "#4f46e5", "logo_url"?: "https://…", "tone"?: "…", "footer"?: "…", "website"?: "https://…" },
"source": "manual|ai", "ai_model": "claude-opus-5-5"|null, "design_notes": "…", "version": 3,
"created_at": "…", "updated_at": "…", "size_bytes": 14230,
// seulement hors liste :
"html": "<!DOCTYPE html>…", "text": "…", "ai_brief": "…"|null
}Variables : {{nom}}, nom = ^[a-z][a-z0-9_]{0,39}$. À l'enregistrement, le HTML est assaini (scripts, cadres, formulaires, gestionnaires, URL non http(s)/mailto, @import, url() non https retirés ; <style>, requêtes média, mode sombre et commentaires conditionnels Outlook conservés) et la liste variables est réalignée sur les variables réellement présentes dans l'objet, l'aperçu, le HTML et le texte.
Routes
| Route | Corps → Réponse |
|---|---|
GET /api/templates |
→ {templates: Template[] (sans html/text), ai: {configured, model}, categories: string[]} |
POST /api/templates |
{name, html, category?, subject?, preheader?, text?, variables?, brand?} → Template |
GET /api/templates/:id |
→ Template |
PUT /api/templates/:id |
champs partiels + note? → Template (toute modification de contenu archive la version précédente ; un renommage seul non) |
DELETE /api/templates/:id |
→ {ok} (archivage) |
POST /api/templates/:id/unarchive |
→ Template (annule un archivage de moins de 30 jours) |
POST /api/templates/:id/duplicate |
→ Template |
GET /api/templates/:id/versions |
→ [{version, subject, note, created_at, size_bytes}] (50 dernières) |
GET /api/templates/:id/versions/:n |
→ {version, subject, preheader, html, text, variables, note, created_at} |
POST /api/templates/:id/versions/:n/restore |
→ Template (nouvelle version) |
POST /api/templates/:id/render |
{values?: {nom: "valeur"}, use_examples?: true} → {subject, preheader, html, text, missing: string[]} — valeurs échappées ; une valeur placée dans href/src doit être une URL http(s)/mailto, sinon # |
POST /api/templates/preview |
brouillon non enregistré {html, subject?, preheader?, text?, variables?, values?} → rendu + variables réalignées + sanitized_html |
POST /api/templates/generate |
`{brief (8–6000 car.), language: "fr" |
GET /api/templates/ai/usage |
→ {last_30_days: {generations, input_tokens, output_tokens}, model, configured} |
Flux de generate
event: start data: {"model":"claude-opus-5-5","revising":false}
event: progress data: {"chars":1234} (tous les ~400 caractères ; des lignes « : ping » toutes les 15 s)
event: done data: {"template": Template, "usage": {"input_tokens","output_tokens","model","seconds"}}
event: error data: {"code":"ai_not_configured|ai_refused|ai_rate_limited|ai_output_truncated|ai_invalid_output|ai_unreachable|ai_error|cancelled","message":"…"}Durée observée : 60 à 150 s. Sans base_template_id un nouveau modèle est créé ; avec, le modèle existant reçoit une nouvelle version (retouche décrite par brief). Fermer la connexion annule la génération. Limite : 30 générations par heure et par utilisateur ; 503 ai_not_configured (JSON, hors flux) si aucune clé n'est configurée.
Seuls le brief, la marque et, pour une retouche, le modèle de base sont envoyés à l'API d'Anthropic — jamais de contenu de boîte aux lettres.