1. Documentation
  2. Intégration
  3. Webhooks

Utilisation des Webhooks

Introduction

Le fonctionnement des webhooks est assez simple : dès qu'un événement ou un changement d'état a lieu sur un email (retour bounce, ouverture, clic, ...), on envoie une requête HTTP contenant en POST les informations de l'email en question, vers une URL donnée. Les webhooks servent donc à notifier des scripts externes qu'un événement a eu lieu.

Les webhooks offrent de nombreuses possibilités.

  • Confirmer l'ouverture d'un email
  • Identifier les adresses emails provoquant un retour bounce dans votre système
  • Traiter facilement vos emails de l'envoi à la lecture grâce à l'ajout de paramètre
  • ...

Ajout d'un webhook

Pour utiliser les webhooks, il faut au préalable ajouter votre url recevant l'appel au sein de Tipimail. Pour cela, suivez cette procédure

Vous pourrez tester votre url en cliquant sur le bouton Test afin de simuler un appel et recevoir un exemple d'appel à votre url.

Voici la liste des évenements disponible et leurs descriptions

Evénement Description
Hardbounce L'email n'a pu être délivré et nous avons reçu un retour négatif
Délivré L'email a été envoyé au destinataire et nous n'avons pas reçu de retour négatif
Ouvert Votre destinataire a ouvert l'email
Cliqué Votre destinataire a cliqué sur un lien contenu dans votre email

Traitement des retours

Chaque événement ayant eu lieu sur un email (délivré, ouvert, cliqué) donne lieu a un appel vers l'url fournis. Ainsi si l'email est ouvert plusieurs fois, vous recevez le même nombre de fois l'appel à votre URL.

Les retours sont effectués au format JSON et sont passé en POST à l'adresse communiquée.

Lors de l'appel, nous attendons une réponse HTTP 2XX afin de confirmer que l'URL fournit est bien accessible et que la transmission des données est possible. En cas d'échec, nous retentons à 10 reprises avant de cesser tout appel.

Pour chacun des appels, nous loguons l'information. Seules les appels en erreur sont publiés sur l'application afin de vous aider à réparer toutes éventuelles erreurs.

Voici des exemples de scripts permettant de récupérer les appels.

PHP
NodeJS
								$towrite = @file_get_contents('php://input');
								$retour = urldecode($towrite);

								$file = 'webhook.txt';

								$current = file_get_contents($file);
								$current .= $retour."\n";


								file_put_contents($file, $current);

Enveloppe retour

Voici le détail de chacune des enveloppes de retours

Erreur

Les retours de type erreur surviennent lorsqu'il y a une erreur de synthaxe ne permettant pas l'envoi de l'email comme par exemple une erreur dans l'adresse email du destinataire.

Libellé Type Description
status String "error"
messageId String identifiant du message que nous utilisons en Interne
accountId String identifiant de votre compte que nous utilisons en Interne
statusAt Integer date au format timestamp de l'événement
tags Array of String liste des tags présent dans l'email
meta Array of key-value liste des éléments meta présent dans l'email sous forme de couple clé - valeur
type Integer identifiant du statut de l'email utilisé en Interne
apiKey Integer Clé API maquillée utilisée pour envoyer l'email
msg Array

détails de l'email

Libellé Type Description
from String Expediteur du message
email String Destinataire du message
subject String Objet du message
size Integer Taille du message en ko

Exemple de l'enveloppe retour :

						{
							"status":"error",
							"messageId":"d4e6fze87ez9g879gf9dfe6b",
							"accountId":"564fe6r5gr8g7re9g87re9gb",
							"statusAt":1431434328,
							"tags":[
							],
							"msg":{
								"from":"from@example.com",
								"email":"recipient@example.com",
								"subject":"Renew password",
								"size":7484
							},
							"type":21,
							"apiKey": [redacted]012341
						}

Rejeté

Libellé Type Description
status String "rejected"
messageId String identifiant du message que nous utilisons en Interne
accountId String identifiant de votre compte que nous utilisons en Interne
statusAt Integer date au format timestamp de l'événement
tags Array of String liste des tags présent dans l'email
meta Array of key-value liste des éléments meta présent dans l'email sous forme de couple clé - valeur
type Integer identifiant du statut de l'email utilisé en Interne
apiKey Integer Clé API maquillée utilisée pour envoyer l'email
msg Array

détails de l'email

Libellé Type Description
from String Expediteur du message
email String Destinataire du message
subject String Objet du message
size Integer Taille du message en ko

Exemple de l'enveloppe retour :

						{
							"status":"rejected",
							"messageId":"d4e6fze87ez9g879gf9dfe6b",
							"accountId":"564fe6r5gr8g7re9g87re9gb",
							"statusAt":1431434328,
							"tags":[
							],
							"msg":{
								"from":"from@example.com",
								"email":"recipient@example.com",
								"subject":"Renew password",
								"size":7484
							},
							"type":9,
							"apiKey": [redacted]012341
						}

Hardbounce

Les emails bounces sont les emails qui ont été envoyé depuis notre infrastructure et dont nous avons reçu un retour de type NPAI immédiatement. Cela peut résulter d'une mauvaise orthographe de l'adresse email, de la suppression de l'adresse email ou du domaine.

Libellé Type Description
status String "hardbounced"
description String message de retour que nous avons récu par le serveur de messagerie de votre destinataire
messageId String identifiant du message que nous utilisons en Interne
accountId String identifiant de votre compte que nous utilisons en Interne
statusAt Integer date au format timestamp de l'événement
tags Array of String liste des tags présent dans l'email
meta Array of key-value liste des éléments meta présent dans l'email sous forme de couple clé - valeur
type Integer identifiant du statut de l'email utilisé en Interne
apiKey Integer Clé API maquillée utilisée pour envoyer l'email
msg Array

détails de l'email

Libellé Type Description
from String Expediteur du message
email String Destinataire du message
subject String Objet du message
size Integer Taille du message en ko

Exemple de l'enveloppe retour :

						{
							"status":"hardbounced",
							"description":"550 <recipient@example.com> recipient rejected",
							"messageId":"d4e6fze87ez9g879gf9dfe6b",
							"accountId":"564fe6r5gr8g7re9g87re9gb",
							"statusAt":1431434328,
							"tags":[
							],
							"msg":{
								"from":"from@example.com",
								"email":"recipient@example.com",
								"subject":"Renew password",
								"size":7484
							},
							"type":12,
							"apiKey": [redacted]012341
						}

Délivré

Les emails délivrés sont les emails qui ont été envoyé depuis notre infrastructure et dont nous n'avons pas reçu de retour NPAI.

Libellé Type Description
status String "delivered"
description String message de retour que nous avons récu par le serveur de messagerie de votre destinataire
messageId String identifiant du message que nous utilisons en Interne
accountId String identifiant de votre compte que nous utilisons en Interne
statusAt Integer date au format timestamp de l'événement
tags Array of String liste des tags présent dans l'email
meta Array of key-value liste des éléments meta présent dans l'email sous forme de couple clé - valeur
type Integer identifiant du statut de l'email utilisé en Interne
apiKey Integer Clé API maquillée utilisée pour envoyer l'email
msg Array

détails de l'email

Libellé Type Description
from String Expediteur du message
email String Destinataire du message
subject String Objet du message
size Integer Taille du message en ko

Exemple de l'enveloppe retour :

							{
								"status":"delivered",
								"description":"250 2.0.0 Ok: queued as EC2F93F8E3\n",
								"messageId":"5550b1399932e399465c659c",
								"accountId":"564fe6r5gr8g7re9g87re9gb",
								"statusAt":1431351609,
								"tags":["ecommerce website", "Renew password"],
								"msg":{
									"from":"from@example.com",
									"email":"recipient@example.com",
									"subject":"Renew password",
									"size":112
								},
								"meta":{"uid":"123456","order_id":"123456789"},
								"type":11,
								"apiKey":[redacted]012341
							}

Ouvert

Les emails ouverts sont les emails qui ont été trackés en ouverture et ont effectués la demande de téléchargement d'une image invisible contenu dans l'email.

Libellé Type Description
status String "open"
messageId String identifiant du message que nous utilisons en Interne
accountId String identifiant de votre compte que nous utilisons en Interne
statusAt Integer date au format timestamp de l'événement
tags Array of String liste des tags présent dans l'email
meta Array of key-value liste des éléments meta présent dans l'email sous forme de couple clé - valeur
type Integer identifiant du statut de l'email utilisé en Interne
apiKey Integer Clé API maquillée utilisée pour envoyer l'email
msg Array

détails de l'email

Libellé Type Description
from String Expediteur du message
email String Destinataire du message
subject String Sujet
size Integer Taille du message en ko
tracking Array

liste des éléments concernant le user agent sous forme de couple clé - valeur

Libellé Type Description
ip String Ip du navigateur ayant ouvert l'email
latitude String latitude résultant de l'ip du navigateur ayant ouvert l'email
longitude String longitude résultant de l'ip du navigateur ayant ouvert l'email
country String pays résultant de l'ip du navigateur ayant ouvert l'email
region String region résultant de l'ip du navigateur ayant ouvert l'email
city String ville résultant de l'ip du navigateur ayant ouvert l'email
postcode String code postal résultant de l'ip du navigateur ayant ouvert l'email
operatingSystem String système d'exploitation ayant ouvert l'email
language String langue disponible sur l'ordinateur ayant ouvert l'email
browser String identité du navigateur ayant ouvert l'email
webmail String webmail ayant ouvert l'email
deviceType String Type de périphérique ayant ouvert l'email

Exemple de l'enveloppe retour :

							{
								"status":"open",
								"messageId":"5551af329932e399465c65b5",
								"accountId":"564fe6r5gr8g7re9g87re9gb",
								"statusAt":1431417399,
								"tracking":{
								"ip":"65.55.227.218",
								"latitude":47.6801,
								"longitude":-122.120605,
								"country":"United States",
								"region":"WA",
								"city":"Redmond",
								"postcode":"98052",
								"operatingSystem":"WINDOWS_7",
								"language":"fr-fr,fr,en",
								"browser":"CHROME 39.0.2171.95",
								"webmail":"Unknown",
								"deviceType":"Computer"
								},
								"tags":["ecommerce website", "renew password"],
								"msg":{
									"from":"from@example.com",
									"email":"recipient@example.com",
									"subject":"Renew password",
									"size":112
								},
								"meta":{
									"uid":"123456",
									"order_id":"123456789"
								},
								"open":2,
								"click":1,
								"type":13,
								"apiKey":[redacted]012341
							}

Cliqué

Les emails cliqués sont les emails qui ont été trackés en clique et dont le destinataire a cliqué sur l'un des liens de l'email

Libellé Type Description
status String "click"
messageId String identifiant du message que nous utilisons en Interne
accountId String identifiant de votre compte que nous utilisons en Interne
statusAt Integer date au format timestamp de l'événement
tags Array of String liste des tags présent dans l'email
meta Array of key-value liste des éléments meta présent dans l'email sous forme de couple clé - valeur
open Integer nombre de fois que l'email a été ouvert
click Integer nombre de fois que l'email a été cliqué
type Integer identifiant du statut de l'email utilisé en Interne
apiKey Integer Clé API maquillée utilisée pour envoyer l'email
msg Array

détails de l'email

Libellé Type Description
from String Expediteur du message
email String Destinataire du message
subject String Sujet
size Integer Taille du message
tracking Array

Libellé Type Description
url String url du lien qui a été cliqué
ip String Ip du navigateur ayant ouvert l'email
latitude String latitude résultant de l'ip du navigateur ayant ouvert l'email
longitude String longitude résultant de l'ip du navigateur ayant ouvert l'email
country String pays résultant de l'ip du navigateur ayant ouvert l'email
region String region résultant de l'ip du navigateur ayant ouvert l'email
city String ville résultant de l'ip du navigateur ayant ouvert l'email
postcode String code postal résultant de l'ip du navigateur ayant ouvert l'email
operatingSystem String système d'exploitation ayant ouvert l'email
language String langue disponible sur l'ordinateur ayant ouvert l'email
browser String identité du navigateur ayant ouvert l'email
webmail String webmail ayant ouvert l'email
deviceType String Type de périphérique ayant ouvert l'email

Exemple de l'enveloppe retour :

							{
								"status":"click",
								"messageId":"5551af329932e399465c65b5",
								"accountId":"564fe6r5gr8g7re9g87re9gb",
								"statusAt":1431417410,
								"tracking":{
									"url":"http://www.google.fr",
									"ip":"217.128.197.225",
									"latitude":48.86,
									"longitude":2.350006,
									"country":"France",
									"operatingSystem":"WINDOWS_7",
									"language":"fr,en-US;q=0.8,en;q=0.6",
									"browser":"CHROME 39.0.2171.95",
									"webmail":"Unknown",
									"deviceType":"Computer"
								},
								"tags":["ecommerce website", "renew password"],
								"msg":{
									"from":"from@example.com",
									"email":"recipient@example.com",
									"subject":"Renew password",
									"size":112
								},
								"meta":{"uid":"123456","order_id":"123456789"},
								"open":3,
								"click":1,
								"type":14,
								"apiKey":[redacted]012341
							}

Désabonné

Les désabonnements sont les adresses des destinataires ayant souhaité ne plus recevoir vos emails en cliquant sur le lien de désinscription.

Libellé Type Description
status String "unsubscribed"
messageId String identifiant du message que nous utilisons en Interne
accountId String identifiant de votre compte que nous utilisons en Interne
statusAt Integer date au format timestamp de l'événement
tags Array of String liste des tags présent dans l'email
meta Array of key-value liste des éléments meta présent dans l'email sous forme de couple clé - valeur
type Integer identifiant du statut de l'email utilisé en Interne
apiKey Integer Clé API maquillée utilisée pour envoyer l'email
msg Array

détails de l'email

Libellé Type Description
from String Expediteur du message
email String Destinataire du message
subject String Objet du message
size Integer Taille du message en ko

Exemple de l'enveloppe retour :

						{
							"status":"unsubscribed",
							"messageId":"d4e6fze87ez9g879gf9dfe6b",
							"accountId":"564fe6r5gr8g7re9g87re9gb",
							"statusAt":1431434328,
							"tags":[
							],
							"msg":{
								"from":"from@example.com",
								"email":"recipient@example.com",
								"subject":"Renew password",
								"size":7484
							},
							"type":16,
							"apiKey":[redacted]012341
						}

Marqué comme plaIntes

Les plaIntes sont les adresses de destinataires ayant déclaré votre email comme "indésirable" auprès de leur fournisseur. Certains fournisseurs acceptent de remonter ces plaIntes à l'émetteur via ce que l'on appelle, les "Feed Back Loop".

Libellé Type Description
status String "complaint"
messageId String identifiant du message que nous utilisons en Interne
accountId String identifiant de votre compte que nous utilisons en Interne
statusAt Integer date au format timestamp de l'événement
tags Array of String liste des tags présent dans l'email
meta Array of key-value liste des éléments meta présent dans l'email sous forme de couple clé - valeur
type Integer identifiant du statut de l'email utilisé en Interne
apiKey Integer Clé API maquillée utilisée pour envoyer l'email
msg Array

détails de l'email

Libellé Type Description
from String Expediteur du message
email String Destinataire du message
subject String Objet du message
size Integer Taille du message en ko

Exemple de l'enveloppe retour :

						{
							"status":"complaint",
							"messageId":"d4e6fze87ez9g879gf9dfe6b",
							"accountId":"564fe6r5gr8g7re9g87re9gb",
							"statusAt":1431434328,
							"tags":[
							],
							"msg":{
								"from":"from@example.com",
								"email":"recipient@example.com",
								"subject":"Renew password",
								"size":7484
							},
							"type":18,
							"apiKey":[redacted]012341
						}
© - Tipimail - Sarbacane Software, Tous droits réservés.