SPB Git

Repository Public

templates-api.md 4.2 KB

# 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

jsonc
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

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

Files main
Menu

Theme