1. Documentation
  2. Integrate
  3. Webhooks

Using Webhooks

Introduction

How Webhooks work is quite simple: when an event or a status change on an email (bounce return, open, click, ...), an HTTP POST request is sent to a given URL. This POST call contains information of the email in question. The webhooks serve to notify external scripts that an event occurred

Webhooks offer many opportunities.

  • Confirm open an email
  • Identify email addresses causing a bounce return in your system
  • Easily handle your emails from sent to the reading by adding parameter
  • ...

Add a webhook

To use webhooks, you must first add your url receiving the call within Tipimail. To do this, follow these procedure

You can test your url by clicking on the Test button to simulate a call and to receive an example.

Here list of events available on Tipimail and the descriptions

Events Description
Hardbounce Email can't be delivered and we have received a negative return
Delivered Email has been sent to the recipient and we haven't received a negative return
Open Your recipient has opened the email
Clicked Your recipient has clicked on a link

Handle returns

Every event happens on an email (delivered, open, click) results in a call to the url provided. So if the email is opened multiple times, you receive the same number of times the call to your URL

Returns are done in JSON format and are passed with POST to the URL provided.

During the call, we expect an HTTP response 2XX to confirm that the URL is available and provides that data transmission is possible. If that fails, we retry 10 times before stopping all calls.

For each call, we log information. Only calls in error are published on the application to help you fix any possible errors.

Here scripts examples to retrieve calls.

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);

Return enveloppe

Here are the details of each of the envelopes returns

Error

Errors returns happen when we can't delivered emails because there are a mistake on the recipient's email address for example.

Label Type Description
status String "error"
messageId String Internal message id
accountId String account id
statusAt Integer timestamp date of the event
tags Array of String list of tags include on the email
meta Array of key-value list of meta items (key and value)
type Integer Internal email status id
apiKey Integer Redacted api key used to send the email
msg Array

email details

Label Type Description
from String Sender
email String Recipient
subject String message subject
size Integer message size on kb

Example of return:

						{
							"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
						}

Rejected

Label Type Description
status String "rejected"
messageId String Internal message id
accountId String account id
statusAt Integer timestamp date of the event
tags Array of String list of tags include on the email
meta Array of key-value list of meta items (key and value)
type Integer Internal email status id
apiKey Integer Redacted api key used to send the email
msg Array

email details

Label Type Description
from String Sender
email String Recipient
subject String message subject
size Integer message size on kb

Example of return:

						{
							"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

Bounces emails are emails that have been sent from our infrastructure and we have received a return immediately that the email cann't be delivered. This can result from improper spelling of the email address, deleting the email address or domain.

Label Type Description
status String "hardbounced"
description String return message that we received by your recipient's mail server
messageId String Internal message id
accountId String account id
statusAt Integer timestamp date of the event
tags Array of String list of tags include on the email
meta Array of key-value list of meta items (key and value)
type Integer Internal email status id
apiKey Integer Redacted api key used to send the email
msg Array

email details

Label Type Description
from String Sender
email String Recipient
subject String message subject
size Integer message size on kb

Example of return:

						{
							"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
						}

Delivered

The delivered emails are emails that have been sent from our infrastructure and we have not received back from ISPs.

Label Type Description
status String "delivered"
description String return message from server
messageId String Internal message id
accountId String Internal account id
statusAt Integer timestamp date of the event
tags Array of String list of tags
meta Array of key-value list of meta items
type Integer Internal status id
apiKey Integer Redacted api key used to send the email
msg Array

email details

Label Type Description
from String Sender
email String Recipient
subject String message subject
size Integer message size on kb

Example of return:

							{
								"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
							}

Open

Open emails are emails that were tracked as open and have made the request to download an invisible image content in the email.

Label Type Description
status String "open"
messageId String Internal message id
accountId String Internal account id
statusAt Integer timestamp date of the event
tags Array of String list of tags
meta Array of key-value list of meta items
type Integer Internal status id
apiKey Integer Redacted api key used to send the email
msg Array

email details

Label Type Description
from String Sender
email String Recipient
subject String Subject
size Integer message size on kb
tracking Array

user agent's details

Label Type Description
ip String Ip resulting from the browser that opened the email
latitude String latitude resulting from the browser that opened the email
longitude String longitude resulting from the browser that opened the email
country String country resulting from the browser that opened the email
region String region resulting from the browser that opened the email
city String city resulting from the browser that opened the email
postcode String post code resulting from the browser that opened the email
operatingSystem String OS
language String langue available of the device
browser String Browser that opened the email
webmail String webmail ayant ouvert l'email
deviceType String Device type who opened the email

Example of return:

							{
								"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
							}

Clicked

Clicked emails are emails that recipient clickedon a tracked email

Label Type Description
status String "click"
messageId String Internal message id
accountId String Internal account id
statusAt Integer timestamp date of the event
tags Array of String list of tags
meta Array of key-value list of meta items
open Integer number of times the email was opened
click Integer number of times the email was clicked
type Integer Internal status id
apiKey Integer Redacted api key used to send the email
msg Array

email details

Label Type Description
from String Sender
email String Recipient
subject String Subject
size Integer email size
tracking Array

User agent's details

Label Type Description
url String clicked link
ip String Browser ip that opened the email
latitude String latitude from IP that opened the email
longitude String longitude form IP that opened the email
country String Country from IP that opened the email
region String region from IP that opened the email
city String city from IP that opened the email
postcode String Postcode form IP that opened the email
operatingSystem String Computer OS that opened the email
language String Compteur language that opened the email
browser String Browser id that opened the email
webmail String webmail used to open the email
deviceType String Device type having opened the email

Example of return:

							{
								"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
							}

Unsubscribed

Unsubscribes are based on a specific tracking link you add to your email. When clicking, your recipients show they no longer wish to receive your emails.

Label Type Description
status String "unsubscribed"
messageId String Internal message id
accountId String account id
statusAt Integer timestamp date of the event
tags Array of String list of tags include on the email
meta Array of key-value list of meta items (key and value)
type Integer Internal email status id
apiKey Integer Redacted api key used to send the email
msg Array

email details

Label Type Description
from String Sender
email String Recipient
subject String message subject
size Integer message size on kb

Example of return:

						{
							"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
						}

Complaint

ComplaInts are return emails from ISPs after your recipients clicked a dedicated button. Some providers report complaints to the sender so called "Feed Back Loop".

Label Type Description
status String "complaint"
messageId String Internal message id
accountId String account id
statusAt Integer timestamp date of the event
tags Array of String list of tags include on the email
meta Array of key-value list of meta items (key and value)
type Integer Internal email status id
apiKey Integer Redacted api key used to send the email
msg Array

email details

Label Type Description
from String Sender
email String Recipient
subject String message subject
size Integer message size on kb

Example of return:

						{
							"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, All rights reserved.