Types de variables

 

Mailjet propose quatre types de variables, chacune ayant une fonction différente dans le templating language. Ces variables comprennent :

1. Data (statiques) : ces variables sont utilisées pour les données statiques ne changeant pas régulièrement. Il s'agit habituellement de valeurs prédéfinies.
2. Var (dynamiques) : les variables Var sont utilisées pour les données dynamiques pouvant changer en fonction de différentes conditions.
3. Variables Mailjet prédéfinies : ces variables sont prédéfinies par Mailjet et fournissent des informations et fonctionnalités utiles dans le templating language.
4. Structures des variables de segmentation : ces variables sont utilisées à des fins de segmentation complexe et ne seront pas abordées en profondeur dans cet article.

Nous nous concentrerons essentiellement sur les deux premiers types de variables (data et var), mais traiteront aussi rapidement des variables prédéfinies.

Les types de variables les plus souvent utilisées sont data et var. Bien qu'elles servent toutes les deux à remplacer des chaînes de caractères par défaut par une valeur changeant dynamiquement, elles diffères dans la façon dont elles doivent être utilisées, la façon dont leurs valeurs sont envoyées dans le système, et dans les types de messages où elles peuvent être utilisées.

En plus des variables autonomes, le templating language offre également des outils (fonctions) permettant aux utilisateurs d'incorporer les variables à des opérations logiques et arithmétiques plus complexes, ainsi que d'influencer le formatage et l'encodage. Dans ce guide, nous explorerons spécifiquement l'utilisation de fonctions telles que 'Set' et 'FormatNumberLocale'. De plus, nous nous pencherons plus précisément sur les expressions conditionnelles If et les boucles For.

 

Data

La variable data est polyvalente et peut être utilisée tant pour vos messages Marketing que Transactionnels. Cette souplesse est due au fait qu'il n'est pas nécessaire que l'utilisateur fournisse de valeur pour la variable par défaut. À la place, le système remplace automatiquement la valeur à partir des objets de la propriété de contact.

Que vous envoyiez une campagne marketing ou un email transactionnel, tant que le message est destiné à un contact existant et que le nom de la variable corresponde à une propriété de contact, le système pourra traiter la variable data. Si le destinataire a une valeur attribuée à cette propriété, elle s'affichera à la place de la variable par défaut.

 

Voici un exemple. Imaginez que je définisse la variable [[data:country]] dans le contenu de mon message et l'envoie à l'un de mes contacts. Dans ce scénario, deux résultats sont possibles :

1. Si le contact a une valeur définie pour la propriété de contact « country », il recevra le message avec la variable [[data:country]] remplacée par la valeur correspondante.
2. Si le contact n'a pas de valeur définie pour la propriété de contact « country », il recevra le message sans que la variable [[data:country]] ne soit remplacée. Cependant, la variable en elle-même ne s'affichera pas en tant qu'élément du templating language dans la version finale du message.

Pour vous donner un exemple concret, imaginons deux contacts : utilisateur1@domaine.tld, qui a « France » pour valeur de la propriété « country » , et utilisateur2@domaine.tld, qui n'a pas de valeur définie pour la propriété « country ».

Si j'envoie à ces deux contacts le même message contenant la phrase :

« Bonjour, est-ce que les choses se sont calmées en [[data:country]] depuis la fin de la pandémie ? »

 

Les destinataires verront alors le contenu suivant :

• utilisateur1@domaine.tld lira : « Bonjour, est-ce que les choses se sont calmées en France depuis la fin de la pandémie ? »
• utilisateur2@domaine.tld lira : « Bonjour, est-ce que les choses se sont calmées en depuis la fin de la pandémie ? »

Dans le deuxième exemple, rien n'est écrit par le système tout simplement parce que l'utilisateur n'a pas de valeur associé à la variable de données utilisée.

 

Var

Il est important de noter que les variables de type var ne doit pas être utilisées dans les modèles marketing ou les brouillons de campagnes. Bien qu'elles puissent être utilisées à ces projets, envoyer un message avec des variables var conduira à un événement de BLOCAGE, lié à une erreur dans le templating language. La plupart du temps, un message d'erreur vous indiquera qu'aucune valeur ne peut être associée à la variable var, ce qui est normal puisqu'il n'est pas possible d'y ajouter de valeur dans ce contexte.

 

Il est toutefois possible d'activer les variables var dans les modèles marketing ou les campagnes. Les deux solutions les plus simples sont :

• L'ajout de la variable var avec une valeur par défaut.
• La définition d'une variable utilisant une fonction Set.

Cependant, même si ces deux approches fonctionnent, elles peuvent être contreproductives et, finalement, peu utiles. En effet, elles demandent à ce que vous paramétriez la valeur de la variable dans le modèle lui-même, avant envoi, ne permettant ainsi aucune variation de la valeur affichée côté destinataire. Cela entre en contradiction avec la raison d'être d'une variable et nuit à sa souplesse.

 

L'utilisation correcte des variables var se fait donc dans les modèles transactionnels, ou directement dans le contenus des emails transactionnels. Les valeurs utilisées pour remplacer ces variables sont fournies par l'utilisateur via un appel à la Send API (dans le corps de la requête) ou pendant une session de relais SMTP (dans un en-tête personnalisé), en fonction du canal transactionnel utilisé.

Pour déclarer les variables et fournir les valeurs qui y sont associées, des paires de clés JSON sont utilisées. Par exemple, "name": "Jean" ou "testVariable123": "testValeur"...

Dans le contexte de la v3 de la Send API, l'objet contenant les variable est nommé « Vars ». Pour la v3.1 de la Send API, le principe reste le même, mais l'objet est désormais nommé « Variables ». Pour les messages générés via le relais SMTP, l'en-tête personnalisé contenant les variables encodées en JSON est « X-MJ-Vars ».

 

Notez que pour que le templating language soit traité correctement (et pas en texte brut), Mailjet s'appuie sur des propriétés spécifiques indiquant si les éléments du templating language doivent être traités comme tels. Ces propriétés sont de types booléen. Ci-dessous, vous trouverez les noms de propriété appropriés pour chaque canal transactionnel :

• V3 de la Send API : « Mj-TemplateLanguage »
• V3.1 de la Send API : « TemplateLanguage »
• Relais SMTP : « X-MJ-TemplateLanguage »

Veuillez garder à l'esprit que la valeur par défaut pour chacune de ces propriétés est « false » ou « 0 ». Si vous passez outre ce détail, même si votre configuration est correcte, les paramètres du templating language peuvent ne pas fonctionner comme prévu. Cela est simplement dû au fait que si vous n'activez pas les propriétés ci-dessus, le système interprètera les éléments du templating language dans le message envoyé comme des chaînes de texte ordinaires, sans apport supplémentaire.

Enfin, dans le cas exceptionnel où des utilisateurs créeraient des objets de campagne en brouillon via l'API, avec l'intension d'utiliser le templating language dans le contenu du brouillon de la campagne, ils devront s'assurer que l'objet "/campaigndraft/$ID/detailcontent" associé à leurs brouillons comprenne la propriété suivante dans l'objet « Headers » :

En incluant cette propriété, le système reconnaîtra l'utilisation du templating language dans le contenu du brouillon de la campagne.

 

Valeurs par défaut

Tant les variables var que data permettent l'utilisation de valeurs par défaut. Une valeur par défaut est une valeur de secours ou de sécurité que les utilisateurs intègrent au système lorsqu'ils paramètrent une variable dans le modèle ou le corps du message. Si certaines conditions sont remplies, la valeur par défaut sera affichée par notre système :

• Variables data : si le contact recevant le message n'a pas de valeur associée à la propriété de contact utilisée dans ce cas spécifique.
• Variables var : si aucune valeur n'a été transmise via l'appel API ou la session SMTP.

Dans ces situations, la valeur par défaut sert de remplacement, pour garantir qu'une valeur sera toujours affichée pour la variable concernée, même si les données nécessaires ne sont pas disponibles ou fournies.

 

Syntaxe

En gardant à l'esprit les considérations ci-dessus, examinons la syntaxe nécessaire pour les variables autonomes (les variables qui ne sont pas utilisées dans une fonction).

 

• Variables var

  • Pour ajouter une variable var, utilisez la syntaxe suivante : {{var:variableName}}
  • Pour ajouter une valeur par défaut à la variable : {{var:variableName:defaultValue}}
    • Syntaxe alternative : {{var:variableName:"defaultValue"}} (les deux options fonctionnent de la même manière)
  • Pour créer un espace en tant que valeur par défaut, mettez-le entre guillemets : {{var:variableName:" "}}
  • Pour ne rien afficher en tant que valeur par défaut, utilisez des guillemets sans rien entre les deux : {{var:variableName:""}}

• Variables data

  • Pour ajouter une variable data, utilisez la syntaxe suivante : [[data:contactPropertyName]]
  • Pour ajouter une valeur par défaut à la variable : [[data:contactPropertyName:defaultValue]]
    • Syntaxe alternative : [[data:contactPropertyName:"defaultValue"]]

Attention : même si les doubles accolades fonctionnent également pour les variables data (à la place des double crochets), il est tout de même recommandé d'utiliser des doubles crochets, sauf si des fonctions spécifiques requièrent l'utilisation expresse de doubles accolades.

 

Il est important de noter que le comportement du système diffère lorsqu'il rencontre une situation où il manque une valeur pour la variable data, par rapport à la variable var. Si une variable data n'a pas de valeur par défaut et que le contact n'a pas de valeur pour une propriété donnée, un espace blanc apparaîtra dans le message. Cependant, si une variable var n'a pas de valeur par défaut, et que cette absence n'est pas déclarée dans l'appel API ou la session SMTP, le message sera bloqué.

 

Les valeurs par défaut ne sont pas obligatoires, mais elles peuvent vous aider à éviter le blocage de vos messages. Par défaut, lorsque le système fait face à une variable var sans valeur, il bloquera le message. Pour modifier ce comportement, vous pouvez inclure une propriété booléenne spéciale dans votre appel API ou l'en-tête SMTP :

• V3 de la Send API : "Mj-TemplateErrorDeliver"
• V3.1 de la Send API : "TemplateErrorDeliver"
• SMTP : "X-MJ-TemplateErrorDeliver"

La valeur par défaut de cette propriété est "false", donc l'activer manuellement permet l'envoi des messages, même s'il y a des erreurs de templating language. Activer cette propriété évitera à vos messages d'être bloqués à l'envoi.

 

Enfin, les utilisateurs peuvent choisir s'ils souhaitent être notifiés par email lorsque leurs envois sont bloqués à cause d'erreurs dans le templating language. Vous pouvez activer ces notifications grâce à une autre propriété spéciale :

• V3 de la Send API : "Mj-TemplateErrorReporting" (par exemple : "Mj-TemplateErrorReporting": "reports@domain.tld")
• V3.1 de la Send API : "TemplateErrorReporting" (par exemple : {"Email": "reports@domain.tld", "Name": "Recipient Name"})
• SMTP : "X-MJ-TemplateErrorReporting" (exemple d'en-tête personnalisé : X-MJ-TemplateErrorReporting: "reports@domain.tld")

 

Variables prédéfinies

Dans notre système, certains noms de variables sont réservés à des variables statiques prédéfinies. Ces variables permettent aux utilisateurs de spécifier une variable correspondant à une valeur système spécifique. Parmi les variables prédéfinies les plus communes, on trouve :

• L'identifiant du destinataire
• L'adresse email du destinataire
• L'identifiant du modèle
• Les liens de partage sur les réseaux sociaux pour la version en ligne de l'email (Twitter, Facebook, LinkedIn...) - ceci s'applique aux newsletters tout comme aux versions en ligne standards et aux PERMALINKS.

Une liste complète de toutes ces variables statiques prédéfinies se trouve à cette adresse.

 

La syntaxe à utiliser pour ces variables prédéfinies est la suivante : {{predefinedVarHere}}.

Par exemple : {{mj:template.ID}} affichera l'identifiant du modèle dans la version finale du message si un modèle a été utilisé pour envoyer l'email.

 

Notez qu'il existe d'autres variables réservées, comme le lien de désinscription ou de version en ligne, qui sont introduites à l'aide de doubles crochets (par exemple : [[PERMALINK]]). Ces variables sont habituellement ajoutées automatiquement par le système, mais les utilisateurs peuvent également les ajouter manuellement dans les templates en glisser-déposer, en HTML brut, ou en MJML brut, ou encore dans les objets detailcontent des brouillons de campagnes. Il est important de rappeler que ces variables spéciales prédéfinies ne doivent pas être introduites avec des accolades. Si vous utilisez des accolades, le systèmes les traitera comme des variables, qui doivent donc être définies dans un appel API ou durant une session API (comme pour les variables var), plutôt que comme des variables que le système peut aller chercher lui-même.

C'est pourquoi toutes les variables statiques prédéfinies mentionnées dans la documentation ci-dessus (commençant par « mj: ») doit utiliser « {{}} », alors que les variables prédéfinies non listées dans la documentation (ne commençant donc pas par « mj: ») doivent utiliser « [[]] ».

 

Objets multidimensionnels et tableaux multidimensionnels

Notre templating language permet l'utilisation d'objets multidimensionnels et de tableaux multidimensionnels. Ils sont utiles dans diverses situations, notamment pour introduire des valeurs utilisées dans des boucles for.

 

Un objet ou un tableau multidimensionnel implique des variables imbriquées les unes dans les autres. Ils ne peuvent être utilisés que pour vos modèles et messages transactionnels, puisqu'ils impliquent l'utilisation de valeurs fournies par l'utilisateur. Cela doit être fait au moyen d'une structure JSON spécifique.

Voici un exemple de variable multidimensionnelle nécessaire pour être présentée comme objet multidimensionnel dans les données JSON, où les variables du messages seront déclarées ainsi :

 

{{var:clothes.winter.coat}}

 

Chaque point (« . ») représente une couche d'imbrication. La valeur la plus à gauche indique le niveau le plus externe. Plus on avance vers la droite, plus nous descendons dans la structure imbriquée. Voici la structure JSON correcte qui doit être utilisée, afin que notre système localise correctement la valeur pour la variable « clothes.winter.coat » (l'exemple comprend la propriété « Variables » de la V3.1, mais cela variera en fonction du canal transactionnel utilisé, comme expliqué dans la section précédente) :

La configuration ci-dessus fera que le mot « blazer » s'affichera là où « {{var:clothes.winter.coat}} » était placé dans le modèle ou le contenu de l'email.

 

Les tableaux multidimensionnel quant à eux sont plus souvent utilisés, notamment dans les boucles for (nous y revenons dans une autre section). La logique qui sous-tend la structure des données JSON est similaire à celle utilisée dans l'exemple ci-dessus, avec quelques ajouts (notamment les tableaux JSON).

Voici un exemple simple : {{customer.Name}}

En imaginant qu'il s'agit d'une variable utilisée dans une boucle for (ce qui signifie que nous voulons assigner différentes valeurs à la même variable - ici, « Name »), nous pouvons utiliser un tableau avec des objets imbriqués pour y parvenir. Voici ce à quoi le JSON ressemblera :

Comme vous pouvez le constater, nous avons une variable imbriquée appelée « Name » sous la couche appelée « customer », donc la structure de notre JSON doit le refléter. Nous définissons d'abord « customer » et nous spécifions qu'il s'agit d'un tableau en ouvrant les crochets. Dans les crochets, on peut voir plusieurs pairs d'accolades qui définissent les différentes valeurs associées à la variable « Name ». Si nous n'utilisions pas de tableau multidimensionnel (qui, dans une situation réelle, serait également combiné à une boucle for), nous n'aurions pas à utiliser la variable « Name » plusieurs fois avec différentes valeurs. Nous devrions utiliser quelque chose comme « Name1 », « Name2 », « Name3 »... C'est pourquoi l'utilisation d'un tableau multidimensionnel permet de gagner du temps, rend le JSON plus simple à utiliser, tout en permettant de réutiliser la variable « Name » avec différentes valeurs.

Nous verrons un autre cas d'utilisation simple du tableau multidimensionnel dans la section sur les boucles for, ainsi qu'un autre exemple plus complexe, avec plusieurs niveaux d'imbrication.

 

Expressions conditionnelles If

Les expressions conditionnelles if sont utilisées pour introduire des exigences qui déterminent si une information spécifique doit être affichée. Elles peuvent comprendre des valeurs alternatives à afficher si les conditions initiales ne sont pas satisfaites, en utilisant des expressions else. Par ailleurs, des conditions alternatives peuvent être introduites en utilisant l'expression conditionnelle elseif. Une condition if doit obligatoirement être clôturée par un opérateur endif.

 

Généralement, les expressions conditionnelles if sont introduites en utilisant les blocs de templating language dans un modèle en « drag-and-drop ». Cependant, elles peuvent aussi être ajoutées dans des blocs de texte. Ces expressions peuvent être utilisées dans les modèles marketing et transactionnels, sachant que les modèles transactionnels sont ceux qui offrent le plus de souplesse. Dans un modèle transactionnel, les conditions if peuvent être construites à partir de valeurs des variables var, transmises par la Send API ou le SMTP, ainsi que des variables data qui fonctionnent avec les valeurs des propriétés des contacts. Dans un modèle marketing, seules les variables data peuvent être utilisées, puisqu'il n'est pas possible de pousser les valeurs des variables var.

Voici un exemple d'une expression conditionnelle if simple dans un modèle marketing :

Voici un exemple d'utilisation du templating language :

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

 

Dans cet exemple, le templating language commence par une clause d'ouverture contenant la condition elle-même. Si la condition est remplie (ici, si le destinataire a une valeur associée à la propriété « firstname »), le système affichera le contenu du bloc (ici, la phrase « PRINT THIS IN THE MARKETING MESSAGE »). La clause finale marque la fin de la section conditionnelle if.

L'expression conditionnelle if repose sur une propriété de contact, « firstname ». Le système vérifiera si le destinataire a bien une valeur associée à la propriété « firstname ». Si la réponse est oui, la système inclura alors le contenu du bloc dans la version finale de l'email. Si la réponse est non, ce bloc spécifique ne sera pas affiché.

Voici un exemple de ce à quoi ressemble la version finale de l'email chez les destinataires ayant défini la propriété « firstname » :

 

Et voici un exemple de ce à quoi ressemble la version finale de l'email chez les destinataires n'ayant pas défini la propriété « firstname » :

La condition if ci-dessus vérifie si la propriété est définie pour le destinataire. Cependant, vous pouvez introduire une valeur spécifique que la propriété doit avoir pour que le contenu conditionnel s'affiche. Par exemple :

Dans cet exemple, le contenu conditionnel « PRINT THIS IN THE MARKETING MESSAGE » ne s'affichera que dans la version du message si la propriété de contact « firstname » est définie sur la valeur « Gina ». Cette condition garantit que le contenu est affiché exclusivement pour les destinataires dont la propriété « firstname » correspond exactement à la valeur « Gina ».

 

Examinons de plus près quelques exemples de modèles transactionnels. Ces exemples illustrent l'utilisation des variables var et des éléments du templating language , et peuvent être appliqués aux blocs texte comme de templating language.

 

Exemple 1 : utilisation d'une variable var dans un modèle transactionnel

Dans cet exemple, nous vérifions si la « variable » var est définie. La condition est soit vraie ou fausse, et agit donc comme une propriété booléenne.

 

Vous pouvez donc vous attendre à différents scénarios :

• Si la « variable » var n'est pas définie dans l'appel de la Send API (SAPI) ou dans la session SMTP, il en résultera une erreur. Ajouter une valeur par défaut dans la condition if (var:variable:defaultValueHere) résultera en l'affichage systématique du texte « PRINT THIS IN THE MARKETING MESSAGE » pour les destinataires chez qui la variable n'est pas définie.
• Si la variable est définie comme true dans l'appel de la SAPI ou dans la session SMTP, la condition est remplie.
• Si la variable est définie comme "anyValueYouCanThinkOfOtherThanFalse" dans l'appel de la SAPI ou la session SMTP, la condition est remplie.
• Si la variable est définie comme false dans l'appel de la SAPI ou la session SMTP, la condition N'EST PAS remplie. Notez la différence entre "variable": "false" (le scénario précédent) et "variable": false (le scénario actuel).

Exemple 2 : présentation d'autres opérateurs logiques et comparatifs (else, elseif et ifelse + AND)

Cet exemple illustre l'utilisation de différents opérateurs de compararaison et opérateurs logiques. Il inclut les conditions if, else et elseif, combinées à l'opérateur logique AND.

Enfin, voici une capture d'écran qui sevira de référence visuelle : 

Ces exemples illustrent comment les variables var et différents opérateurs peuvent être utilisés efficacement dans des modèles transactionnels pour personnaliser le contenu à partir de conditions spécifiques.

 

À présent, examinons les paires de données JSON et les résultats correspondants qu'elle produisent pour le destinataire final :

JSON 1 :

JSON 2 :

JSON 3 :

JSON 4 :

Concrètement, pour que la valeur « I'll consider going out » s'affiche, il faut que les conditions suivantes soient remplies simultanément : la variable « weather » ne doit pas être « bad », la valeur de la variable « bankAccountBalance » doit être différente de « 0 », et la variable « haveFreeTime » doit être "true" (ou définie comme tel). Si l'une de ces trois conditions n'est pas remplie, la valeur « I Won't be going out » ou « I'll stay at home » s'affichera, en fonction de la condition qui n'a pas été remplie.

 

Notez que l'utilisation de l'opérateur logique AND nécessite l'utilisation de parenthèses () pour assurer un regroupement correct des conditions.

 

Boucles for

Les boucles for vous permettent de parcourir plusieurs itérations d'une variable ou d'effectuer une boucle sur la liste de variables, offrant dynamisme et souplesse à votre contenu. Il est important de noter que les boucles for ne doivent être utilisées qu'avec les modèles transactionnels, jamais avec les modèles marketing, puisque les valeurs ou itérations ne peuvent pas être introduites dans les messages marketing.

 

Examinons une représentation simple de boucle for :

Dans cet exemple, nous avons défini une boucle for avec le nom de variable « Test », et spécifié le namespace où le système doit faire la recherche (var:Test). Nous supposons une variable simple avec une itération. L'appel API ou les en-têtes SMTP doivent inclure la structure JSON suivante :

Notez que la section « Tableaux multidimensionnels » précédente contient une autre façon de présenter le même type de structure qui peut également être utilisée avec les boucles for.

 

La boucle for sera remplacée par les valeurs fournies dans la structure JSON. Voici un exemple de ce à quoi le message final ressemblerait.

Imaginons maintenant un scénario où vous faites partie de l'équipe de relations publiques d'une entreprise, et que vous ayez besoin d'envoyer un email au département Finances. Vous voulez communiquer les prénoms, pays de résidence et numéros de téléphone de trois clients qui ont gagné un jeu organisé par votre entreprise, et avez besoin que leurs informations de contact soient vérifiées par l'équipe Finances.

Pour ce faire, vous pouvez utiliser une boucle for dans votre message pour faire défiler les différentes itérations d'un même nom de variable (par exemple : « Name », « Phone »...), et avoir différentes valeurs affichées à chaque fois.

Voici un exemple de configuration du templating language pour cette situation :

Ici, nous avons utilisé le nom de variable « customer » pour parcourir les détails du client fournis dans l'appel API ou les en-têtes SMTP. La structure JSON devrait être formatée ainsi :

En utilisant cette approche, vous simplifiez la structure du JSON et réduisez les risques d'erreurs. L'email qui en résulte affichera les détails du client en fonction des itérations fournies.

Enfin, explorons un exemple plus complexe, impliquant une structure de tableau multidimensionnel. Dans cette situation, le scénario est en lien avec les vêtements d'hiver.

Voici la configuration de la boucle for du modèle :

Dans cet exemple, nous utilisons la variable « value », située sous le namespace « items » dans la structure JSON. Nous spécifions deux types d'articles (« coats » et « hats »), avec leurs variables respectives imbriquées dans plusieurs couches de variables.

Voici ce à quoi la structure JSON de cet exemple ressemble :

Le message final affichera les valeurs « coats » et « hats » en fonction des itérations fournies.

En utilisant des boucles for, vous pouvez itérer dynamiquement à travers les variables et générer un contenu personnalisé dans les modèles transactionnels. Il est important de veiller à ce que la structure JSON soit correcte, et de suivre la syntaxe du templating language pour obtenir les résultats souhaités

 

Ce qu'il faut retenir des expressions conditionnelles if et des boucles for :

 

Blocs de texte - Blocs HTML - Blocs de template language

Lorsque vous travaillez avec des modèles d'emails, différentes approches pour incorporer des structures de templating language existent. Elles peuvent être introduites via des blocs de texte, des blocs HTML ou des blocs de templating language dans les modèles transactionnels en « drag-and-drop ». Par ailleurs, ils peuvent être intégrés directement dans le contenu de l'email.

Il est généralement conseillé de séparer le contenu HTML brut des structures de templating language lorsque cela est possible. Lorsqu'il est nécessaire de les combiner, par exemple pour créer un tableau avec des itérations variables utilisant une boucle for, il est généralement plus sûr d'utiliser un bloc HTML en « drag-and-drop », et d'intégrer le templating language dedans, plutôt que d'ajouter du HTML brut dans un bloc de templating language.

Les blocs de templating language sont particulièrement utiles lorsque vous utilisez des expressions conditionnelles if. Chaque opérateur de la condition if peut être placé dans un bloc de templating language distinct, avec différents autre éléments en « drag-and-drop » servant de contenu qui sera affiché en fonction d'une condition spécifique. Vous pouvez par exemple afficher une image, une vidéo ou un bouton si certains critères sont remplis. Il est possible d'ouvrir une boucle for ou une condition if dans un bloc et de les clore dans un autre, vous offrant plus de flexibilité et d'organisation.

Pour maintenir de la clarté et de l'organisation, il est recommandé de placer les structures de templating language dans des blocs de templating language dédiés plutôt que les mélanger au reste du contenu. Bien qu'il soit possible d'ajouter du texte brut dans un bloc de templating language, il est préférable d'utiliser des blocs séparés pour le contenu plus complexe. Lorsque vous combinez du HTML brut à des structures de templating language, il est recommandé d'utiliser un bloc de HTML brut où le code est stocké avec le templating language, plutôt qu'ajouter un bloc de HTML brut dans un bloc de templating language.

 

Fonctions

Comme nous l'avons vu plus haut, les fonctions sont une partie essentielle du templating language de Mailjet, offrant une variété d'opérations qui peuvent être effectuées par le système. Ces fonctions permettent d'obtenir des effets de formatage dans différents domaines comme :

• Les opérations mathématiques : arrondir les valeurs numériques.
• Les manipulations de chaînes de caractères : convertir les chaînes en majuscules ou en minuscules, ou capitaliser la première lettre.
• Le formatage des nombres : formatage des nombres en fonction de règles spécifiques.
• L'encodage d'URL : conversion d'une chaîne de caractères en un format sûr d'URL.
• La conversion de caractères : garantie que les caractères spéciaux sont encodés correctement.

En combinant ces fonctions à des variables, des expressions conditionnelles if et des opérateurs mentionnés dans la présente documentation, vous pouvez créer des contenus très personnalisables et dynamiques.

Dans cette section, nous explorons deux fonctions spécifiques : la fonction set et la fonction FormatNumberLocale.

 

Fonction set

La fonction set est une fonctionnalité puissante, vous permettant d'assigner une valeur directement à une variable dans le contenu du modèle ou de l'email, ce qui évite ainsi de devoir déclarer la variable dans l'appel de la SAPI ou dans la session SMTP.

Étudions cet exemple :

Dans l'exemple ci-dessus, nous avons utilisé la fonction set pour assigner une valeur à la variable « testVar », directement dans le modèle lui-même. À la ligne suivante, nous utilisons la même variable dans une phrase.

 

En utilisant la fonction set, nous pouvons envoyer un message avec un objet Variables vide, comme ci-dessous :

Cette approche nous permet d'envoyer des messages sans définir explicitement la variable dans l'appel API. Ainsi, le message ne sera pas bloqué. Voici à quoi ressemble le message une fois envoyé :

Un des aspects intéressants de la fonction set est que vous pouvez l'utiliser plusieurs fois dans le même contenu, pour mettre à jour la valeur de la même variable. Voici un exemple qui corrige la déclaration initiale :

Dans cet exemple, nous avons mis à jour la valeur de la variable « testVar » dans le modèle. La seconde attribution remplace la valeur initiale, ce qui donne le résultat suivant :

Gardez à l'esprit que si vous transmettez une valeur pour la même variable via un appel API ou une session SMTP, elle ne remplacera pas la valeur définie par la fonction set dans le modèle.

 

Fonction FormatNumberLocale

La fonction FormatNumberLocale vous permet de formater les nombres à virgule flottante (les nombres décimaux), suivant certaines règles spécifiques. Il repose sur trois propriétés :

• Format : spécifie le format souhaité pour le nombre.
• Number : indique le nombre qui doit être formaté.
• Locale : sélectionne la localisation pour déterminer si un point ou une virgule doivent être utilisés comme séparateur décimal ou espacer les milliers.

Regardez ce modèle de code :

Dans cet exemple, nous utilisons la localisation française ("fr_FR") pour formater le nombre 3 500, en utilisant le format "#,###.00". Le résultat sera le suivant :

Vous constatez que le nombre prend désormais en compte un séparateur pour les milliers, et un séparateur décimal, en suivant le format français.

La fonction FormatNumberLocale supporte également d'autres variantes de format comme :

Ces exemples montrent comment de légères variations du format peuvent affecter le résultat final. La localisation "en_GB" est utilisée ici. Les résultats seront :

Lorsque vous utilisez des variables dynamiques avec la fonction FormatNumberLocale, assurez-vous de suivre la syntaxe correcte :

Assurez-vous que la variable « var:VarName » est fournie sans guillemets ni crochets. Par ailleurs, fournissez la valeur de la variable sous la forme d'un nombre entier dans l'appel API ou la session SMTP :

L'utilisation des guillemets autour de la valeur causera des erreurs dans le templating language.

Ces fonctions, ainsi que les vastes capacités du templating language de Mailjet, vous permettent de créer des contenus très personnalisables et dynamiques pour vos emails. 

Notes supplémentaires

Il convient de mentionner que les variables peuvent être ajoutées hors des blocs de texte, HTML ou de templating language. Vous pouvez introduire des variables dans différents autres éléments en « drag-and-drop », comme les liens hypertextes, les boutons ou les URL d'images.

Lorsque vous utilisez une variable dans un lien hypertexte ou l'URL d'un bouton, vous pouvez utiliser une valeur de variable par défaut. Cependant, gardez à l'esprit que vous ne pouvez pas utiliser de variable par défaut dans l'URL associée à un élément d'image en « drag-and-drop ». Le système vous permettra de sauvegarder la variable dans le champ URL avec une valeur par défaut, mais la supprimera immédiatement.

Gardez également à l'esprit que lorsque l'ajout d'une variable par défaut dans le lien d'un élément de type bouton ou dans un lien hypertexte est possible et fonctionnera correctement. Cependant, vous recevrez peut-être une notification d'erreur dans l'éditeur, que vous pouvez ignorer. Assurez-vous que la valeur par défaut est bien ajoutée sans guillemets ni protocole HTTP/HTTPS au début. Par exemple : {{var:Link:www.mailjet.com}}

Un autre point important à prendre en considération est la déclaration des variables dans l'appel de la SAPI ou la session SMTP. Elle doit correspondre exactement à ce qui a été ajouté dans le contenu du message. La sensibilité à la casse joue un rôle crucial, donc restez attentif à toute divergence entre les majuscules et les minuscules. Par ailleurs, lorsque vous utilisez un point « . » dans les variables, il indique des objets ou tableaux multidimensionnels. Si vous avez besoin d'un séparateur dans une structure multidimensionnelle, un tiret bas « _ » est préférable au point.

Mises à jour du templating : syntaxe plus stricte, changements de comportement (octobre 2025)

Nous avons déployé des mises à jour qui améliorent la fiabilité et les performances, et rendent la validation de la syntaxe plus stricte. Si vos templates reposaient sur un parsing permissif, veuillez consulter les changements ci-dessous.

👉 Gestion plus stricte des balises

Les blocs {% if %} / {% for %} doivent désormais obligatoirement être correctement fermés. L’absence de {% endif %} ou {% endfor %} déclenche une erreur (auparavant, les blocs incomplets pouvaient être tolérés).

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

👉 Espaces de noms des variables : var et data

• Si la variable est déclarée/connue (existe dans votre schéma) mais non fournie dans le payload, le rendu est désormais plus permissif (résolution en vide/faux selon le cas).
• Si une variable n’est pas définie du tout, une erreur sera renvoyée.

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

👉 Identifiants vs. opérations

Les espaces autour des opérateurs sont importants. Le parseur distingue les identifiants des expressions :

• var:x-1 → interprété comme un identifiant unique nommé x-1
• var:x - 1 → interprété comme une opération de soustraction (x moins 1)

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

👉 Réécriture des liens pour le suivi des clics

Les balises <a> sans href entre guillemets étaient auparavant ignorées par l’outil de réécriture de liens. Elles sont désormais réécrites et suivies.

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

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

👉 Remplacement du lien de désinscription

[[ UNSUB_LINK ]] est désormais correctement remplacé dans toutes les parties du corps du message (y compris dans les blocs/partials où il pouvait auparavant être ignoré).

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

👉 Améliorations de performance

La latence moyenne du traitement des templates a été améliorée, permettant une personnalisation des emails plus rapide au moment de l’envoi.

👉 Rigueur globale de la syntaxe

Le moteur de templating applique désormais une syntaxe plus stricte de manière générale. Vous pourriez rencontrer des erreurs courantes telles que :

• Bloc non fermé (manque {% endif %} ou {% endfor %})
• Variable indéfinie (référence à une clé qui n’existe pas dans var/data)
• Expression mal formée (espacement des opérateurs ou délimiteurs non appariés)

👉 Checklist

1. Effectuez un rendu de test pour chaque template de production (en utilisant des payloads avec et sans champs optionnels).
2. Fermez tous les blocs de contrôle avec {% endif %} / {% endfor %}.
3. Définissez vos variables (schéma) ou fournissez-les dans le payload ; évitez les références réellement indéfinies.
4. Vérifiez l’usage des opérations et des identifiants : ajoutez des espaces autour des opérateurs destinés à être évalués.
5. Mettez toutes les valeurs href entre guillemets : href="{{ var:url }}".
6. Vérifiez la présence et le rendu de [[ UNSUB_LINK ]] partout où il apparaît.

Gestion des erreurs de modèle

Explorez cet article complet qui vous guidera à travers le processus d'utilisation de la fonctionnalité de gestion des erreurs de modèle de Mailjet. Cette fonctionnalité puissante automatise la vérification de vos modèles, vous faisant gagner un temps précieux, et éliminant les vérifications manuelles. Dites adieu à l'examen fastidieux de chaque modèle, et laissez la place à une gestion rationalisée des erreurs.