Guida a Handlebars

I modelli Frontmail usano la sintassi Handlebars nel corpo HTML, nella versione testuale, nell’oggetto e nei campi dei destinatari. Frontmail esegue Handlebars in un ambiente isolato e bloccato: esistono solo gli helper elencati in questa pagina, i partial non sono disponibili e ogni valore viene sottoposto a escaping.

Variabili

<p>Ciao {{name}},</p>
<p>la tua prenotazione per il {{booking.date}} è confermata.</p>   {{!-- oggetto annidato --}}
<p>{{default company "(nessuna azienda)"}}</p>                     {{!-- valore di riserva --}}

Un valore mancante viene generato come stringa vuota. Usa {{!-- … --}} per i commenti che non devono mai arrivare nell’email.

Condizioni

{{#if newsletter}}
  <p>Grazie per l'iscrizione!</p>
{{else}}
  <p>Puoi iscriverti in qualsiasi momento.</p>
{{/if}}

{{#unless paid}}<p>Il pagamento è in attesa.</p>{{/unless}}

{{#if (eq topic "support")}}<p>Il nostro supporto ti risponderà entro un giorno.</p>{{/if}}
{{#if (and vip (gt total 1000))}}<p>🎁 Spedizione gratuita</p>{{/if}}
{{#if (or (eq country "IT") (eq country "SM"))}}<p>Spedizione gratuita</p>{{/if}}

{{#if}} considera falsi false, 0, "", null, i valori mancanti e le liste vuote.

Cicli

Usa un parametro di tipo list con itemFields:

<table>
  {{#each items}}
    <tr>
      <td>{{@index}}</td>
      <td>{{title}}</td>
      <td>{{qty}} × {{formatMoney price ../currency}}</td>
    </tr>
  {{else}}
    <tr><td colspan="3">Nessun articolo.</td></tr>
  {{/each}}
</table>

Dentro {{#each}}, this è l’elemento corrente, sono disponibili @index (da 0), @first e @last, e ../ raggiunge il contesto padre. {{#with customer}}…{{/with}} cambia contesto e {{lookup map key}} legge una chiave dinamica.

Helper

Helper	Esempio	Risultato
formatDate value [style] [timeZone=…] [locale=…]	{{formatDate arrival "long"}}	October 1, 2026 / 1 ottobre 2026
formatNumber value [decimals=n]	{{formatNumber 1234.5 decimals=2}}	1,234.50 / 1.234,50
formatMoney amount currency [minor=true]	{{formatMoney 49 "EUR"}} · {{formatMoney 4900 "EUR" minor=true}}	€49.00 / 49,00 €
uppercase value	{{uppercase code}}	ABC123
lowercase value	{{lowercase email}}	giulia@example.com
default value fallback…	{{default nickname name "amico"}}	il primo valore non vuoto
eq a b · ne a b	{{#if (eq status "paid")}}	uguaglianza non stretta (1 è uguale a "1")
gt a b · lt a b	{{#if (gt qty 10)}}	confronto numerico
and a b … · or a b … · not a	{{#if (and a (not b))}}	operazioni booleane (i valori vuoti sono falsi)
json value	{{json items}}	testo JSON (con escaping), utile per il debug
nl2br value	{{nl2br message}}	testo con escaping in cui gli a capo diventano <br>

Stili di formatDate: date, datetime, time, short, long, full, iso. La lingua dell’output segue la lingua in cui viene inviata l’email – la lingua predefinita del modello o la traduzione scelta; puoi sovrascriverla per una singola chiamata con locale="it". Gli orari usano il fuso orario dell’organizzazione, a meno che tu non passi timeZone="Europe/Rome".

Chiamare qualsiasi altro helper è un errore di compilazione, mostrato nei controlli del modello.

Variabili di sistema

Variabile	Valore
{{frontmail.message_id}}	L’ID del messaggio, ad es. msg_01J9Z3K7Q2: utile come numero di riferimento.
{{frontmail.sent_at}}	Timestamp ISO della generazione, ad es. 2026-09-24T10:11:05.000Z. Da combinare con formatDate.
{{frontmail.origin}}	L’Origin della richiesta dal browser (ad es. https://example.com), vuoto per gli invii lato server.

frontmail è riservato: non puoi definire un parametro con questo nome.

Escaping e il tipo html

Frontmail applica l’escaping HTML a ogni output, comprese le forme {{{triple}}} e {{& ampersand}}. Un visitatore che scrive <a href="…">clicca</a> nel tuo modulo vedrà esattamente quel testo nell’email, non un link.

Quando hai davvero bisogno di markup dai parametri (ad esempio testo formattato dal tuo CMS), dichiara il parametro con il tipo html. Il suo valore viene ripulito in base a un elenco di elementi consentiti:

• tag: a, b, strong, i, em, u, s, p, br, div, span, h1–h6, ul, ol, li, blockquote, pre, code, hr, img, table e le sue parti, small, sub, sup, center, font;
• link: http, https, mailto, tel; immagini: http, https, cid;
• stili inline: colori, peso/stile/dimensione del carattere, interlinea, allineamento/decorazione del testo, margin, padding, width, height, max-width;
• tutto il resto (script, iframe, moduli, gestori di eventi, URL javascript:) viene rimosso.

Generalo con un semplice {{body_html}}: il valore ripulito viene inserito come markup.

Consiglio

Usa i parametri html solo per contenuti che controlli tu o che invii dal tuo server con una chiave privata. Per l’input degli utenti da un modulo pubblico, preferisci text con {{nl2br message}}.

Versione testuale

La versione testuale generata automaticamente viene prodotta dall’HTML generato (i link diventano testo (url), le tabelle diventano righe). Se modifichi la versione testuale a mano, viene generata con le stesse regole Handlebars, ma senza escaping HTML.