Utiliser le langage de template de SendinBlue pour créer des templates d’emails [NOUVEAU]

Notre langage de template inclut des substituts et des élément logiques prédéfinis qui peuvent être utilisés pour intégrer à votre email un contenu dynamique et modifier l'affichage de ce contenu en fonction du destinataire.

Le langage de template offre une structure commune standardisée afin de créer des templates efficaces et de fournir de puissantes options de configuration.

Bon à savoir : le nouveau langage de template remplace une version antérieure du langage de template de SendinBlue, qui était moins puissante et utilisait une syntaxe différente. Dans ce guide, « le langage de template » fait référence au nouveau langage de template.

Avant de commencer

Si vous souhaitez créer un email unique à envoyer à plusieurs destinataires à la fois, créez votre email en tant que campagne.

Si vous souhaitez créer un template afin de l'envoyer en tant qu'email transactionnel ou à partir d'un scénario de Marketing Automation, créez et enregistrez-le en tant que template.

L'envoi d'emails utilisant le langage de template peut être déclenché à l'aide de leurs appels d'API v3 SendinBlue respectifs (pour les campagnes) ou (pour les emails transactionnels) en fournissant l'ID de la campagne ou du template. Vous pouvez également envoyer vos emails en utilisant le relais SMTP, en indiquant l'en-tête X-SIB-API avec les paramètres appropriés.

Bon à savoir : si vous n’avez encore jamais utilisé notre plateforme Transactionnel (SMTP), il vous faudra peut-être effectuer une demande d’activation. Pour vérifier si cette activation est nécessaire, connectez-vous à votre compte et consultez cette page. Si aucun message ne vous demande d’activer votre compte SMTP, et si votre quota est supérieur à 0, vous êtes prêt à envoyer vos emails.

Vue d’ensemble

Le langage de template utilise des variables et des filtres, qui sont remplacés par des valeurs spécifiques lorsque l'email est envoyé, ainsi que des tags dont la logique permet de contrôler comment et si le contenu s'affiche.

Il existe deux types de délimiteurs :

{{ ... }} : « saisit » ou intègre à l'email le résultat d’une variable ou d’un filtre
{% ... %} : exécute la logique d'un tag, telle qu'une boucle FOR.

Bon à savoir : le langage de template vous permet de modifier divers aspects de votre email, y compris l’objet, l’en-tête, les contenus des tags HTML <body> et le champ « à » du destinataire. Par défaut, le contenu HTML est automatiquement échappé dans les templates, mais vous pouvez modifier cette option en utilisant le tag autoescape décrit en détails ci-dessous.

 

Variables

Il existe trois types de variables différentes, décrites ci-dessous.

Bon à savoir : Lorsque vous utilisez la fonctionnalité « Envoyer un test » pour envoyer une version test de votre template d'email, les variables ne sont pas remplacées par des contenus spécifiques au destinataire dans l'email de test. Les variables apparaissent telles que vous les avez saisies dans le code de votre template. 

1. Variables prédéfinies

Ces variables sont disponibles pour tous les utilisateurs de SendinBlue :

{{ mirror }}

insère un lien pour visualiser votre email dans une page Web

L'utilisation de cette variable n'est pas obligatoire.

Elle est généralement placée en haut de l'email au format de lien, comme par exemple :

<a href={{ mirror }}>Cliquez ici pour visualiser ce message dans votre navigateur.</a>

{{ unsubscribe }}

insère un lien permettant de se désabonner de vos emails

Tous les emails non transactionnels envoyés via SendinBlue doivent inclure un lien de désabonnement.

Elle est généralement placée dans le pied de page de l'email au format de lien, comme par exemple :

<a href={{ unsubscribe }}>Cliquez ici pour vous désabonner.</a>

 

2. Attributs des contacts

Ce type de variable est composé de deux éléments et est structuré ainsi :

{{ contact.attributeNAME }}

Attribute = nom de l'attribut de contact SendinBlue tel qu'il apparaît sur votre page de contacts dans SendinBlue. Les attributs sont toujours en MAJUSCULES et ne contiennent jamais d'espace.

Exemple : pour insérer le numéro de téléphone d'un contact, si le nom de l'attribut est PHONE, utilisez : {{ contact.PHONE }}

Si le nom de l'attribut de contact contient un tiret, comme dans CELL-PHONE, indiquez votre variable sous la forme : {{ contact|key:"ATTRIBUTE" }}.  

Exemple : {{ contact|key:"CELL-PHONE" }}

3. Paramètres transactionnels

Les variables des paramètres transactionnels sont également composées de deux éléments et sont structurées ainsi :

{{ params.parameterNAME }}

parameterNAME = nom du paramètre transactionnel, au même format que dans l'API.

Exemple : pour insérer une liste de produits, si le nom du paramètre est PRODUCTS, utilisez : {{ params.PRODUCTS }}.

Envisageons à présent un cas de figure courant : établir une liste des produits achetés par un client. Puisque le nombre de produits achetés varie selon le client, vous pouvez associer une boucle « for » avec votre paramètre transactionnel PRODUCTS, en saisissant par exemple le code suivant :  

<ul> 
{% for product in params.products %}

   <li><strong>{{ product.NAME }}</strong> - {{ product.PRICE }}</li>
{% endfor %}
</ul>

Ce code génère une liste à puces désordonnée de produits, qui comprend le nom et le prix du produit, comme suit (chaque liste pourra inclure un nombre de produits différents selon le destinataire) :  

  • Produit 1 - 10 $
  • Produit 2 - 10 $
  • Produit 3 - 10 $

Bon à savoir : nous vous conseillons d'éviter l'emploi de tirets ou d'autres caractères spéciaux dans vos noms de variables/paramètres. Si vous n'avez pas d'autre solution, vous pouvez utiliser {{ params|key:”parameter-NAME” }}. Vous pouvez imbriquer le filtre à plusieurs reprises, comme dans {{ params|key:”my-product”|key:”my-product-name” }}.

Tableaux

Lorsque vous utilisez un tableau, vous pouvez accéder à tous les éléments individuels. Indiquez leur ID de la manière suivante : params.parameterARRAY.ID.parameterNAME. Par exemple : {{ params.PRODUCTS.1.NAME }}.

 

Tags  

Les tags les plus fréquemment utilisés disponibles dans les templates sont iffor, et autoescape. Vous trouverez ci-dessous des directives et des exemples pour chacun de ces tags. 

if

Grâce à sa puissante logique, le tag if vous permet d'ajouter ou supprimer des blocs de contenus entiers au sein de votre template (ou de modifier les contenus d'un bloc). Avec cette fonctionnalité, il est encore plus utile de créer un seul template pour plusieurs scénarios.

Le tag {% if %} permet de vérifier si une expression est vraie (ou si un tableau est vide) et de modifier le contenu de l'email en fonction du résultat. Il peut également agir sur des valeurs fausses, des conditions multiples et des alternatives multiples.

Vous trouverez ci-dessous quelques utilisations courantes de  if :

if

vérifier si une valeur est vraie ou si un tableau n'est pas vide

{% if contact.ACTIVE %}
Congrats! You achieved your goal this month.
{% endif %}
{% endif %}

---

{% if params.tutors %}

{% for tutor in params.tutors %}
The following tutors are available to help you:
<ol>
<li>{{ tutor.name }}</li>
{% endfor %}
</ol>
{% endif %}

==

vérifier si une expression est vraie

{% if coupon == “WELCOME” %}
<p>Bienvenue sur notre liste ! Voici votre premier code de réduction : WELCOME25</p>
{% endif %} 

---

{% if contact.DONOR == true %}
<b>Thank you for your support!</b>
{% endif %}

if, in

vérifier si une valeur (sous-chaîne) existe au sein d'une chaîne ou si une variable existe dans un tableau

{% if “@example.com" in "bob@example.com" %}
Ceci apparaît puisque "@example.com" est une sous-chaîne de "bob@example.com"
{% endif %}

 

{% if "Piano" in params.types %}
Attention ! Votre commande comprend des objets lourds. Vous devez être présent pour recevoir cette commande.
{% endif %}

not

vérifier les valeurs fausses

{% if not user.subscribed %}
   <p>Vous n'êtes pas inscrit à nos alertes de ventes secrètes. Inscrivez-vous ici.</p>
{% endif %}

and / or

évaluer des conditions multiples

{% if temperature > 10 and temperature < 55 %}
   <p>Brr. Il fait froid ! Voici un bon de réduction de 20 % valable sur les boissons chaudes, aujourd'hui uniquement.</p>
{% endif %}

 

{% if contact.LANG == “FR” and contact.COUNTRY == “Canada” %}
{% endif %}

 

{% if contact.COUNTRY == “United States” or contact.COUNTRY == “Canada” %}
{% endif %}

elif, else

évaluer des alternatives multiples

{% if contact.GENRE == “Homme” %} Bonjour Mr. {{ contact.NOM }},
{% elif contact.GENRE == “Femme” %} 
Bonjour Mme. {{ contact.NOM }},
{% else %} Bonjour, {% endif %}

---

{% if event.paid %}
   Votre réservation est confirmée. Merci pour votre paiement.
{% elif event.registered %}
    Votre réservation est confirmée mais sera annulée en cas de non-paiement d'ici le 2 janvier.
{% else %}
    Vous avez encore le temps de vous inscrire ! Cliquez ici.
{% endif %}

 

Bon à savoir : nous vous déconseillons d'appliquer des comparaisons avec le tag if à des variables qui contiennent des valeurs de type « float », car elles pourraient produire des résultats inexacts. (Les valeurs de type float sont des valeurs contenant un nombre fractionné au lieu d'un nombre entier.) Cependant, vous pouvez utiliser ces comparaisons si la valeur est une chaîne de caractères (contenue entre guillemets “comme ceci”).

for

Comme expliqué un peu plus loin dans ce guide, for est un tag très utile lorsqu'il est intégré à vos paramètres transactionnels. Avec ce tag, vous pouvez réaliser des actions complexes, comme par exemple insérer une liste dynamique de produits.

Le tag {% for %} permet de passer en revue ou itérer chacun des éléments d'une séquence. Il est particulièrement pratique lorsque le nombre d'éléments dans la séquence n'est pas encore connu au moment de la création du template.

Vous trouverez ci-dessous quelques utilisations courantes de
for :

for, in

afficher une liste

<ul>
   {% for user in params.USERS %}
       <li>{{ user.username }}</li>
   {% endfor %}
</ul>

else

exécuter un bloc de remplacement si la séquence est vide

<ul>
   {% for user in params.USERS %}
       <li>{{ user.username }}</li>
   {% else %}
       <li><em>aucun utilisateur trouvé</em></li>
   {% endfor %}
</ul>

Affiche « aucun utilisateur trouvé ».

reversed

inverse l'ordre de saisie des éléments d'une séquence

{% for country in params.countries reversed %} {% end for %}

Affiche une liste de pays dans l'ordre inverse de la liste d'origine.

 

Variables de boucles

Vous pouvez également appliquer les variables suivantes à l'intérieur d'une boucle « for » :

forloop.Counter

Correspond à un nombre entier qui représente le nombre d'entrées dans la boucle. Le compte démarre à 1 : après la première entrée dans la boucle, forloop.Counter est égal à 1.

Vous pouvez facilement utiliser cette expression afin de numéroter les éléments d'une boucle :

{% for product in params.products %}
{{ forloop.Counter }}. {{ product.name }} {% endfor %}

affichera une liste comme celle-ci :

1. Produit A
2. Produit B
3. Produit C, etc.

forloop.Counter0

Itération actuelle de la boucle (en commençant par 0).

forloop.Revcounter

Correspond à un nombre entier qui représente le nombre d'éléments restants dans la boucle. Après la première entrée dans la boucle, forloop.Revcounter est égal au nombre total d'éléments dans la séquence traversée. Après la dernière entrée dans la boucle, forloop.Revcounter est égal à 1.

forloop.Revcounter0

Nombre d'itérations jusqu'à la fin de la boucle (en commençant par 0)

forloop.First

La valeur booléenne indique True s'il s'agit du premier passage dans la boucle.

Cette fonctionnalité est particulièrement pratique pour appliquer un format spécifique au premier élément d'une liste, comme par exemple pour appliquer un filtre « upper » (décrit dans la partie « Filtres » ci-dessous) uniquement au premier élément de cette liste de produits.

{% for product in params.products %}
{{ forloop.Counter }}. {% if forloop.First %} {{ product.name|upper }} {% else %} {{ product.name }} {% endif %} - {{ product.price }}
{% endfor %}

peut afficher une liste de produits comme celle-ci :

1. PREMIER PRODUIT : 5,00 €
2. Deuxième produit : 2,00 €
3. Troisième produit : 4,00 €

forloop.Last

La valeur booléenne indique True s'il s'agit du dernier passage dans la boucle. Un caractère de séparation (comme , ou |) est souvent utilisé dans une liste d'éléments.

forloop.Parentloop

Référence l'objet forloop par rapport à une boucle parente, en cas de boucles imbriquées. Par exemple :

{% for country in countries %}
<table>
{% for city in country.city_list %}
<tr>
<td>Pays #{{ forloop.Parentloop.counter }}</td>
<td>Ville #{{ forloop.Counter }}</td>
<td>{{ city }}</td>
</tr>
{% endfor %}
</table>
{% endfor %}

 

Bon à savoir : les noms des variables des boucles sont sensibles à la casse.

Exemple : pour attribuer une valeur numérique (en commençant par 1) à chaque élément de votre itération, utilisez {{ forloop.Counter }} :

{% for user in users %}
   {{ forloop.Counter }} - {{ user.username }}
{% endfor %}

 

autoescape

Bon à savoir : par défaut, SendinBlue échappe le contenu HTML (et JS) de toutes les variables. Cela signifie que tous les contenus HTML compris dans une variable seront échappés et saisis en tant que texte. Par exemple, si le contenu de votre variable est <h1>Mon titre</h1>, votre template affichera précisément ce texte dans votre email : <h1> Mon titre</h1>, au lieu d'afficher le texte « Mon titre » au format titre H1.

Le tag autoescape contrôle les actions d'auto-échappement appliquées. Puisque les templates SendinBlue échappent automatiquement le contenu HTML, vous devrez appliquer ce tag pour désactiver l'auto-échappement au sein d'un bloc particulier. Ce bloc doit être fermé par un tag de fin endautoescape.

Analysons un exemple typique pour lequel il est judicieux de désactiver autoescape. Imaginons que vous regroupez vos produits dans une variable, mais que chaque produit requiert un formatage unique.

Si autoescape est utilisé de la manière suivante :

{% autoescape off %}{{ params.my_html }}{% endautoescape %}

Alors, l'échappement automatique sera désactivé pour la variable {{ params.my_html }}. }}. À présent, si le contenu de votre variable est <h1>Mon titre</h1>, celui-ci s'affichera en tant que titre H1. 

Les seules exceptions sont les variables pour lesquelles l'échappement est déjà désactivé, soit par le code qui définit la variable, soit par l'application du filtre safe.

 

verbatim

Le tag verbatim vous permet d'utiliser des accolades doubles {{ comme ceci }} dans votre email sans qu'elles soient reconnues en tant qu'élément de langage de template. Pour échapper {{ }} et afficher ces symboles directement dans votre email, utilisez ce tag :

{% verbatim %}
{{ Afficher variable }}
{% endverbatim %}

Ce texte apparaîtra entièrement dans votre email, comme ceci :

{{ Afficher variable }}

 

Filtres

Des filtres peuvent s'appliquer aux variables. Ils sont séparés de la variable par une barre verticale (|) et peuvent inclure des arguments optionnels entre parenthèses. Plusieurs filtres peuvent être combinés. Le résultat d'un filtre s'applique au filtre suivant.

Filtres les plus fréquents

Modifier le format des mots

capfirst

applique une majuscule à la valeur

Le premier caractère apparaîtra en majuscules, et tous les autres caractères seront en minuscules.

{{ contact.NAME|capfirst }}

jean dupont prendra la forme Jean dupont.

title

applique une majuscule à chaque début de mot

Chaque mot commencera par une majuscule, tandis que les autres caractères seront en minuscules.

{{ contact.NAME|title }}

jean dupont prendra la forme Jean Dupont.

upper

applique des majuscules à la valeur

{{ contact.NAME|upper }}

jean dupont prendra la forme JEAN DUPONT.

lower

applique des minuscules à la valeur

{{ contact.NAME|lower }}

JEAN DUPONT prendra la forme jean dupont.

trunchars

tronque une chaîne de caractères si celle-ci dépasse le nombre de caractères spécifié. Les chaînes tronquées se terminent par une ellipse (...).

{{ value|truncatechars:9 }}

Si « value » = félicitations, la valeur prendra la forme félicitat...

Modifier le format des nombres

floatformat

arrondit les valeurs float de votre paramètre ou attribut de contact à la décimale spécifiée.
Pour fonctionner correctement, les valeurs doivent être traitées en tant que nombre, et non en tant que chaîne de caractères.
(Les valeurs ne doivent pas être comprises entre guillemets, comme dans “valeur”.)

Si votre template comprend 
{{ contact.BALANCE }} et que la valeur du résultat est égale à 40,320000, celle-ci peut être arrondie à la décimale « n » comme ceci :
{{ contact.BALANCE | floatformat: n}}

{{ contact.BALANCE | floatformat: 2}}
prendra la forme 40,32 au lieu de 40,320000

{{ contact.BALANCE | floatformat: 0}}
prendra la forme 40 au lieu de 40,320000

Modifier le format des dates

time_parse

convertit le format de la date (en tant que chaîne de caractères) en un format standard qui peut être utilisé avec d'autres filtres

Utilisez le format actuel de la date en tant qu'argument : indiquez la date et l'heure exactes de Monday January 2 15:04:05 -0700 MST 2006 au format qui s'afficherait si cette valeur était utilisée.

Si votre chaîne est au format RFC3339, vous pouvez utiliser le paramètre dédié time_parse_rfc3339 sans argument.

{{ params.my_date|time_parse:"15:04 02/01/2006” }}

{ params.my_date|time_parse:"Monday 02 January 2006” }}

Remarque : seuls les mots anglais des jours et des mois sont reconnus.

date

saisit la date au format spécifié
Pour définir votre propre format, indiquez comment la date et l'heure de référence, définies à Mon Jan 2 15:04:05 - 0700 MST 2006, s'afficheraient selon le format que vous souhaitez utiliser.

Veuillez noter que vous devez ajouter une date à ce filtre.

Vous obtenez une date à partir d'une chaîne de caractères qui utilise le filtre time_parse.

{{ "14:01 01/06/2018"|time_parse:"15:04 02/01/2006"|date:"Mon Jan 2 15:04:05 2006"}}

prendra la forme :

Fri Jun 1 14:01:00 2018

Remarque : seuls les mots anglais des jours et des mois sont reconnus.

 

Veuillez noter que :

  • les abréviations des jours et des mois sont prises en charge en anglais uniquement
  • Si aucune valeur n'est spécifiée, elle est alors fixée à 0
  • Le fuseau horaire par défaut (s'il n'est pas spécifié) est UTC
  • Vous pouvez utiliser les mots clés am/pm
  • Les moyens les plus courants de définir les fuseaux horaires sont : les mots clés dédiés (MST, CET, UTC, Asian/Kolkata, etc.) ou les nombres, +0100 ou -0100, pour le format UTC.

Autres filtres

first

retourne le premier élément d'une séquence, d'un mappage ou d'une chaîne de caractères

Si votre template comprend {{params.array|first}}

et si votre demande de l'API comprend: 

“params” :
{
“array” : [ 1,2,3,4 ]
}

prendra la forme 1

join

retourne une chaîne de caractères qui regroupe les éléments d'une séquence

Par défaut, le séparateur des éléments est une chaîne vide. Vous pouvez définir un autre séparateur à l'aide du premier paramètre optionnel.

{{ [1, 2, 3]|join }}

prendra la forme 123  


{{ [1, 2, 3]|join('|') }}

prendra la forme 1|2|3

last

retourne le dernier élément d'une séquence, d'un mappage ou d'une chaîne de caractères

{{ [1, 2, 3, 4]|last }}

prendra la forme 4

length

retourne le nombre d'éléments d'une séquence ou d'un mappage, ou la longueur d'une chaîne de caractères

{% if users|length > 10 %}
   ...
{% endif %}

safe

permet d'indiquer qu'une chaîne de caractères ne nécessite pas d'échappement HTML avant l'affichage du résultat.

 

{{ params.htmltest | safe }}

"params" :{HtmlTest: "<p>Ceci est une phrase test.</p>"}

affichera un paragraphe formaté dans l'email du destinataire. 

 

{{ params.html }}
"params" :{HtmlTest: "<p>html para</p>"}

Sans le filtre safe, ce code affichera le tag HTML comme une chaîne de caractères normale dans l'email du destinataire :

<p>Ceci est une phrase test.</p>

slice

extrait certains éléments d’une séquence, d’un mappage ou d’une chaîne de caractères

Ce filtre peut être configuré pour :

A. Passer en boucle uniquement les « n » premiers éléments d'un groupe

B. Passer en boucle les éléments entre deux positions spécifiques (« n » et « m ») dans le groupe

Dans ces deux cas, n'oubliez pas qu'à chaque élément d'un groupe est attribué un numéro de position unique, en commençant par « 0 » à la première position.

C. Le filtre peut aussi être configuré pour passer en boucle les éléments entre des éléments spécifiques d'un groupe.

Dans chaque exemple, imaginons que le groupe contient les éléments suivants :

["a","b","c","d","e","f","g","h",...]

A.
{% for product in params.products|slice:’:5’ %}
{{ product.name - {{ product.price }}
{% endfor %}
passera en boucle les 5 premières positions (0-4), c'est-à-dire : ["a","b","c","d","e"]

B.
{% for product in params.products|slice:’2:3’ %}
{{ product.name - {{ product.price }}
{% endfor %}
passera en boucle les positions (2-3), c'est-à-dire : ["c","d"]

C.
{% for product in params.products|slice:’b:d’ %}
{{ product.name - {{ product.price }}
{% endfor %}
passera en boucle les éléments spécifiés  : ["b","c","d"]

 

 

 

Tester votre template et résoudre les problèmes

Pour tester votre template et résoudre les éventuels problèmes, veuillez consulter ce guide ou contacter notre service client.

Bon à savoir : lorsque vous utilisez la fonctionnalité « Envoyer un test » pour envoyer une version test de votre template d'email, les variables d'attribut de contact ne sont pas remplacées par des contenus spécifiques au destinataire dans l'email de test, tandis que les variables de paramètres transactionnels restent vierges.

 

Autres ressources documentaires

Le langage de template utilisé par SendinBlue est basé sur le langage de template de Django.

Ce guide comprend la plupart des structures et éléments les plus pertinents et les plus fréquemment utilisés. Vous trouverez ci-dessous une liste exhaustive de tous les tags et filtres pris en charge. Référez-vous à ces ressources Django pour obtenir plus d'informations. 

Tous les tags pris en charge

autoescape, comment, cycle, filter, firstof, for, if, ifchanged, now, set, spaceless, templatetag, with

Tous les filtres pris en charge

escape, safe, escapejs, add, addslashes, capfirst, center, cut, date, default, default_if_none, divisibleby, first, floatformat, get_digit, iriencode, join, last, length, length_is, linebreaks, linebreaksbr, linenumbers, ljust, lower, make_list, phone2numeric, pluralize, random, removetags, rjust, slice, stringformat, striptags, time, title, truncatechars, truncatechars_html, truncatewords, truncatewords_html, upper, urlencode, urlize, urlizetrunc, wordcount, wordwrap, yesno (Référence : https://djangobook.com/builtin-template-tags-filters/)

 

Remarque importante : Si vous souhaitez utiliser un élément qui n'est pas encore pris en charge, veuillez contacter notre équipe de service client à l'adresse contact@sendinblue.com afin d'en faire la demande.