Vai al contenuto

Funzionalità

Template

Layout email riutilizzabili e responsive, costruiti con i componenti MJML per funzionare in tutti i client di posta e personalizzati con Liquid.

L'editor visuale delle email, con l'albero della struttura, l'email e le impostazioni del pulsante selezionato

Panoramica

I template email si creano in un editor visuale a trascinamento. Usano il framework MJML, per la compatibilità tra client di posta e dispositivi, e Liquid per personalizzare con variabili come {{ contact.first_name }}. Ogni modifica crea una nuova versione, così resta traccia del contenuto già inviato. I template servono sia alle campagne broadcast sia alle notifiche transazionali.

Funzionalità dell’editor di template

  • Modifica a trascinamento
  • Layout responsive che si adattano agli schermi mobili
  • Blocchi pronti: intestazioni, piè di pagina, pulsanti, immagini e sezioni di contenuto
  • Impostazioni del brand: colori, font, loghi e stili
  • Un’anteprima dal vivo dell’email prima dell’invio

Creare un nuovo template

Nuovo modello apre una finestra in cui scegli il punto di partenza del template:

  • Galleria: 15 email pronte, divise per caso d’uso: codice di verifica, reimpostazione della password, conferma dell’iscrizione, invito al team, ricevuta di pagamento, conferma d’ordine, ordine spedito, carrello abbandonato, promozione, newsletter, annuncio di prodotto, invito a un evento, benvenuto, riconquista e conferma della disiscrizione. Fai clic su una per vederne l’anteprima su desktop o mobile, con la categoria, l’oggetto e le variabili che un invio deve fornire, poi su Usa questo modello.
  • I tuoi template: una copia di uno dei tuoi template, che mantiene la sua modalità di editor.
  • Semplice: un logo, un paragrafo e il piè di pagina.

Un modello della galleria arriva nella lingua predefinita del workspace, più una traduzione per ogni altra lingua del workspace coperta dalla galleria (inglese, francese, spagnolo, tedesco, catalano, portoghese brasiliano, giapponese e italiano). Nome, categoria, oggetto, testo di anteprima e dati di test sono già compilati, e il logo e il nome del workspace sostituiscono quelli d’esempio quando il workspace li ha; il mittente si sceglie in Impostazioni. Se apri la finestra da una newsletter, da una lista o da una notifica transazionale, mostra solo i modelli della categoria richiesta.

Le immagini della galleria sono segnaposto servite dalla tua istanza Notifuse, all’indirizzo https://<your API endpoint>/console/gallery/. Sostituiscile con le tue prima di inviare: un destinatario le vede solo finché la tua istanza è raggiungibile da Internet a quell’indirizzo.

Modalità dell’editor

Quando crei un template, scegli come scriverne l’email:

  • Visuale: l’editor a trascinamento, dove blocchi, stili e variabili Liquid si modificano direttamente.
  • Codice (MJML): scrivi tu l’MJML, con Liquid, in un editor di codice con anteprima dal vivo.

La modalità dell’editor si sceglie alla creazione del template e poi non si può più cambiare. Per passare un design all’altro editor, crea un nuovo template in quella modalità e copia il contenuto con il menu Importa / Esporta di ciascun editor:

  • Dal codice al visuale: nel template di codice, usa Esporta MJML; nel nuovo template visuale, usa Importa → MJML con quel file.
  • Dal visuale al codice: nel template visuale, usa Esporta → MJML; nel nuovo template di codice, usa Importa MJML con quel file.

Dopo la copia controlla l’anteprima. L’editor visuale rifiuta i componenti MJML che non supporta. Il Liquid posto tra i blocchi viene conservato: un file MJML esportato da Notifuse restituisce i suoi blocchi Liquid e le sue condizioni di visualizzazione, e in qualsiasi altro file MJML un passaggio con Liquid tra i blocchi (per esempio un ciclo {% for %} attorno a delle sezioni) diventa un blocco Liquid che contiene quel codice così com’è, da modificare poi come codice. Nella direzione opposta, scrivi il Liquid dentro i link con apici singoli ({{ link | append: '?ref=mail' }}): il testo tra virgolette doppie in quel punto non sopravvive all’esportazione.

Il nuovo template ha un proprio ID. Collega a questo i tuoi broadcast, le notifiche transazionali e le automazioni, poi elimina quello vecchio.

Titoli

I blocchi di testo dell’editor visuale contengono veri titoli, da Titolo 1 a Titolo 6, così gli screen reader possono elencare le sezioni di un’email e spostarsi dall’una all’altra (WCAG 2.2, criterio di successo 1.3.1). Scegli il livello della riga corrente nel menu stile del testo all’inizio della barra degli strumenti, oppure scrivi # (o ## , ### …) all’inizio di una riga. Il canvas mostra accanto a ogni titolo il suo livello; quel segno non fa parte dell’email.

Struttura: un titolo dovrebbe scendere al massimo di un livello rispetto a quello che lo precede (un H2 dopo un H1, non un H3). L’editor non rifiuta mai un livello, perché spostare o nascondere un blocco può cambiare l’ordine in seguito, ma segnala un livello che ne salta uno: accanto al livello nel menu, con un badge sul blocco Testo e in un riquadro Struttura dei titoli sopra l’anteprima. Quel riquadro legge l’email così come viene inviata, compresi i titoli scritti dai blocchi Liquid.

Aspetto: dimensione, spessore, interlinea e spaziatura di ogni livello, e se vuoi anche font e colore, si impostano una volta per template in Attributi predefiniti → Titoli. Notifuse li scrive su ogni titolo al momento dell’invio, così tutti i client di posta li mostrano. Un titolo prende il font e il colore del suo blocco Testo, a meno che il suo livello non ne imposti di propri.

L’editor conserva questi stili in un blocco mj-style del template, aggiunto con il primo titolo. Se modifichi a mano quel blocco, la sezione Titoli mostra un messaggio e smette di modificarlo. I template che avevano già dei titoli mantengono il loro aspetto finché non modifichi Titoli.

Libreria dei blocchi salvati

Nell’editor visuale, la scheda Libreria accanto a Struttura contiene i blocchi salvati nel workspace, mostrati come anteprime, dal più recente, con una ricerca e un filtro per sezioni e blocchi di contenuto. Sotto ci sono i blocchi di base: sezione, wrapper, testo, immagine, pulsante, divisore, spaziatore, social, HTML grezzo e Liquid.

Per aggiungere un blocco all’email:

  • Inserisci: passa sopra un blocco salvato e fai clic su Inserisci, oppure fai clic su un blocco di base. Il blocco va dopo quello selezionato (o alla fine dell’email se non è selezionato nulla) e diventa il blocco selezionato; la conferma propone di annullare. Quando la selezione non può accogliere il blocco, il suo tooltip dice cosa selezionare invece, per esempio una colonna per un testo.
  • Trascina: trascina un blocco salvato o di base sull’email. Una linea mostra dove finirà, oppure un riquadro tratteggiato per una colonna o un wrapper vuoti. Sopra un punto che non lo accoglie, un’etichetta spiega perché, come “Va dentro una colonna” per un testo rilasciato tra due sezioni. Tieni il puntatore vicino al bordo superiore o inferiore dell’email per farla scorrere, e premi Esc per annullare. I blocchi si trascinano solo sull’email, non sull’albero della struttura.

Per salvare un blocco, selezionalo e usa il pulsante di salvataggio nella sua barra degli strumenti. La finestra propone un nome tratto dal contenuto del blocco, oppure può sostituire un blocco salvato esistente dello stesso tipo. I blocchi salvati sono disponibili in tutti i template del workspace. Un template che contiene già un blocco salvato ne conserva una propria copia, che non cambia se sostituisci o elimini il blocco salvato. Dopo il salvataggio di un nuovo blocco, la libreria si apre su di esso.

Per gestire un blocco salvato, apri il menu … sulla sua scheda nella libreria. Il menu compare nell’editor aperto dalla pagina Template, per i membri che possono modificare i template:

  • Rinomina: scrivi il nuovo nome e premi Invio, oppure Esc per tenere quello vecchio.
  • Sostituisci con il blocco selezionato: prima seleziona nell’email un blocco dello stesso tipo.
  • Duplica: aggiunge una copia, con il nome del blocco seguito da “(copia)”.
  • Elimina: lo toglie dalla libreria per tutti i template del workspace.

I template che contengono già il blocco non cambiano.

La scheda Libreria dell'editor visuale, con i blocchi salvati mostrati come anteprime e Inserisci al passaggio del mouse

Anche i pulsanti + dell’albero della struttura elencano tutti i blocchi salvati nella loro scheda Blocchi salvati. I blocchi che possono andare in quel punto vengono per primi, con un’anteprima al passaggio del mouse. Gli altri sono in grigio sotto “Non disponibile qui”, con il motivo, come “Va dentro una colonna”. I pulsanti + si aprono sull’ultima scheda che hai usato.

Utilizzo

In Notifuse i template servono per:

  • Campagne broadcast: campagne email di massa inviate alle tue liste di contatti
  • Notifiche transazionali: email automatiche attivate dalle azioni degli utenti
  • Email di double opt-in: inviate quando contatti anonimi si iscrivono a delle liste
  • Email di benvenuto: inviate quando i contatti confermano l’iscrizione a delle liste
  • Conferme di disiscrizione: inviate quando i contatti si disiscrivono
La pagina Template, con la categoria di ogni template, dove viene usato, il mittente e l'ultima versione

Eliminare un template

Eliminare un template lo toglie dall’elenco dei template e da tutti i selettori di template, ma Notifuse lo conserva con tutte le sue versioni: i messaggi già inviati sono stati generati da quelle versioni, e la cronologia dei messaggi e i report dei broadcast continuano a mostrarle.

Un template eliminato mantiene quindi il suo ID. La creazione di un nuovo template con lo stesso ID viene rifiutata, e templates.update dell’API risponde 404 per quell’ID. Dai al nuovo template un altro ID.

Eliminare un template, però, disattiva le versioni web delle email inviate con esso.

I template gestiti da un’integrazione, come le email di autenticazione di Supabase, non si possono eliminare.

Versione in testo semplice

Ogni email inviata da Notifuse contiene due versioni del contenuto: l’HTML e una versione in testo semplice generata a partire da esso, a meno che tu non scriva la tua. I client di posta solo testo, alcuni smartwatch e gli screen reader mostrano la versione testo, e i filtri antispam trattano meglio un’email con entrambe le versioni rispetto a una solo HTML.

Per impostazione predefinita la versione testo viene generata a ogni invio dall’HTML finale, quindi non c’è nulla da scrivere né da tenere aggiornato:

  • titoli e paragrafi mantengono le loro interruzioni di riga, gli elenchi diventano - item o 1. item;
  • un link diventa la sua etichetta seguita dall’URL tra parentesi, come Shop the sale (https://example.com/sale); un’immagine con link usa come etichetta il suo testo alt;
  • il contenuto nascosto (il testo di anteprima della casella di posta, gli elementi con stile display:none) e i pixel di tracciamento vengono esclusi.

I suoi link sono quelli dell’HTML, con lo stesso tracciamento dei click e gli stessi parametri UTM, decisi per ogni destinatario come per l’HTML, e un click dalla versione testo conta come qualsiasi altro. Se il tuo provider email riscrive i link per il proprio tracciamento dei click (SendGrid, Mailgun o Postmark, quando è attivo dalla loro parte), riscrive anche quelli della versione testo. Un’email il cui HTML non contiene alcun testo, come una sola immagine senza alt, viene inviata solo in HTML.

Per vederla prima dell’invio, apri la modalità Versione testo accanto a Modifica e Anteprima nell’editor visuale, la scheda Versione testo dell’editor MJML o la scheda Versione testo dell’anteprima del template. Mostrano il testo generato con i tuoi dati di test. Tramite l’API, templates.compile lo restituisce nel campo text.

Scrivere la propria versione

La versione automatica va bene per la maggior parte delle email. Per un testo diverso, per esempio più breve o senza i link ripetuti del layout, scegli Personalizzato nella modalità Versione testo (o nella scheda Versione testo dell’editor MJML) e scrivi tu il testo. Si parte dalla versione automatica, variabili comprese, così la modifichi invece di cominciare da zero.

  • Liquid funziona come nell’oggetto. {{ contact.first_name }}, le condizioni e i cicli vengono generati per ogni destinatario. Un {{ letterale va racchiuso in {% raw %}…{% endraw %}. Il testo viene verificato al salvataggio: un errore di sintassi Liquid, un tag {% include %} o {% render %} o un testo oltre i 64 KB vengono rifiutati con il motivo.
  • I suoi link vengono inviati così come sono scritti. I link di un testo personalizzato non hanno tracciamento dei click né parametri UTM. Il testo di un’email di marketing dovrebbe mantenere {{ unsubscribe_url }}, e quello di un’email di double opt-in {{ confirm_subscription_url }}; l’editor te lo ricorda e avvisa al salvataggio quando il link manca.
  • Non segue l’email. Un testo personalizzato non si aggiorna quando modifichi l’HTML. Ricomincia dalla versione automatica lo sostituisce con un nuovo punto di partenza; scegliere Automatica lo rimuove.
  • Un testo per lingua. Il testo che scrivi nell’editor principale è per la lingua predefinita. Ogni traduzione ha il suo, scritto nel proprio editor nella scheda Traduzioni; una lingua senza testo proprio riceve la versione automatica del proprio HTML, mai il testo della lingua predefinita.

Nota

Il punto di partenza conserva il Liquid scritto dentro i blocchi di testo. Conserva il testo di un blocco condizionale ma non la sua condizione, e le condizioni e i cicli posti tra i blocchi spesso non vengono ripresi, a seconda del layout. L’editor avvisa quando il punto di partenza contiene meno tag Liquid dell’email: controlla il testo e aggiungi a mano ciò che manca prima di salvare. Un testo personalizzato non ha condizioni di visualizzazione: il testo di un blocco condizionale arriva a tutti i destinatari, a meno che tu non lo racchiuda in un {% if %}.

Se un testo personalizzato non può essere generato al momento dell’invio, l’email parte con la versione automatica, e l’anteprima del template ne indica il motivo. Tramite l’API, il testo personalizzato è email.text del template (e translations.<language>.email.text); templates.compile lo accetta come text e indica in text_source se il testo restituito è custom o auto.

Blocchi condizionali

Un blocco dell’editor visuale può essere inviato solo ad alcuni destinatari: dagli una condizione di visualizzazione sui dati dell’email, come “order.total è maggiore di 100” o “contact.custom_string_1 uguale a vip”. I destinatari per cui la condizione non vale ricevono l’email senza il blocco.

Seleziona un blocco, poi usa + Condizione nella fascia Condizione di visualizzazione in cima alle sue impostazioni. Una condizione è un elenco di regole, ognuna composta da una variabile, un operatore e, per la maggior parte degli operatori, un valore. Scegli se devono valere tutte le regole o almeno una delle regole; una condizione può contenere fino a 20 regole.

Le condizioni si possono impostare su sezioni, wrapper, testi, immagini, pulsanti, divisori, spaziatori, blocchi social e blocchi HTML grezzo. Una condizione su una sezione o su un wrapper nasconde tutto ciò che contiene. Colonne e gruppi non possono averne, perché togliere una colonna altererebbe la larghezza delle altre; metti la condizione sulla sezione o sui blocchi dentro la colonna. Non può averne nemmeno un blocco che contiene un blocco Liquid: nasconderlo toglierebbe anche il blocco Liquid, che potrebbe contenere metà di un tag come {% if %} il cui {% endif %} si trova altrove. Sposta prima fuori il blocco Liquid. Per lo stesso motivo, l’editor non ti permette di mettere un blocco Liquid dentro un blocco che ha una condizione.

Variabili

Una variabile è un percorso senza parentesi graffe, come lo scriveresti dentro {{ }}: contact.first_name, order.total, order.items.size. .empty e .to_liquid non si possono usare in un percorso; per verificare una lista o un testo vuoti, usa è falso o vuoto. È disponibile ogni variabile dei dati dell’email: campi del contatto, il data di una chiamata all’API transazionale, i data feed. Le variabili assegnate con Liquid dentro l’email (un {% assign %} in un blocco Liquid o HTML grezzo) non lo sono, perché una condizione legge i dati con cui l’email viene inviata, non il suo contenuto.

Operatori

OperatoreVale quando la variabile
è veroè true, oppure il testo true
è falso o vuotoè false, vuota, fatta solo di spazi, oppure assente
è impostato / non è impostatoha un valore, oppure non ne ha: assente, null, un testo o una lista vuoti, un oggetto vuoto o un testo fatto solo di spazi (false e 0 sono impostati)
uguale a / non è uguale aè esattamente il testo del valore: vip non è uguale a VIP
contiene / non contieneper un testo, contiene il valore; per una lista, ha un elemento uguale al valore; per un oggetto, ha un campo con quel nome; un numero o un booleano non contiene nulla
è maggiore di, è maggiore o uguale a, è minore di, è minore o uguale aè un numero, o un testo che lo rappresenta ("150"), confrontato con il valore

Alcuni dettagli:

  • Variabili assenti: una regola su una variabile che manca dai dati è falsa, tranne è falso o vuoto, non è impostato, non è uguale a e non contiene, che valgono.
  • Numeri e booleani: uguale a 100 corrisponde anche al numero 100, e uguale a true corrisponde al booleano true. I confronti (è maggiore di e gli altri) richiedono come valore un numero con al massimo 15 cifre prima della virgola; una variabile che non è un numero li rende falsi.
  • Valori di testo: sono liberi, va bene qualsiasi carattere tranne i delimitatori Liquid {{, }}, {% e %}.

Verificare una condizione

L’editor delle condizioni mostra, per ogni regola e per la condizione intera, il risultato con i dati di test del template, e avvisa quando una variabile manca da quei dati. L’anteprima nasconde i blocchi che i tuoi dati di test nasconderebbero e dice quanti sono. Nell’albero dei livelli e sul canvas, un’icona segnala i blocchi che hanno una condizione.

Traduzioni ed esportazioni

Ogni traduzione ha il proprio contenuto, quindi le proprie condizioni: impostale anche nella traduzione. Reimposta traduzione copia anche le condizioni del contenuto predefinito.

Esporta → MJML scrive ogni condizione come Liquid attorno al suo blocco, così un template di codice creato dall’esportazione invia gli stessi blocchi. C’è una differenza: nel template di codice la condizione vede anche le variabili assegnate dal Liquid dell’email stessa, come un {% assign %} in un blocco Liquid o la variabile di un ciclo {% for %} attorno al blocco. Reimportando quel file nell’editor visuale, i blocchi ritrovano le loro condizioni: l’esportazione segna ogni condizione con un commento Liquid, che non produce alcun output. Un file esportato prima della versione 44.0 non ha questi segni: ogni condizione torna dentro un blocco Liquid, insieme al suo blocco.

L’MJML di un template di codice passa per intero da Liquid, e Liquid accetta al massimo 100 KB (102.400 byte) alla volta. Ogni condizione esportata aggiunge da qualche centinaio a qualche migliaio di caratteri di Liquid attorno al suo blocco, a seconda delle regole, quindi un’email con molte condizioni può superare il limite una volta esportata, e il suo template di codice non riesce più a compilare. Tieni un’email del genere nell’editor visuale, dove le condizioni non contano ai fini del limite.

Tramite l’API, un blocco di visual_editor_tree porta la sua condizione in display_condition:

{
  "type": "mj-section",
  "display_condition": {
    "match": "all",
    "rules": [
      { "variable": "order.has_image", "operator": "is_true" },
      { "variable": "order.total", "operator": "gt", "value": "100" }
    ]
  },
  "children": []
}

Gli operatori sono is_true, is_blank, is_present, is_absent, eq, neq, contains, not_contains, gt, gte, lt e lte, e match vale all o any. Una condizione su un blocco che non può averne una, o una condizione non valida, viene rifiutata con un 400.

Traduzioni

Un template può contenere una versione del contenuto per ogni lingua. Notifuse sceglie la versione al momento dell’invio in base al campo language del contatto, così un solo broadcast o una sola notifica transazionale servono tutte le lingue che hai scritto, senza diramazioni nelle tue automazioni o nelle chiamate API.

Attivare le lingue nel workspace

Le traduzioni sono proposte solo per le lingue attivate nel workspace. Apri Impostazioni → Generale, pannello Lingua e fuso orario:

  • Lingue supportate: le lingue in cui lavora questo workspace. Aggiungi tutte le lingue per cui intendi scrivere template; a una lingua che non compare qui non si può dare una traduzione.
  • Lingua predefinita: la lingua del contenuto principale di un template, e la versione che un contatto riceve quando nessun’altra corrisponde meglio. Ogni workspace ne ha esattamente una.

I codici di lingua sono codici ISO di due lettere come en, fr, de, es. La lingua predefinita deve essere una delle lingue supportate, e l’elenco deve contenerne almeno una.

Nota

Con una sola lingua supportata, l’editor di template non mostra alcun controllo per le traduzioni. La scheda Traduzioni compare non appena il workspace supporta più di una lingua.

Scrivere una traduzione

Quando crei o modifichi un template, l’editor ha due schede: Template, nella lingua predefinita del workspace, e Traduzioni, che elenca ogni altra lingua supportata. Apri una lingua per scriverne oggetto, testo di anteprima e corpo, con lo stesso editor visuale, la stessa modalità codice MJML e le stesse variabili Liquid della lingua predefinita. Mittente e reply-to si impostano una sola volta, sul template, e ogni traduzione viene inviata con quelli. Reimposta traduzione copia nella traduzione il contenuto della lingua predefinita come punto di partenza, sostituendo quello che c’era.

Una lingua senza traduzione viene saltata al momento dell’invio, quindi non devi tradurre un template in tutte le lingue supportate in una volta sola.

Quale versione riceve un contatto

Al momento dell’invio Notifuse legge il campo language del contatto:

  1. Se è vuoto, o è uguale alla lingua predefinita del workspace, il contatto riceve il contenuto predefinito.
  2. Se il template ha una traduzione per quella lingua, il contatto riceve quella traduzione.
  3. Altrimenti il contatto riceve il contenuto predefinito.

Il contenuto predefinito fa sempre da ripiego, quindi una traduzione mancante non lascia mai un contatto senza email. Imposta la lingua di un contatto all’importazione, tramite l’API (language su contacts.upsert) o da un modulo di iscrizione; vedi Contatti.

Per controllare una lingua specifica prima dell’invio, l’anteprima del template e la finestra dell’invio di prova hanno entrambe un selettore Lingua.

Nota

Self-hosted: aggiungere una lingua a un template, o modificare il contenuto di una traduzione esistente, richiede una chiave di licenza. Le traduzioni già salvate continuano a essere inviate in qualsiasi stato della licenza, la modifica del resto di un template che le contiene non viene mai rifiutata, e rimuovere una traduzione è sempre consentito. Notifuse Cloud include le traduzioni dei template a partire dal piano Starter (dettagli).

Sintassi Liquid

Notifuse usa Liquid per inserire contenuti dinamici nelle email. Le variabili vanno tra doppie parentesi graffe e vengono sostituite con i dati reali al momento dell’invio.

Nota

Liquid viene valutato nel template che scrivi, non nei tuoi dati. Un valore che arriva da un campo del contatto, da un data feed o da una chiamata API viene inserito come testo: se contiene {{ ... }} o {% ... %}, quel testo viene mostrato così com’è e non eseguito come Liquid. Metti i merge tag nel template e passa nei dati valori semplici.

L’HTML nei tuoi dati viene sottoposto a escape

Nell’HTML di un’email, ogni output ({{ }}, echo e cycle) viene sottoposto a escape: un valore appare come il testo che contiene, mai interpretato come HTML. Un contatto che scrive <a href="https://example.com"> come nome vede quei caratteri nell’email, non un link. L’oggetto e la versione testo non sono HTML, quindi non sono sottoposti a escape.

Quando un valore è HTML di proposito, come un data feed che restituisce un blocco di HTML, scrivilo con il filtro raw:

{{ global_feed.article_html | raw }}

Usa raw solo per dati che controlli tu. Su un campo del contatto, o su qualsiasi cosa che un modulo o un chiamante dell’API possono compilare, permette a quel valore di aggiungere link e markup alla tua email.

Alcuni output non vengono sottoposti a escape una seconda volta:

  • Già sottoposto a escape: {{ name | escape }} subisce l’escape una sola volta, anche quando è seguito da newline_to_br, strip o truncate. {{ bio | escape | newline_to_br }} mantiene le interruzioni di riga.
  • HTML catturato: il testo di un {% capture %} viene scritto così com’è: i suoi output hanno già subito l’escape al momento della cattura, e il resto è il markup del tuo template.

L’escape riguarda il testo e gli attributi HTML:

  • CSS e script: un valore scritto in un CSS (mj-style, un elemento <style>) o in uno script richiede raw e deve venire da dati di cui ti fidi, come le impostazioni del tuo brand, mai dai contatti.
  • Attributi tra virgolette: un output dentro il valore di un attributo è sicuro solo tra virgolette. Scrivi class="{{ value }}", non class={{ value }}.

Un errore Liquid blocca l’email

Quando Liquid non riesce a valutare una parte di un’email, l’email non viene inviata: l’invio fallisce con l’errore, e l’anteprima e l’invio di prova lo mostrano, così puoi correggere il template prima che arrivi a qualcuno. Vale per l’HTML, l’oggetto e la versione testo. In passato l’email partiva con dentro un testo Liquid error: ....

Le cause più comuni sono:

  • Un testo confrontato con un numero: {% if contact.custom_string_1 >= 10 %} fallisce quando il campo contiene "12" (comparison of String with 10 failed). Confronta un campo numerico, oppure confronta con un testo tra virgolette: {% if contact.custom_string_1 == "12" %}.
  • Un operatore sconosciuto: {% if x = 1 %} fallisce (Unknown operator =). Scrivi ==.
  • Un filtro che fallisce: {{ order.total | divided_by: order.count }} fallisce quando order.count vale 0 (divided by 0), e lo stesso vale per un filtro a cui manca un argomento, come {{ contact.first_name | replace }} (wrong number of arguments). Proteggi il valore: {% if order.count > 0 %}{{ order.total | divided_by: order.count }}{% endif %}.

Tramite l’API, transactional.send e broadcasts.sendToIndividual rispondono a un invio del genere con un 422 il cui error è l’errore Liquid.

Un campo mancante non è un errore: {{ contact.first_name }} non mostra nulla quando è vuoto, e {% if order.total > 50 %} è falso quando non c’è order. I blocchi condizionali non causano mai errori. Nei temi del blog, un errore viene ancora mostrato nella pagina.

Variabili del contatto

L’oggetto contact contiene il profilo completo del contatto, quindi qualsiasi campo del contatto si può usare per la personalizzazione:

Hello {{ contact.first_name }}!

Your account email: {{ contact.email }}
Full name: {{ contact.first_name }} {{ contact.last_name }}

Esempio di output:

Hello John!

Your account email: john.doe@example.com
Full name: John Doe

Variabili della lista

Per fare riferimento alle informazioni della lista di distribuzione:

You're subscribed to: {{ list.name }}
List ID: {{ list.id }}

Esempio di output:

You're subscribed to: Newsletter
List ID: newsletter

URL di sistema

Usa gli URL generati in anticipo per le azioni comuni:

<a href="{{ unsubscribe_url }}">Unsubscribe from this list</a>

Aprire questo link disiscrive subito il contatto dalla lista e mostra il centro notifiche. I client di posta possono anche mostrare un proprio pulsante di disiscrizione, grazie all’intestazione List-Unsubscribe che Notifuse aggiunge a ogni email inviata a una lista, tranne i broadcast che vanno anche ai contatti disiscritti della lista.

Per controllare questi link e l’intestazione prima dell’invio, scegli una Lista di distribuzione quando invii un’email di prova; una prova inviata da un broadcast ha già selezionata la lista del broadcast. La prova contiene allora i link di quella lista e, come il broadcast, l’intestazione List-Unsubscribe, e funzionano davvero: disiscriversi o confermare dalla prova, o un bounce o un reclamo segnalati su di essa, modificano l’iscrizione del destinatario di prova alla lista. Il campo Lista di distribuzione non è proposto per le notifiche transazionali, i cui invii reali non contengono link di lista. Senza una lista, i link di disiscrizione della prova non portano a nessuna lista reale e la prova non ha l’intestazione List-Unsubscribe.

Conferma dell’iscrizione

<a href="{{ confirm_subscription_url }}">Confirm your subscription</a>

Centro notifiche

<a href="{{ notification_center_url }}">Manage your preferences</a>

Preferenze di tracciamento delle email

<a href="{{ tracking_preferences_url }}">Choose what we track</a>
<a href="{{ tracking_optout_url }}">Stop tracking my opens and clicks</a>

Il primo apre la finestra del tracciamento email del centro notifiche; il secondo chiede al contatto di confermare in quella finestra, poi rifiuta il tracciamento di aperture e click. Vedi Tracciamento delle email.

Visualizza nel browser

{% if view_in_browser_url != blank %}
  <a href="{{ view_in_browser_url }}">View this email in your browser</a>
{% endif %}

Il link apre la versione web dell’email, per i destinatari il cui client di posta la mostra male. Nell’editor visuale, seleziona del testo, apri l’editor dei link e scegli il tipo di link Versione web dell’email.

  • Disponibile nei broadcast e nelle automazioni. Le email transazionali e di double opt-in lasciano la variabile vuota, a meno che una chiamata all’API transazionale non imposti view_in_browser_url nei propri dati. In un template condiviso con queste email, proteggi il link come sopra.
  • Solo dove viene usata. Solo le email il cui template usa la variabile hanno una versione web. Non esiste un’impostazione a livello di workspace.
  • L’email così come è stata inviata. La pagina è generata dalla versione del template e dai dati di quell’invio, nella lingua del contatto. Le modifiche successive al template non la cambiano.
  • Sulla pagina non si traccia nulla. Visualizzarla non registra alcuna apertura, e i suoi link non registrano click; mantengono i parametri UTM dell’invio. Con il tracciamento dei click attivo, il click sul link nell’email stessa conta come click, come qualsiasi altro link.
  • Disattivata con il template o con il contatto. Eliminare il template o eliminare il contatto fa rispondere alla pagina “This email is no longer available”.

Chiunque abbia il link può aprire la pagina, come per un’email inoltrata. Mostra ciò che mostra l’email, compresi i link di disiscrizione e del centro notifiche del contatto, quindi chi la possiede può disiscrivere quel contatto. La versione web di ogni email si apre al massimo 30 volte al minuto: non è pensata come link d’archivio pubblico.

Il link firma il dominio con cui è stato inviato, cioè il Custom Endpoint URL del tuo workspace o l’indirizzo API_ENDPOINT, e la pagina si apre lì e solo sull’indirizzo API_ENDPOINT. Così il dominio personalizzato di un altro workspace non può mostrare la tua email sotto il proprio indirizzo. Ecco cosa non copre:

  • L’indirizzo API_ENDPOINT apre la versione web di tutti i workspace, perché ogni link può ripiegare su di esso.
  • I workspace che condividevano già un dominio personalizzato prima della 44.0 mostrano lì le versioni web l’uno dell’altro.
  • Chiunque abbia il link può scaricare la pagina e pubblicarne una copia altrove, come con qualsiasi email ricevuta.
  • Per un dominio personalizzato si verifica solo che punti a Notifuse, non che appartenga al workspace che lo salva. Il workspace che salva per primo un dominio lo detiene; vedi Custom Endpoint URL.

Dopo che il tuo workspace cambia dominio personalizzato, i link inviati con il vecchio continuano a funzionare finché il vecchio dominio punta ancora a Notifuse, fino a quando un altro workspace non lo prende; da quel momento smettono di funzionare entro pochi minuti. Un reindirizzamento dal vecchio dominio li tiene in vita solo se porta all’indirizzo API_ENDPOINT, non al nuovo dominio personalizzato.

Dietro un reverse proxy, inoltra l’intestazione Host originale, oppure imposta X-Forwarded-Host con quel valore: quando questa intestazione è presente, la pagina viene valutata solo su di essa. Un proxy che sostituisce Host con il proprio indirizzo upstream, come notifuse:8080, fa rispondere a ogni versione web “This email is no longer available”. Uno che lo sostituisce con l’host di API_ENDPOINT disattiva la regola: ogni dominio personalizzato mostra allora le versioni web di tutti i workspace.

La pagina non esegue script ed è tenuta separata dalla console, anche se entrambe sono servite dallo stesso dominio.

Nell’anteprima di un template e in un’email di prova, il link apre una pagina che spiega che la versione web esisterà una volta inviata l’email a un contatto.

Nota

Le versioni web sono servite sotto /v/. Su un blog servito da un dominio personalizzato, una categoria con slug v non è raggiungibile: dalle un altro slug.

Variabili delle automazioni

Un’email inviata da un’automazione riceve anche:

  • {{ automation_id }} e {{ automation_name }}
  • {{ trigger_event }}: l’evento che ha avviato il percorso. {{ trigger_event.kind }} è il suo tipo (custom_event.cart_abandoned, list.subscribed, email.link_clicked…) e {{ trigger_event.occurred_at }} il momento in cui è avvenuto. Per un evento personalizzato, {{ trigger_event.name }}, {{ trigger_event.external_id }} e le sue proprietà, {{ trigger_event.properties.<key> }}.
{% if trigger_event.properties.items %}
  {% for item in trigger_event.properties.items %}
    {{ item.name }} × {{ item.quantity }}: {{ item.price }}
  {% endfor %}
{% endif %}

Un percorso avviato prima della versione 44 non ha trigger_event: proteggilo con {% if %}.

Esempio completo

Welcome {{ contact.first_name }}!

Thank you for subscribing to {{ list.name }}. We're excited to have you on board!

Your registered email: {{ contact.email }}

Manage Preferences: {{ notification_center_url }}

Don't want to receive these emails?
Unsubscribe here: {{ unsubscribe_url }}

Struttura dei dati disponibili

I template possono usare questa struttura di dati:

{
  "contact": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "list": {
    "id": "newsletter",
    "name": "Newsletter"
  },
  "unsubscribe_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=unsubscribe&email=john.doe@example.com&lid=newsletter&lname=Newsletter&wid=workspace123&mid=msg_123&email_hmac=abc123",
  "confirm_subscription_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=confirm&email=john.doe@example.com&lid=newsletter&lname=Newsletter&wid=workspace123&mid=msg_123&email_hmac=abc123",
  "notification_center_url": "https://your_notifuse_endpoint.your_website.com/notification-center?email=john.doe@example.com&email_hmac=abc123&wid=workspace123",
  "tracking_preferences_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=tracking&email=john.doe@example.com&email_hmac=abc123&wid=workspace123",
  "tracking_optout_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=tracking_optout&email=john.doe@example.com&email_hmac=abc123&wid=workspace123",
  "view_in_browser_url": "https://your_notifuse_endpoint.your_website.com/v/ODkyY2Q..."
}

Differenze rispetto a Shopify Liquid

Notifuse genera il Liquid con liquidgo, che segue Shopify Liquid 5.11. Alcuni comportamenti differiscono di proposito, perché i tuoi dati arrivano da JSON e le tue email le leggono delle persone:

  • Il testo vuoto è falso: {% if contact.first_name %} salta un contatto con il nome vuoto. In Shopify Liquid sono falsi solo nil e false.
  • I numeri dei tuoi dati sono decimali: con order.total impostato a 1999, {{ order.total | plus: 1 }} mostra 2000 (non 2000.0), e {{ order.total | divided_by: 100 }} mantiene i decimali e mostra 19.99. Aggiungi | floor per tenere solo la parte intera.
  • In un tema del blog, un errore di filtro non mostra nulla: {{ 1 | divided_by: 0 }}, un base64_decode non valido o un filtro con troppi argomenti non mostrano nulla, invece di Liquid error: .... In un’email, blocca l’email (vedi Un errore Liquid blocca l’email).
  • Le liste si mostrano tra parentesi quadre: {{ contact.custom_json_1.tags }} mostra ["vip", "early"]. Usa {{ contact.custom_json_1.tags | join: ", " }} per elencarle.
  • date legge come UTC una data scritta senza fuso orario, e un numero come timestamp Unix.

Nei temi del blog, che sono gli unici template con i partial, {% render %} accetta il nome di un template tra virgolette come in Shopify Liquid 5.11 ({% render 'footer' %}); le email lo rifiutano. {% snippet %} non è supportato.