Tipi di variabili

 

Mailjet offre quattro tipi di variabili, ciascuna delle quali ha uno scopo diverso nel linguaggio per modelli. I tipi di variabili includono:

1. Data (statiche): utilizzate per i dati statici che non cambiano frequentemente. Si tratta generalmente di valori predefiniti.
2. Var (dinamiche): utilizzate per dati dinamici che possono cambiare in base a condizioni o input differenti.
3. Variabili MJ predefinite: sono predefinite da Mailjet e forniscono informazioni e funzionalità utili all'interno del linguaggio per modelli.
4. Strutture delle variabili di segmentazione: sono utilizzate per scopi di segmentazione complessi e non sono l'obiettivo principale di questo articolo.

In questo articolo ci concentreremo principalmente sui primi due tipi di variabili (data e var), soffermandoci brevemente anche su quelle predefinite.

I tipi di variabili più comuni sono data e var. Sebbene entrambe servano a sostituire una stringa segnaposto con un valore che cambia in modo dinamico, esse si distinguono per la modalità di utilizzo, per il modo in cui il valore viene fornito al sistema e per i tipi di messaggi in cui possono essere utilizzate.

Oltre alle variabili autonome, il linguaggio per modelli fornisce strumenti (funzioni) che consentono di incorporare le variabili in operazioni logiche e aritmetiche più complesse, nonché di influenzare la formattazione e la codifica. In questa guida esploreremo in particolare l'uso di funzioni come "set" e "FormatNumberLocale". Inoltre, esamineremo in dettaglio le dichiarazioni condizionali if e i cicli for.

 

Data

Il tipo di dati della variabile è versatile e può essere utilizzato sia nei messaggi di marketing sia in quelli transazionali. Questa flessibilità deriva dal fatto che non è richiesto all'utente di fornire un valore alla variabile segnaposto. Infatti, il sistema sostituisce automaticamente il valore in base agli oggetti delle proprietà del contatto.

Che si tratti di una campagna o di un'email transazionale, purché il messaggio sia diretto a un contatto esistente e il nome della variabile corrisponda a una proprietà del contatto, il sistema sarà in grado di elaborare la variabile data. Se il destinatario ha un valore assegnato a tale proprietà, questo verrà visualizzato al posto della variabile segnaposto.

 

Vediamo un esempio. Supponiamo di impostare la variabile [[data:country]] nel contenuto del mio messaggio e di inviarlo a uno dei miei contatti. In questo contesto, sono possibili due risultati:

1. Se il contatto ha un valore impostato per la proprietà "country", riceverà il messaggio con la variabile [[data:country]] sostituita con il valore corrispondente.
2. Se il contatto non ha un valore impostato per la proprietà "country", riceverà il messaggio senza alcuna sostituzione della variabile [[data:country]]. Tuttavia, la variabile stessa non verrà visualizzata come elemento del linguaggio per modelli nella versione finale del messaggio.

Come esempio concreto, consideriamo due contatti: user1@domain.tld, che ha un valore impostato per la proprietà "country" equivalente a "France", e user2@domain.tld, che non ha un valore impostato per la proprietà "country".

Se invio a entrambi lo stesso messaggio contenente la frase:

"Ciao, come vanno le cose in [[data:country]] dopo la pandemia?"

 

I due contatti visualizzeranno contenuti diversi:

• user1@domain.tld visualizzerà: "Ciao, come vanno le cose in Francia dopo la pandemia?"
• user2@domain.tld visualizzerà: "Ciao, come vanno le cose in dopo la pandemia?"

Nel secondo esempio, il sistema non inserisce nulla perché l'utente non ha impostato un valore per la proprietà della variabile data in uso.

 

Var

Tieni presente che il tipo di variabile var non deve essere utilizzato nei modelli di email di marketing o nelle bozze delle campagne. Sebbene possa essere aggiunto a questi oggetti, il tentativo di inviare questo tipo di messaggio provocherà un evento BLOCKED (bloccato), dovuto a un errore del linguaggio per modelli. In genere, il messaggio di errore indica che non è stato fornito alcun valore per la variabile var, il che è prevedibile poiché non esiste alcun modo di aggiungere un valore a essa.

 

Tuttavia, esistono modi per poter utilizzare le variabili var in un modello di email di marketing o nella bozza di una campagna. I due approcci più semplici sono:

• Aggiunta della variabile var con un valore predefinito.
• Definizione della variabile mediante una funzione set.

Sebbene questi approcci funzionino dal punto di vista tecnico, possono essere controproducenti e poco utili. Questo in quanto richiedono di impostare il valore della variabile nel modello stesso prima dell'invio, senza consentire alcuna variazione del valore visualizzato in base al destinatario. Ciò contraddice lo scopo di una variabile e ne annulla la flessibilità.

 

Per un utilizzo corretto delle variabili var è necessario includerle nei modelli di email transazionali o direttamente nel contenuto dei messaggi transazionali. I valori utilizzati per sostituire queste variabili sono forniti dall'utente attraverso la chiamata API Send (come parte del corpo della richiesta) o durante la sessione di inoltro SMTP (come intestazione personalizzata), a seconda del canale transazionale utilizzato.

Per dichiarare le variabili e fornire i rispettivi valori, si utilizzano coppie chiave/valore JSON. Ad esempio, "name": "John" o "testVariable123": "testValue", ecc.

Nel contesto dell'API Send v3, l'oggetto che contiene le variabili è denominato "Vars". Per l'API Send v3.1, il principio rimane lo stesso, ma l'oggetto è denominato "Variables". Per i messaggi generati dall'inoltro SMTP, l'intestazione personalizzata che deve contenere le variabili codificate in JSON è "X-MJ-Vars".

 

Nota: affinché il linguaggio per modelli venga elaborato correttamente e non come testo normale, il sistema Mailjet si basa su proprietà specifiche che indicano se gli elementi del linguaggio per modelli debbano o meno essere trattati come tali. Queste proprietà sono di tipo booleano. Di seguito è indicato il nome della proprietà adatta a ogni canale transazionale:

• API Send v3: "Mj-TemplateLanguage"
• API Send v3: "TemplateLanguage"
• Inoltro SMTP: "X-MJ-TemplateLanguage"

Tieni presente che il valore predefinito per ciascuna di queste proprietà è "false" o "0". Se si trascura questo dettaglio, anche se le configurazioni sono corrette, le impostazioni del linguaggio per modelli potrebbero non funzionare come previsto. Infatti, senza l'abilitazione delle suddette proprietà, il sistema interpreta gli elementi del linguaggio per modelli nel messaggio inviato come normali stringhe di testo senza alcun significato aggiuntivo.

Infine, in uno scenario poco comune in cui gli utenti creano oggetti di una bozza di campagna tramite l'API e prevedono di utilizzare un linguaggio per modelli nel contenuto di tale bozza, devono assicurarsi che l'oggetto "/campaigndraft/$ID/detailcontent" a essa associato includa la seguente proprietà nell'oggetto "Headers":

Includendo questa proprietà, il sistema riconosce l'uso del linguaggio per modelli nel contenuto della bozza della campagna.

 

Valori predefiniti

Entrambe le variabili var e data supportano l'uso di valori predefiniti. Un valore predefinito funge da valore alternativo o di sicurezza che gli utenti forniscono al nostro sistema quando impostano la variabile nel modello o nel corpo del messaggio. Se vengono soddisfatte determinate condizioni, il nostro sistema visualizzerà il valore predefinito:

• variabili data: se il contatto che riceve il messaggio non ha un valore di proprietà impostato per quella specifica variabile/ proprietà.
• variabili var: se non viene inviato alcun valore attraverso la chiamata API o la sessione SMTP.

In questi scenari, il valore predefinito funge da sostituto per garantire che venga sempre visualizzato un valore per la variabile, anche quando i dati necessari non sono disponibili o forniti.

 

Sintassi

Tenendo a mente le considerazioni precedenti, analizziamo la sintassi corretta per variabili autonome (variabili che non vengono utilizzate all'interno di una funzione).

 

• Variabili var

  • Per aggiungere una variabile var, utilizza la seguente sintassi: {{var:variableName}}
  • Per fornire un valore predefinito insieme alla variabile: {{var:variableName:defaultValue}}
    • Sintassi alternativa: {{var:variableName:"defaultValue"}} (possono essere utilizzate indifferentemente entrambe le opzioni)
  • Per inserire uno spazio come valore predefinito, racchiudilo tra virgolette: {{var:variableName:" "}}
  • Per non visualizzare nulla come valore predefinito, utilizza le virgolette vuote: {{var:variableName:""}}

• Variabili data

  • Per aggiungere una variabile data, utilizza la seguente sintassi: [[data:contactPropertyName]]
  • Per fornire un valore predefinito insieme alla variabile:[[data:contactPropertyName:defaultValue]]
    • Sintassi alternativa: [[data:contactPropertyName:"defaultValue"]]

Nota: sebbene le doppie parentesi graffe al posto delle doppie parentesi quadre funzionino anche per le variabili data, si raccomanda di utilizzare le parentesi quadre eccetto in caso di funzioni specifiche che richiedono le doppie parentesi graffe.

 

Tieni presente che, a differenza di una variabile var, il comportamento del sistema cambia quando si verifica una situazione in cui manca un valore per una variabile data. Se una variabile data non ha un valore predefinito e il contatto non ha un valore impostato per la rispettiva proprietà, nel messaggio verrà inserito uno spazio bianco. Tuttavia, se non si dichiara l'assenza di un valore predefinito per una variabile var nella chiamata API o nella sessione SMTP, il messaggio verrà bloccato.

 

I valori predefiniti non sono obbligatori, ma possono essere utili per evitare il blocco dei messaggi. Per impostazione predefinita, quando il sistema incontra una variabile var senza un valore fornito, bloccherà il messaggio. Per influenzare questo comportamento, puoi includere una speciale proprietà booleana nella chiamata API o nell'intestazione SMTP:

• API Send v3: "Mj-TemplateErrorDeliver"
• API Send v3.1: "TemplateErrorDeliver"
• SMTP: "X-MJ-TemplateErrorDeliver"

Il valore predefinito di questa proprietà è "false," quindi abilitarla manualmente consente di inviare messaggi anche se sono presenti errori del linguaggio per modelli ed evita il blocco dei messaggi.

 

Infine, gli utenti possono scegliere se vogliono essere avvisati via email quando i loro messaggi vengono bloccati a causa di errori del linguaggio per modelli. Questa funzione può essere attivata attraverso un'altra proprietà speciale:

• API Send v3: "Mj-TemplateErrorReporting" (esempio: "Mj-TemplateErrorReporting": "reports@domain.tld")
• API Send v3.1: "TemplateErrorReporting" (esempio: {"Email": "reports@domain.tld", "Name": "Recipient Name"})
• SMTP: "X-MJ-TemplateErrorReporting" (esempio di intestazione personalizzata: X-MJ-TemplateErrorReporting: "reports@domain.tld")

 

Variabili predefinite

Nel nostro sistema, alcuni nomi di variabili sono riservati a variabili statiche predefinite. Queste consentono agli utenti di specificare una variabile che corrisponde a un valore specifico basato sul sistema. Alcune variabili predefinite comuni includono:

• ID del contatto destinatario
• Indirizzo email del contatto destinatario
• ID del modello
• Link condivisibili sui social media per la versione online dell'email (Twitter, Facebook, LinkedIn, ecc.): applicabili alle newsletter, allo stesso modo delle versioni online standard/collegamenti permanenti.

Puoi trovare un elenco di queste variabili statiche predefinite a questo link.

 

La sintassi per utilizzare una qualsiasi di queste variabili predefinite è la seguente: {{predefinedVarHere}}.

Esempio: {{mj:template.ID}} visualizzerà l'ID del modello nella versione finale del messaggio se è stato usato un modello per inviare l'email.

 

Tieni presente che esistono altre variabili riservate, come il link di annullamento dell'iscrizione o la versione online, che vengono introdotte utilizzando le doppie parentesi quadre (ad es. [[collegamento permanente]]). Queste variabili vengono in genere aggiunte automaticamente dal sistema, ma gli utenti possono anche introdurle manualmente in modelli a trascinamento, HTML grezzo, MJML grezzi o in oggetti DetailContent della bozza di una campagna. Ricorda che queste speciali variabili predefinite non devono essere introdotte con parentesi graffe. Introducendole con parentesi graffe, il sistema le tratterà come variabili che devono essere definite in una chiamata API o durante una sessione SMTP (come variabili "var") anziché come variabili che il sistema può recuperare da solo.

Pertanto, qualsiasi variabile statica predefinita specificata nella documentazione di riferimento indicata sopra (che inizia con "mj:") deve essere introdotta usando "{{}}", mentre qualsiasi variabile predefinita non elencata in tale documentazione (che non inizia con "mj:") deve essere introdotta usando "[[]]".

 

Oggetti e array multidimensionali

Il nostro linguaggio per modelli consente l'utilizzo di oggetti e array multidimensionali, che sono utili in varie situazioni, ad esempio per introdurre valori da utilizzare in un ciclo for.

 

Un oggetto o array multidimensionale è un oggetto che include variabili annidate una sotto l'altra. Può essere unicamente utilizzato nei modelli/messaggi transazionali, in quanto richiede che i valori siano forniti dall'utente e ciò deve essere effettuato tramite una struttura JSON specifica.

Ecco un esempio di variabile multidimensionale che deve essere presentata come oggetto multidimensionale nei dati JSON in cui saranno dichiarate le variabili per tale messaggio:

 

{{var:clothes.winter.coat}}

 

Ogni punto (".") rappresenta un "livello" di annidamento: il valore più a sinistra indica il livello più esterno, mentre più ci si sposta a destra, più ci si trova in basso nella struttura annidata. Ecco la struttura JSON corretta da utilizzare, in modo che il sistema individui correttamente il valore della variabile "clothes.winter.coat" (l'esempio include la proprietà "Variables" v3.1, ma questo varia a seconda del canale transazionale utilizzato, come discusso in una sezione precedente):

La configurazione presentata sopra fa sì che il termine "blazer" venga visualizzato nella posizione in cui "{{var:clothes.winter.coat}}" è stato inserito nel modello/contenuto dell'email.

 

Gli array multidimensionali sono invece più utilizzati, in particolare nei cicli for (di cui discuteremo in un'altra sezione). La logica di strutturazione dei dati JSON è simile a quella utilizzata nell'esempio precedente, con alcune aggiunte (ovvero, gli array JSON).

Ecco un semplice esempio: {{customer.Name}}

Supponendo che questa variabile verrà utilizzata in un ciclo for (il che significa che si vogliono assegnare valori diversi alla stessa variabile, in questo caso "Name"), possiamo utilizzare un array con oggetti annidati. Ecco come si presenterebbe la struttura JSON:

Come si può vedere, è presente una variabile annidata chiamata "Name" sotto il livello chiamato "customer". Ciò deve essere riflesso nella nostra struttura JSON. Innanzitutto è necessario definire "customer", dopo di che occorre specificare che si tratta di un array tramite l'inserimento di parentesi quadre aperte. All'interno delle parentesi quadre possiamo utilizzare più coppie di parentesi graffe per definire diversi valori per la variabile "Name". Se non fosse stato utilizzato un array multidimensionale (che in uno scenario reale sarebbe stato combinato anche con un ciclo for), non sarebbe stato possibile utilizzare la variabile "Name" più volte con valori diversi. Sarebbe stato necessario utilizzare, ad esempio, "Name1", "Name2", "Name3" e così via. Pertanto, l'utilizzo di un array multidimensionale permette di risparmiare tempo, rendendo la struttura JSON più facile da gestire e permettendo di riutilizzare la stessa variabile Name con valori diversi.

Nella sezione Ciclo for esamineremo un altro array multidimensionale semplice e uno più complesso (con più livelli di annidamento).

 

Dichiarazioni condizionali if

Le dichiarazioni condizionali if vengono utilizzate per introdurre requisiti che determinano se una specifica informazione debba essere visualizzata o meno. Possono anche includere valori alternativi che verranno visualizzati se il requisito iniziale non viene soddisfatto, utilizzando dichiarazioni else. Inoltre, è possibile introdurre un requisito alternativo utilizzando la dichiarazione condizionale elseif. Una dichiarazione if deve essere chiusa con un operatore endif.

 

In genere, le dichiarazioni condizionali if vengono introdotte utilizzando blocchi di linguaggio per modelli in un modello a trascinamento. Tuttavia, possono essere aggiunte anche all'interno di elementi di testo. Queste dichiarazioni possono essere utilizzate sia nei modelli di marketing che in quelli transazionali, sebbene questi ultimi offrano una maggiore flessibilità. In un modello transazionale, è possibile costruire dichiarazioni condizionali if basate sui valori delle variabili var, che vengono inviate tramite l'API Send o l'SMTP, e delle variabili data, che operano con i valori delle proprietà del contatto. In un modello di marketing si possono utilizzare solo variabili data, poiché non è possibile inserire valori per variabili var.

Ecco un esempio di una semplice dichiarazione condizionale if utilizzata in un modello di marketing:

Ecco un esempio del linguaggio per modelli in uso:

{% if data:firstname %}
PRINT THIS IN THE MARKETING MESSAGE
{% endif %}

 

In questo esempio, il linguaggio per modelli inizia con una clausola di apertura che contiene la condizione stessa. Se la condizione è soddisfatta (ovvero, il destinatario ha un valore impostato per la proprietà "firstname"), il sistema visualizzerà il contenuto nel blocco ("PRINT THIS IN THE MARKETING MESSAGE"). La clausola di chiusura indica la fine della sezione condizionale if.

La dichiarazione condizionale if si basa su una proprietà del contatto ("firstname"). Il sistema verifica se il destinatario ha un valore impostato per la proprietà "firstname". In caso affermativo, il sistema includerà nella versione finale dell'email il contenuto nel blocco. In caso contrario, la stringa specifica non verrà visualizzata.

Ecco un esempio di come potrebbe apparire la versione finale dell'email per un destinatario che ha una proprietà "firstname" definita:

 

Ecco un esempio della versione finale dell'email per un destinatario che non ha una proprietà "firstname" definita:

La condizione if di cui sopra verifica se la proprietà è definita per il destinatario. Tuttavia, è possibile introdurre un valore specifico che la proprietà deve avere affinché il contenuto condizionale venga inserito. Ad esempio:

In questo esempio, il contenuto condizionale "PRINT THIS IN THE MARKETING MESSAGE" sarà presente nella versione del messaggio del destinatario solo se la proprietà "firstname" del contatto è impostata sul valore "Gina". Questa condizione assicura che il contenuto venga visualizzato esclusivamente per i destinatari la cui proprietà "firstname" corrisponde al valore specificato "Gina".

 

Analizziamo un paio di esempi riguardanti modelli transazionali. Questi esempi dimostrano l'uso sia delle variabili var sia degli elementi del linguaggio per modelli e possono essere applicati all'interno di blocchi di testo o blocchi di linguaggio per modelli.

 

Esempio 1: utilizzo di una variabile var in un modello transazionale

In questo esempio verificheremo se la variabile var è definita. La condizione è true o false e funziona come una proprietà booleana.

 

Ecco cosa ci si può aspettare in diversi scenari:

• Se la "variabile" var non è definita nella chiamata API Send (SAPI) o nella sessione SMTP, si verificherà un errore del linguaggio per modelli. Aggiungendo un valore predefinito nella dichiarazione condizionale if (var:variable:defaultValueHere), verrà sempre inserito "PRINT THIS STRING IN THE TRANSACTIONAL EMAIL" per i destinatari la cui variabile non è definita.
• Se la variabile è impostata come true nella chiamata SAPI o nella sessione SMTP, la condizione sarà soddisfatta.
• Se la variabile è impostata come "anyValueYouCanThinkOfOtherThanFalse" nella chiamata SAPI o nella sessione SMTP, la condizione sarà soddisfatta.
• Se la variabile è impostata come false nella chiamata SAPI o nella sessione SMTP, la condizione NON sarà soddisfatta. Nota la differenza tra "variabile": "false" (scenario precedente) e "variabile": false (scenario attuale).

Esempio 2: panoramica di altri operatori di confronto e logici (else, elseif e ifelse + AND)

Questo esempio dimostra l'uso di diversi operatori di confronto e logici. Include le dichiarazioni if, else ed elseif combinate con l'operatore logico AND.

Infine, ecco uno screenshot utile come riferimento visivo: 

Questi esempi illustrano come le variabili var e i vari operatori possano essere utilizzati efficacemente all'interno dei modelli transazionali per personalizzare il contenuto in base a condizioni specifiche.

 

Esaminiamo ora le coppie di dati JSON e i risultati corrispondenti che producono per il destinatario finale:

JSON 1:

JSON 2:

JSON 3:

JSON 4:

In sostanza, affinché il valore "I'll consider going out" venga visualizzato, è necessario che le seguenti condizioni siano soddisfatte contemporaneamente: il "weather" non deve essere "bad", il valore "bankAccountBalance" deve essere diverso da 0 e la variabile "haveFreeTime" deve essere true (o defined). Se una di queste tre condizioni non è soddisfatta, verrà visualizzato il valore "I won't be going out" o "I'll stay at home", a seconda di quale condizione non è soddisfatta.

 

Nota l'uso dell'operatore logico AND, che richiede l'uso di parentesi () per garantire il corretto raggruppamento delle condizioni.

 

Cicli for

I cicli for consentono di eseguire più iterazioni di una variabile o utilizzare un elenco di variabili, offrendo flessibilità e contenuti dinamici. Tieni presente che i cicli for devono essere utilizzati solo nei modelli transazionali e non nei modelli di marketing, poiché non è possibile introdurre i valori o le iterazioni in un messaggio di marketing.

 

Vediamo una semplice rappresentazione di un ciclo for:

In questo esempio definiamo un ciclo for con il nome della variabile "Test" e specifichiamo lo spazio dei nomi in cui il sistema deve cercarla (var:Test). Consideriamo, ad esempio, una variabile semplice con una sola iterazione. La chiamata API o le intestazioni SMTP devono includere la seguente struttura JSON:

Nota: la precedente sezione "array multidimensionali" contiene un modo alternativo di presentare lo stesso tipo di struttura che può essere utilizzato anche con i cicli for.

 

Il ciclo for sarà sostituito dai valori forniti nella struttura JSON. Ecco un esempio di come risulterebbe il messaggio.

Immaginiamo ora uno scenario in cui fai parte del team di pubbliche relazioni di un'azienda e devi inviare un'email al dipartimento finanziario. Vuoi comunicare i nomi, il paese di residenza e i numeri di telefono di tre clienti che hanno vinto un gioco organizzato dall'azienda e hai bisogno che le loro informazioni di contatto vengano esaminate dal team finanziario.

A tale scopo, è possibile utilizzare un ciclo for nel messaggio per eseguire diverse iterazioni dello stesso nome di variabile (ad es. Name, Phone, ecc.) e visualizzare ogni volta valori diversi.

Ecco un esempio di come impostare una configurazione del linguaggio per modelli:

In questo caso, utilizziamo il nome della variabile "customer" per eseguire iterazioni dei dettagli del cliente forniti nella chiamata API o nelle intestazioni SMTP. La struttura JSON deve seguire questo formato:

Utilizzando questo approccio, si semplifica la struttura JSON e si riduce il rischio di errori. L'email risultante mostrerà i dettagli del cliente sulla base delle iterazioni fornite.

Infine, analizziamo un esempio più complesso che riguarda una struttura di array multidimensionale. In questo caso, ipotizziamo uno scenario legato ai capi di abbigliamento invernali.

Ecco la configurazione del ciclo for nel modello:

In questo esempio, utilizziamo la variabile "value" che si trova sotto lo spazio dei nomi "items" nella struttura JSON. Specifichiamo due tipi di articoli (coats e hats, ovvero cappotti e cappelli) con le rispettive variabili annidate sotto più livelli di variabili.

Ecco come risulterà la struttura JSON di questo esempio:

Il messaggio risultante mostrerà i valori per i cappotti e i cappelli invernali sulla base delle iterazioni fornite.

Utilizzando i cicli for è possibile eseguire iterazioni dinamiche delle variabili e generare contenuti personalizzati nei modelli transazionali. Per ottenere i risultati desiderati, è importante garantire la corretta struttura JSON e seguire la sintassi del linguaggio per modelli.

 

Dichiarazione condizionale if e tabella dei punti chiave dei cicli for:

 

Blocchi di testo - Blocchi di HTML - Blocchi di linguaggio per modelli

Quando si lavora con modelli di email, esistono diversi approcci per incorporare le strutture del linguaggio per modelli. Possono essere introdotte attraverso blocchi di testo, blocchi di HTML o blocchi di linguaggio per modelli nei modelli transazionali a trascinamento. Inoltre, possono essere incorporate direttamente nel contenuto dell'email.

È generalmente consigliabile separare, quando possibile, il contenuto HTML grezzo dalle strutture del linguaggio per modelli. Quando è necessario combinarli, ad esempio quando si crea una tabella con iterazioni di variabili usando un ciclo for, è generalmente più sicuro utilizzare un blocco di HTML a trascinamento e incorporare il linguaggio per modelli al suo interno, anziché aggiungere HTML grezzo a un blocco di linguaggio per modelli.

I blocchi di linguaggio per modelli sono particolarmente utili quando si lavora con le dichiarazioni condizionali if. Ogni operatore all'interno della dichiarazione condizionale if può essere inserito in un blocco separato del linguaggio per modelli, con vari altri elementi a trascinamento che fungono da contenuto che verrà visualizzato in base a una condizione specifica. Ad esempio, è possibile visualizzare un elemento immagine, un elemento video o un pulsante se vengono soddisfatti determinati criteri. È possibile aprire un ciclo for o dichiarazione condizionale if in un blocco e chiuderlo/a in un altro, garantendo flessibilità e organizzazione.

Per mantenere la chiarezza e la separazione, si raccomanda di collocare le strutture del linguaggio per modelli in blocchi dedicati, anziché mescolarle con altri contenuti. Sebbene sia possibile aggiungere del testo normale all'interno di un blocco di linguaggio per modelli, è meglio utilizzare blocchi separati per contenuti più complessi. Quando si combina HTML grezzo con strutture del linguaggio per modelli, è consigliabile utilizzare un blocco di HTML grezzo in cui il codice è memorizzato insieme al linguaggio per modelli, anziché includere HTML grezzo all'interno di un blocco di linguaggio per modelli.

 

Funzioni

Come discusso sopra, le funzioni sono una parte essenziale del linguaggio per modelli di Mailjet e offrono una serie di operazioni che possono essere eseguite dal sistema. Queste funzioni consentono di ottenere effetti di formattazione in diverse aree, come ad esempio:

• Operazioni matematiche: arrotondamento di valori numerici.
• Manipolazione delle stringhe: conversione delle stringhe in maiuscole o minuscole o capitalizzazione della prima lettera.
• Formattazione dei numeri: formattazione dei numeri in base a regole specifiche.
• Codifica URL: conversione di una stringa in un formato compatibile con gli URL.
• Escaping delle stringhe: assicura che i caratteri speciali in una stringa siano correttamente codificati.

Combinando queste funzioni con le variabili, le dichiarazioni condizionali if e gli operatori indicati nella guida al linguaggio per modelli di Mailjet, è possibile creare contenuti altamente personalizzabili e dinamici.

In questa sezione esamineremo due funzioni specifiche: la funzione set e la funzione FormatNumberLocale.

 

Funzione set

La funzione set è una potente funzione che consente di assegnare un valore direttamente a una variabile all'interno del modello o del contenuto dell'email, eliminando la necessità di dichiarare la variabile nella chiamata SAPI o nella sessione SMTP.

Vediamo un esempio:

Nell'esempio presentato sopra, si usa la funzione set per assegnare un valore alla variabile "testVar" all'interno del modello stesso. Nella riga successiva, utilizziamo la stessa variabile all'interno di una frase.

 

Utilizzando la funzione set, è possibile inviare un messaggio con un oggetto Variables vuoto, come questo:

Questo approccio ci consente di inviare messaggi senza definire esplicitamente la variabile nella chiamata API e il messaggio non verrà bloccato. Ecco il risultato dell'invio del messaggio:

Uno degli aspetti interessanti della funzione set è che può essere utilizzata più volte all'interno dello stesso contenuto per aggiornare il valore della stessa variabile. Vediamo un esempio che corregge una dichiarazione:

Nell'esempio sopra, aggiorniamo il valore della variabile "testVar" all'interno del modello. La seconda assegnazione sovrascrive il valore iniziale, determinando il seguente risultato:

Tieni presente che se si definisce un valore per la stessa variabile attraverso la chiamata API o la sessione SMTP, questo non sovrascriverà il valore impostato usando la funzione set all'interno del modello.

 

Funzione FormatNumberLocale

La funzione FormatNumberLocale consente di formattare i numeri in virgola mobile (numeri con frazioni decimali) secondo regole specifiche. Si basa su tre proprietà:

• Format: specifica il formato desiderato del numero.
• Number: fornisce il numero da formattare.
• Locale: seleziona le impostazioni locali per determinare il separatore decimale e quello delle migliaia.

Ad esempio, considera il seguente codice di modello:

In questo esempio, utilizziamo le impostazioni locali previste per il francese ("fr_FR") per formattare il numero 3500 usando il formato "#,###.00". Il risultato sarà:

Si può notare che il numero ora include separatori decimali e separatori delle migliaia nel formato francese.

La funzione FormatNumberLocale supporta anche altre varianti di formato, come:

Questi esempi dimostrano come piccole variazioni nel formato possano influenzare il risultato. Per la formattazione vengono utilizzate le impostazioni locali "en_GB". I risultati saranno:

Quando si usano variabili dinamiche con la funzione FormatNumberLocale, assicurati di seguire la sintassi corretta:

Assicurati che la variabile "var:VarName" non presenti virgolette o parentesi. Inoltre, fornisci il valore della variabile come numero intero nella chiamata API o nella sessione SMTP:

L'uso delle virgolette intorno al valore causerà errori nel linguaggio per modelli.

Queste funzioni, insieme alle numerose capacità del linguaggio per modelli di Mailjet, permettono di creare contenuti altamente personalizzati e dinamici nelle email. 

Note aggiuntive

Vale la pena ricordare che le variabili possono essere aggiunte al di fuori delle caselle di testo, dell'HTML o dei blocchi di linguaggio per modelli. È possibile introdurre variabili in vari altri elementi, come collegamenti ipertestuali, pulsanti e URL di immagini in elementi immagine a trascinamento.

Quando si utilizza una variabile all'interno di un collegamento ipertestuale o dell'URL di un pulsante, è possibile utilizzare un valore predefinito della variabile. Tuttavia, tieni presente che non è possibile utilizzare una variabile predefinita all'interno dell'URL associato a un elemento immagine a trascinamento. Il sistema ti consentirà di salvare la variabile nel campo URL con un valore predefinito, ma la eliminerà subito.

Tieni presente che l'aggiunta di una variabile predefinita all'interno del link di un elemento pulsante o di un collegamento ipertestuale è possibile e non causerà problemi. Tuttavia, è possibile che nell'editor venga visualizzata una notifica di errore, che può essere ignorata. Assicurati che il valore predefinito sia aggiunto senza virgolette e senza un protocollo HTTP/HTTPS all'inizio. Ad esempio: {{var:Link:www.mailjet.com}}

Un altro punto importante da considerare è la dichiarazione delle variabili nella chiamata SAPI/sessione SMTP. Questa dovrebbe corrispondere esattamente a come sono state aggiunte le variabili nel contenuto del messaggio. La sensibilità alle maiuscole e alle minuscole gioca un ruolo fondamentale, quindi è necessario prestare attenzione a eventuali discrepanze. Inoltre, l'utilizzo di un punto (.) nelle variabili indica oggetti o array multidimensionali. Se non bisogna indicare una struttura multidimensionale ma è necessario un separatore, il trattino basso (_) è una scelta migliore del punto.

Aggiornamenti del Templater: sintassi più rigorosa e cambiamenti di comportamento (ottobre 2025)

Abbiamo introdotto aggiornamenti che migliorano l’affidabilità e le prestazioni e rendono la validazione della sintassi più rigorosa. Se i tuoi template si basavano su una logica di parsing più permissiva, rivedi le modifiche riportate di seguito.

👉 Gestione più rigorosa dei tag

I blocchi {% if %} / {% for %} ora devono essere chiusi correttamente. La mancanza di {% endif %} o {% endfor %} genera un errore (in precedenza, i blocchi incompleti potevano essere tollerati).

{% if var:is_promo %}
  <p>Promo!</p>
{% endif %}

👉 Namespace delle variabili: var e data

• Se la variabile è dichiarata/conosciuta (esiste nello schema) ma non viene fornita nel payload, il rendering ora è più permissivo (si risolve in vuoto/falso a seconda del contesto).
• Se una variabile non è definita affatto, verrà restituito un errore.

{% if var:user.first_name %}Hello {{ var:user.first_name }}!{% endif %}

👉 Identificatori vs. operazioni

La spaziatura attorno agli operatori è importante. Il parser distingue gli identificatori dalle espressioni:

• var:x-1 → interpretato come un unico identificatore chiamato x-1
• var:x - 1 → interpretato come un’operazione di sottrazione (x meno 1)

{{ var:price - 1 }}   {# subtraction #}
{{ var:price-1 }}     {# key literally named "price-1" #}

👉 Riscrittura dei link per il tracciamento dei clic

I tag <a> senza un attributo href tra virgolette in precedenza venivano ignorati dal riscrittore di link. Ora vengono riscritti e tracciati correttamente.

<a href={{ var:url }}>Open</a>

<a href="{{ var:url }}">Open</a>

👉 Sostituzione del link di disiscrizione

[[ UNSUB_LINK ]] ora viene sostituito correttamente in tutte le parti del corpo del messaggio (incluse parti/ blocchi in cui in precedenza poteva essere ignorato).

<p>To unsubscribe, click [[ UNSUB_LINK ]]</p>

👉 Miglioramenti delle prestazioni

La latenza media di elaborazione dei template è stata ridotta, con conseguente personalizzazione delle email più rapida al momento dell'invio.

👉 Maggiore rigore sintattico

Il Templater applica ora la sintassi in modo più rigoroso. Gli errori di validazione più comuni includono:

• Blocco non chiuso (manca {% endif %} o {% endfor %})
• Variabile non definita (riferimento a una chiave non definita in var/data)
• Espressione non valida (problemi di spaziatura degli operatori o delimitatori non corrispondenti)

👉 Checklist

1. Esegui un rendering di prova per ogni template in produzione (usa payload che includono e omettono campi opzionali).
2. Chiudi ogni blocco di controllo con {% endif %} / {% endfor %}.
3. Definisci le tue variabili (schema) o fornisci tali valori nel payload; evita riferimenti non definiti.
4. Controlla operazioni aritmetiche e identificatori: aggiungi spazi attorno agli operatori che devono essere valutati.
5. Metti tra virgolette tutti i valori href: href="{{ var:url }}".
6. Verifica la presenza e il corretto rendering di [[ UNSUB_LINK ]] ovunque venga utilizzato.

Gestione degli errori dei modelli

Consulta questo articolo completo che ti illustrerà il processo di utilizzo della funzione Template Error Management di Mailjet. Questa potente funzione automatizza la verifica dei modelli, facendoti risparmiare tempo prezioso ed eliminando la necessità di controlli manuali. In questo modo puoi dire addio al noioso compito di rivedere singolarmente ogni modello e adottare invece un approccio semplificato per gestire gli errori in modo efficiente.