1. Documentation
  2. Intégration
  3. Headers

Headers

Les headers ou en-têtes personnalisés vous permettent de personnaliser chacun de vos emails comme bon vous semble, au moment de leur émission vers les serveurs de Tipimail. Vous sélectionnez par ce biais les éléments à activer ou intégrer dans chacun des emails générés peu importe le contenu ou les paramètres préalablement définis dans l'application Tipimail.

Les headers sont regroupés en deux catégories :

  • Modification de la configuration d'envoi
  • Modification du contenu

Utilisation des headers

Les headers sont constitués de paramètres au format JSON.

Exemple : 

{"TRACKING":{"html":{"open":1,"click":1},"text":{"click": 0}}}

Les headers peuvent être utilisé de plusieurs manières au sein de vos emails

Dans l'en-tête de vos emails

L'utilisation de ces instructions dans l'en-tête de vos emails est conditionnée par le langage de programmation utilisé. En effet selon les langages, l'ajout de paramètres en en-tête est différente. Néanmoins pour utiliser ces instructions, il faudra précéder le header par la chaîne "X-TM" (Exemple: X-TM-TRACKING). Des exemples d'utilisation selon le langage de programmation sont disponible dans le configurateur

Dans le sujet de l'email

Pour cela, il suffit de passer vos paramètres au format JSON en commencant et terminant votre header par le caractère "|"

Exemple: 

|{"tags":["reset-password"],"meta":{"order_id":"123456"},"tracking":{"html":{"open":1,"click":0},"text":{"click":0}}}| Mon sujet

En commentaire dans le contenu de l'email

Pour cela, il suffit de passer vos paramètres au format JSON en commencant et terminant votre header par le caractère "|"

Exemple:

Configuration de l'envoi

Tipimail vous permet depuis son interface de définir un certain nombre de paramètres tels que l'activation ou non du tracking. Les headers de type configuration d'envoi vous permettent de passer outre cette configuration et d'activer ou non certaines options selon les conditions.

Domain : X-TM-DOMAIN

Par défaut nous nous appuyons sur le domaine défini dans l'adresse email d'expéditeur pour envoyer l'email avec le bon domaine. Si le domaine n'est pas disponible, nous envoyons avec un autre domaine valide au hasard dans votre compte. Ce header vous permet de forcer le domaine de votre choix.

Voici les paramètres disponibles

Paramètre Type Exemple
string tipimail.com

Voici un exemple complet de l'header tags

"X-TM-DOMAIN":"tipimail.com"

Tracking : X-TM-TRACKING

Ce header vous permet d'activer ou non le tracking et de sélectionner le type de tracking

Voici les paramètres disponibles

Paramètre Type Valeur Exemple
html array contenant les éléments suivants
Paramètre Type Valeur Exemple
open integer
  • 1 : active le tracking sur les ouvertures du format html de l'email
  • 0 : désactive le tracking sur les ouvertures du format html de l'email
 "open":1
click integer
  • 1 : active le tracking sur les clics du format html de l'email
  • 0 : désactive le tracking sur les clics du format html de l'email
 "click":0
Active ou non le tracking sur l'ouverture et le clic pour la version html de votre email "html":{"open":1,"click":1}
text array contenant les éléments suivants
Paramètre Type Valeur Exemple
click integer
  • 1 : active le tracking sur les clics du format text de l'email
  • 0 : désactive le tracking sur les clics du format text de l'email
 "click": 1
Active ou non le tracking sur l'ouverture et le clic pour la version texte de votre email "text":{"click": 0}

Voici un exemple complet de l'header tracking

"X-TM-TRACKING":{"html":{"open":1,"click":1},"text":{"click": 1}}

Google Analytics : X-TM-GOOGLEANALYTICS

Ce header vous permet d'activer et de personnaliser l'utilisation de Google Analytics dans vos liens

Voici les paramètres disponibles

Paramètre Type Valeur Exemple
enable integer
  • 1 : activer le tracking Google Analytics
  • 0 : désactiver le tracking Google Analytics
 "enable" : "1"
utm_source string Source de votre email "utm_source" : "Transactional Email"
utm_medium string Média de votre email "utm_medium" : "email"
utm_content string Contenu de votre email "utm_content" : "order confirmation"
utm_campaign string campagne de votre email "utm_campaign" : "Ecommerce website"

Voici un exemple complet de l'header google analytics

"X-TM-GOOGLEANALYTICS":{"enable":"1","utm_source":"Transactional Email","utm_medium":"email","utm_content":"order confirmation","utm_campaign":"Ecommerce website"}

Tags : X-TM-TAGS

Ce header vous permet d'ajouter des tags (étiquettes) à vos emails. Ces étiquettes vous permettent de filtrer vos données dans la vue Activités > Statistiques de l'interface de Tipimail. Vous pouvez ainsi différencier aisement les emails de type "renouvellement de mot de passe" ou de "bienvenue" ou encore selon leurs provenances. Les tags ne sont évidemment pas visibles par vos destinataires.

Voici les paramètres disponibles

Paramètre Type Exemple
array de string ["welcome", "website1"]

Voici un exemple complet de l'header tags

"X-TM-TAGS":["welcome", "website1"]

Meta : X-TM-META

Ce header vous permet d'ajouter des élements personnalisés sous forme de clé-valeur. Ces éléments peuvent être aussi bien un numéro d'identifiant unique, un numéro de commande ou toutes autres renseignements vous étant utile. Les éléments contenus dans le header meta ne sont pas présent dans l'email de destination. Seuls les webhooks vous permettent de récupérer ces informations et de les traiter dans votre système.

Voici les paramètres disponibles

Paramètre Type Exemple
array de key-value {"order_id":"123456789","shipment_id":"123456789"}

Voici un exemple complet de l'header meta

"X-TM-META":{"order_id":"123456789","shipment_id":"123456789"}

Mode bulk (envoi de masse) : X-TM-BULK

Ce header vous permet d'activer l'envoi d'emails de masse. Il est important d'activer ce paramètre si vous souhaitez effectuer un envoi vers de nombreux destinataires afin de l'orienter vers les serveurs dédiés à cet envoi spécifique, garantissant la meilleure déliverabilité en conséquence.

Voici les paramètres disponibles

Paramètre Type Exemple
integer
  • 1: active l’envoi d’email de masse
  • 0: désactive l’envoi d’email de masse

Voici un exemple complet de l'header bulk

"X-TM-BULK":1

IP : X-TM-IPPOOL

Ce header vous permet de définir l'IP à utiliser pour votre envoi.

Voici les paramètres disponibles

Paramètre Type Exemple
string adresse IP

Voici un exemple complet de l'header bulk

"X-TM-IPPOOL":"192.168.1.1"

Personnalisation de l'envoi

Tipimail vous permet de personnaliser à la volé le contenu de l'email en remplacant certaines valeurs dynamiquement.

Version Texte : X-TM-TEXTVERSION

Ce header vous permet de créer et d'envoyer une version texte de votre email à partir de la version HTML

Voici les paramètres disponibles

Paramètre Type Exemple
int 1 ou 0

Voici un exemple

"X-TM-TEXTVERSION":1

Désinscription : X-TM-BLACKLIST

Ce header vous permet de gérer vos désinscriptions en les ajoutant dans une liste noire définie. Pour cela, il faut ajouter un lien spécial au sein du contenu HTML et Text de votre email et définir la liste noire au sein de laquelle vous souhaitez ajouter les désinscriptions. Grâce aux tracking de ce lien, nous serons en mesure de vous remonter le nombre de désinataire ayant cliqué sur le lien

Voici le paramètre à ajouter dans le contenu de votre email

‹a href="{{UNSUB 'http://www.tipimail.com/unsub?email={{email}}'}}">Désabonnement‹/a›

Voici le header à utiliser pour définir la liste noire

"X-TM-BLACKLIST":"liste_desabo"

Données personnalisées : X-TM-SUB

Le header sub vous permet de personnaliser la structure de l'emails, de remplacer un contenu spécifique selon les destinataires ou d'ajouter des arguments uniques à votre email.

Les cas les plus courants de remplacement de données dynamiquement sont la civilité ou le nom du destinataire. Avec un contenu dynamique, vous pouvez aller plus loin dans la personnalisation de votre e-mail

Les possibilités sont infinies :

  • Ajoutez des produits pour réaliser des ventes croisées selon la commande du destinataire
  • Changez le CSS de votre e-mail selon le genre du destinataire
  • Envoyer sujets différents selon le destinataire
  • Ajouter des données de votre système d'information au sein de l'email pour confirmer que les destinataires ont lu votre e-mail

Voici plusieurs cas d'utilisation

Cas d'utilisation 1 : remplacer la variable

Pour ajouter du contenu personnalisé, voici la procédure :

  • Ajouter les variables nécessaires à être remplacé dans le contenu de votre e-mail. Pour identifier la variable que nous devons remplacer, vous devez l'entourer par des doubles accolades comme le montre l'exemple suivant : {{name}}
  • Ajouter dans l'header le nom de la variable et sa valeur et ce pour chacune des adresses emails des destinataires

Lorsque Tipimail va générer l'e-mail, il va analyser toutes les adresses e-mail défini par le "To" et vérifier s'il y a des variables à remplacer.

Cas d'utilisation 2 : relier les informations d'un destinataire

Il peut être interessant d'ajouter des données importantes (identifiant de l'utilisateur, de la commande) fournis par votre système d'information au sein d'un email. Ces données vous permettront de les relier à vos utilisateurs afin d'effectuer différents traitements.

Exemple :

  • Un identifiant unique utilisé pour identifier le destinataire où l'adresse e-mail n'est pas la clé primaire
  • Utiliser un identifiant en lieu et place du message ID pour suivre le statut de cet email

Pour transmettre ses données sans les insérer dans l'email et donc qu'il ne soit pas visible par le destinataire, il vous suffit d'ajouter ces données dans la partie "meta" de l'en-tête personnalisée pour chaque destinataire.

Voici comment utiliser le header Sub avec les paramètres disponibles

Paramètre Type Valeur Exemple
email string adresse email du destinataire "email":"email@example.com"
values array de key-value couple de key value comportant les données à remplacer. Les variables à remplacer dans l'email doivent être entre les balises suivantes : {{...}} "values":{"first_name":"Gauthier","last_name":"DHU"}
meta array de key-value Vous avez la possibilité d'ajouter des données meta propre à ce destinataire. "meta":{"unique_id" : "987654321","order_id" : "132456798","shipment_id" : "1237498798"}

Voici un exemple complet de l'header sub

				{
					"X-TM-SUB":
					[
						{
							"email": "email1@example.com",
							"values":
							{
								"first_name" : "Firstname1",
								"unique_id":"132456798"
							},
							"meta":{}
						},
						{
							"email": "email2@example.com",
							"values":
							{
								"first_name" : "Firstname2",
								"unique_id":"987654321"
							},
							"meta":
							{
								"order_id" : "132456798",
								"shipment_id" : "1237498798"
							}
						}
					]
				}

Voici un exemple de l'email associé

	Bonjour {{first_name}} {{last_name}}

	Merci pour votre enregistrement, votre numéro est le : {{unique_id}}

Voici le résultat de l'email pour le destinataire email1@example.com

	Bonjour Firstname1

	Merci pour votre enregistrement, votre numéro est le : 123456789

Voici le résultat de l'email pour le destinataire email2@example.com

	Bonjour Firstname2

	Merci pour votre enregistrement, votre numéro est le : 987654321

La plupart du temps, l'email est utilisé comme clé pour transmettre des informations. Mais dans certains cas, une même adresse email peut être partagée entre plusieurs personnes, typiquement M et Mme qui partage leur adresse email.

Pour utiliser cette possibilité, il faut juste que vous passiez dans le header Sub, les informations concernant chaque personne dans 2 noeuds différents comme le montre l'exemple ci-dessous. Il ne faut passer qu'une fois l'adresse email en question dans le paramètre To

				{
					"X-TM-SUB":
					[
						{
							"email": "email1@example.com",
							"values":
							{
								"civilite" : "Monsieur",
							},
						},
						{
							"email": "email1@example.com",
							"values":
							{
								"civilite" : "Madame",
							},
						}
					]
				}

Template : X-TM-TEMPLATE

Ce header vous permet d'envoyer un email avec un template pré enregistré dans Tipimail. Cela vous permet de ne passer que les valeurs des variables contenus dans l'email et non tout votre email.

Voici les paramètres disponibles

Paramètre Type Exemple
string Nom du template

Voici un exemple

"X-TM-TEMPLATE":"reset-password"

L'utilisation du template est plus puissant avec le header SUB afin de remplacer les données des variables de votre email. Voici un exemple complet: 

				"X-TM-TEMPLATE":"reset-password"
				"X-TM-SUB":
				[
					{
						"email": "email1@example.com",
						"values":
						{
							"first_name" : "Firstname1",
							"unique_id":"132456798"
						},
						"meta":{}
					}
				]

Limite des headers

La RFC concernant les communications SMTP imposent plusieurs limites :

  • Vous êtes limité à une taille de 200 octects pour l'enveloppe JSON
  • Vous êtes limité à 1000 caractères par header. Si vous devez dépasser cette limite, il faudra séparer ce header
© - Tipimail - Sarbacane Software, Tous droits réservés.