Parametri e tipi

Ogni modello ha uno schema dei parametri. Documenta cosa si aspetta il modello, alimenta il pannello dei parametri nell’editor, genera i tipi TypeScript e – soprattutto – valida ogni invio. Una richiesta i cui parametri non corrispondono fallisce con 422 invalid_template_params prima che venga usato qualsiasi credito.

Definire i parametri

Ogni parametro ha:

Campo	Significato
name	Identificatore usato nel modello, ad es. customer_name. Lettere, cifre, _ e -; i nomi con il punto come customer.name sono consentiti e producono oggetti annidati. frontmail, this e root sono riservati.
label, description	Mostrati nel pannello dei parametri e negli snippet generati.
type	Uno dei tipi elencati sotto.
required	Valore mancante (o vuoto) → errore.
default	Usato quando il valore manca. Un parametro con valore predefinito non fallisce mai come required.
sampleValue	Usato dall’anteprima e dagli invii di prova.
Regole	minLength / maxLength, min / max, pattern (regex), enumValues, itemFields, a seconda del tipo.

Nell’editor apri Parametri e aggiungi parametri con Aggiungi parametro, oppure clicca Rileva dal modello: Frontmail analizza l’HTML, l’oggetto e i campi dei destinatari alla ricerca di {{segnaposto}} e propone un parametro per ciascuno, compresi i campi degli elementi usati dentro i blocchi {{#each}}.

Tipi

Tipo	Accetta (JSON)	Conversione da stringhe (moduli)	Regole	Output nel modello
string	stringa, numero, booleano	convertito in stringa	minLength, maxLength, pattern	testo con escaping
text	come string	come sopra	come sopra	testo con escaping; usa {{nl2br x}} per mantenere gli a capo
email	stringa	spazi rimossi	deve essere un indirizzo valido (max 254 caratteri); maxLength, pattern	testo con escaping
url	stringa	spazi rimossi	solo http, https, mailto o tel	testo con escaping
number	numero	"1234.5", "1 234,5" (sono accettati spazi e la virgola decimale)	min, max	numero (usa formatNumber / formatMoney)
boolean	booleano, 1, 0	true/false, on/off, 1/0, yes/no, y/n, ano/ne (senza distinzione tra maiuscole e minuscole)	–	true / false per {{#if}}
date	stringa ISO, millisecondi epoch	YYYY-MM-DD (mantenuta come data di calendario) o YYYY-MM-DDTHH:mm… (normalizzata in ISO UTC)	–	stringa (usa formatDate)
enum	stringa o numero	spazi rimossi	il valore deve essere in enumValues	testo con escaping
html	stringa	–	minLength, maxLength	HTML ripulito, inserito come markup
list	array di oggetti	una stringa JSON viene interpretata	min, max elementi (max predefinito 500); ogni elemento validato rispetto a itemFields	array per {{#each}}

Altre regole:

• Una stringa vuota o null conta come mancante, quindi si applicano required e default.
• I parametri stringa senza maxLength sono limitati a 50.000 caratteri.
• Tutti i parametri insieme possono occupare al massimo 256 kB di JSON; i payload più grandi falliscono con payload_too_large.
• pattern deve corrispondere all’intero valore (viene ancorato automaticamente), ad es. [A-Z]{2}\d{4}.

Conversione dai dati dei moduli

sendForm() e POST /v1/send-form inviano multipart/form-data, dove ogni valore è una stringa. Frontmail li converte in base ai tipi dichiarati, così lo stesso modello funziona sia con JSON sia con i moduli:

<input name="guests" value="3">            <!-- number → 3 -->
<input name="price" value="1 299,50">      <!-- number → 1299.5 -->
<input type="checkbox" name="newsletter">  <!-- selezionata "on" → true; non selezionata → mancante → default -->
<input type="date" name="arrival">         <!-- "2026-10-01" resta "2026-10-01" -->
<input type="hidden" name="items" value='[{"title":"Camera","qty":1}]'> <!-- list → JSON interpretato -->

I campi file diventano allegati, non parametri.

Parametri sconosciuti e modalità rigorosa

Per impostazione predefinita, i parametri che non sono nello schema vengono passati al modello (così puoi iniziare a inviare prima di completare lo schema). Attiva Parametri rigorosi in Sicurezza → Protezione dagli abusi per rifiutarli invece con un problema unknown_param: consigliato per i modelli usati con chiave pubblica.

La risposta di errore

{
  "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 } }
      ]
    }
  }
}

Codici dei problemi: 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. Usa param per mostrare il messaggio accanto al campo giusto del modulo; meta contiene il limite, così puoi tradurre il messaggio tu stesso.

Escaping e il tipo html

Ogni valore viene sottoposto a escaping HTML durante la generazione, anche dentro {{{triple graffe}}}, che Frontmail tratta come {{doppie graffe}}. In questo modo nessuno può iniettare markup nella tua email tramite una chiave pubblica. Se ti serve testo formattato, dichiara il parametro come html: passa attraverso un sanitizer rigoroso (solo tag di formattazione, link, tabelle e immagini; niente script, moduli, iframe o gestori di eventi; solo stili inline sicuri). Dettagli nella guida a Handlebars.

Nella dashboard

Consulta Editor dei modelli per i pannelli Parametri e Dati di esempio.