Paramètres et types

Chaque modèle a un schéma de paramètres. Il documente ce que le modèle attend, alimente le panneau des paramètres de l’éditeur, génère des types TypeScript et – surtout – valide chaque envoi. Une requête dont les paramètres ne correspondent pas échoue avec 422 invalid_template_params avant qu’aucun crédit ne soit utilisé.

Définir les paramètres

Chaque paramètre possède :

Champ	Signification
name	Identifiant utilisé dans le modèle, p. ex. customer_name. Lettres, chiffres, _ et - ; les noms à points comme customer.name sont autorisés et produisent des objets imbriqués. frontmail, this et root sont réservés.
label, description	Affichés dans le panneau des paramètres et dans les extraits de code générés.
type	L’un des types ci-dessous.
required	Valeur manquante (ou vide) → erreur.
default	Utilisée quand la valeur est manquante. Un paramètre avec une valeur par défaut n’échoue jamais comme obligatoire.
sampleValue	Utilisée par l’aperçu et les envois de test.
Règles	minLength / maxLength, min / max, pattern (regex), enumValues, itemFields – selon le type.

Dans l’éditeur, ouvrez Paramètres et ajoutez des paramètres avec Ajouter un paramètre, ou cliquez sur Détecter depuis le modèle : Frontmail parcourt le HTML, l’objet et les champs de destinataires à la recherche de {{placeholders}} et propose un paramètre pour chacun, y compris les champs d’éléments utilisés dans les blocs {{#each}}.

Types

Type	Accepte (JSON)	Conversion depuis des chaînes (formulaires)	Règles	Sortie dans le modèle
string	chaîne, nombre, booléen	converti en chaîne	minLength, maxLength, pattern	texte échappé
text	comme string	idem	idem	texte échappé ; utilisez {{nl2br x}} pour conserver les retours à la ligne
email	chaîne	espaces supprimés aux extrémités	doit être une adresse valide (254 caractères max.) ; maxLength, pattern	texte échappé
url	chaîne	espaces supprimés aux extrémités	http, https, mailto ou tel uniquement	texte échappé
number	nombre	"1234.5", "1 234,5" (les espaces et la virgule décimale sont acceptés)	min, max	nombre (utilisez formatNumber / formatMoney)
boolean	booléen, 1, 0	true/false, on/off, 1/0, yes/no, y/n, ano/ne (insensible à la casse)	–	true / false pour {{#if}}
date	chaîne ISO, millisecondes epoch	YYYY-MM-DD (conservée comme date calendaire) ou YYYY-MM-DDTHH:mm… (normalisée en ISO UTC)	–	chaîne (utilisez formatDate)
enum	chaîne ou nombre	espaces supprimés aux extrémités	la valeur doit figurer dans enumValues	texte échappé
html	chaîne	–	minLength, maxLength	HTML assaini, rendu comme balisage
list	tableau d’objets	une chaîne JSON est analysée	nombre d’éléments min, max (500 max. par défaut) ; chaque élément est validé selon itemFields	tableau pour {{#each}}

Autres règles :

• Une chaîne vide ou null compte comme manquante : required et default s’appliquent donc.
• Les paramètres de type chaîne sans maxLength sont limités à 50 000 caractères.
• L’ensemble des paramètres ne peut pas dépasser 256 ko de JSON ; au-delà, l’envoi échoue avec payload_too_large.
• pattern doit correspondre à la valeur entière (il est ancré automatiquement), p. ex. [A-Z]{2}\d{4}.

Conversion des données de formulaire

sendForm() et POST /v1/send-form envoient du multipart/form-data, où chaque valeur est une chaîne. Frontmail les convertit selon les types déclarés, si bien que le même modèle fonctionne pour le JSON comme pour les formulaires :

<input name="guests" value="3">            <!-- number → 3 -->
<input name="price" value="1 299,50">      <!-- number → 1299.5 -->
<input type="checkbox" name="newsletter">  <!-- coché « on » → true ; non coché → manquant → default -->
<input type="date" name="arrival">         <!-- "2026-10-01" reste "2026-10-01" -->
<input type="hidden" name="items" value='[{"title":"Room","qty":1}]'> <!-- list → JSON analysé -->

Les champs de fichier deviennent des pièces jointes, pas des paramètres.

Paramètres inconnus et mode strict

Par défaut, les paramètres absents du schéma sont transmis au modèle (vous pouvez donc commencer à envoyer avant d’avoir terminé le schéma). Activez Paramètres stricts dans Sécurité → Protection contre les abus pour les refuser avec un problème unknown_param – recommandé pour les modèles utilisés avec la clé publique.

La réponse d’erreur

{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Invalid email address. message: Must be at least 10 characters.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        { "param": "email", "code": "invalid_email", "message": "Invalid email address." },
        { "param": "message", "code": "too_short", "message": "Must be at least 10 characters.", "meta": { "min": 10 } },
        { "param": "items[2].qty", "code": "too_small", "message": "Must be at least 1.", "meta": { "min": 1 } }
      ]
    }
  }
}

Codes de problème : required, invalid_type, too_short, too_long, too_small, too_big, invalid_format, invalid_email, invalid_url, invalid_enum, invalid_date, unknown_param, payload_too_large. Utilisez param pour afficher le message à côté du bon champ du formulaire ; meta contient la limite pour que vous puissiez traduire le message vous-même.

Échappement et type html

Chaque valeur est échappée en HTML au rendu – même entre {{{triples accolades}}}, que Frontmail traite comme des {{doubles accolades}}. Ainsi, personne ne peut injecter de balisage dans votre e-mail par le biais d’une clé publique. Si vous avez besoin de texte enrichi, déclarez le paramètre comme html : il passe par un assainisseur strict (uniquement balises de mise en forme, liens, tableaux et images ; pas de scripts, formulaires, iframes ni gestionnaires d’événements ; uniquement des styles en ligne sûrs). Détails dans le guide Handlebars.

Dans le tableau de bord

Consultez Éditeur de modèles pour les panneaux Paramètres et Données d’exemple.