1. Documentation
  2. Integrate
  3. Headers

Headers

Headers allow you to custom your emails as you want. The idea is to choose what to turn on or integrated in all emails you have generated regardless of the content or settings.

Headers are grouped into two categories :

  • Editing the configuration of sending
  • Editing content

Using headers

Headers are composed of parameters on JSON format.

Example : 

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

Custom Headers can be used on several ways

On the header of the email

Using custom header on the header on the email is restricted according the programming language used and maybe different. But the syntax is always the same "X-TM" following by the action (Example: X-TM-TRACKING). Example for each programmaing language are available on the configurator

On the subject

You just have to send parameters on JSON by beginning and ending your custom header by "|" caracters

Example: 

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

By adding comment on the content of your email

You just have to send parameters on JSON by beginning and ending your custom header by "|" caracters

Example:

Sending configuration

Tipimail allows you to define some parameters on the interface like enable tracking. Sending configuration headers allow you to override this configuration and enable or disable options depending on emails.

Domain : X-TM-DOMAIN

By default, we set the domain according the sender email address. If the domain is not available, we send emails with another random valid domain or with the mutualized domain. This header allows you to force the domain used.

Voici les paramètres disponibles

Parameter Type Example
string tipimail.com

Here an exemple

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

Tracking : X-TM-TRACKING

This header lets you enable or disable the tracking and select the type of tracking

Here parameters availables

Parameter Type Value Example
html array with following content
Parameter Type Value Example
open integer
  • 1 : activate open tracking of the email on html format
  • 0 : desactivate open tracking of the email on html format
 "open":1
click integer
  • 1 : activate click tracking of the email on html format
  • 0 : desactivate click tracking of the email on html format
 "click":0
activate or not tracking on open and click for html version of your email "html":{"open":1,"click":0}
text array with following items
Parameter Type Value Example
click integer
  • 1 : activate click tracking of the email on text format
  • 0 : desactivate click tracking of the email on text format
 "click": 1
activate or not tracking on open and click for text version of your email "text":{"click": 1}

Here an example of header tracking

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

Google Analytics : X-TM-GOOGLEANALYTICS

This header allows you to activate and personalize tracking with Google Analytics on your links

Here parameters availables

Parameter Type Value Example
enable integer
  • 1 : activate Google Analytics tracking
  • 0 : desactivate Google Analytics tracking
 "enable" : "1"
utm_source string Source of your email "utm_source" : "Transactional Email"
utm_medium string Media of your email "utm_medium" : "email"
utm_content string email content "utm_content" : "order confirmation"
utm_campaign string campaign "utm_campaign" : "Ecommerce website"

Here an exemple

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

Tags : X-TM-TAGS

This header allows you to add tags on your emails. These tags are used to filter and split your data. You can split email according the origin or the aim of the email. Tags are not visible by the recipients

Here parameters available

Parameters Type Example
array of string ["welcome", "website1"]

Here an exemple

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

Meta : X-TM-META

This header allows you to add personnalize items. These items can be an unique id, an order number or anything can be useful for you. Items will not be send and present on the recipients' email. Only webhooks can retrieve those data and handle them.

Here parameters

Parameters Type Example
array of key-value {"order_id":"123456789","shipment_id":"123456789"}

Here an example

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

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

This header activate bulk sending. It is important to enable this header if you want to send bulk email. We will be able to handle in different way than transactional email and use the dedicated infrastructure.

Here parameters available

Parameters Type Example
integer
  • 1: activate bulk mode
  • 0: desactivate bulk mode

Here an example

"X-TM-BULK":1

IP : X-TM-IPPOOL

Thise header helps you to define the IP used to send your email (only for dedicated IP).

Here parameters available

Parameters Type Example
string IP address

Here an exemple of bulk header

"X-TM-IPPOOL":"192.168.1.1"

Personnalize your send

Tipimail allows you to personnalize content of the email by replacing dynamic value.

Text version : X-TM-TEXTVERSION

Create a text version of your email from html version

Here parameters available

Parameters Type Example
int 1 or 0

Here an example

"X-TM-TEXTVERSION":1

Unsubscribe : X-TM-BLACKLIST

This header allows you to manage unsubscribe by adding them on a dedicated list. First, you have to add a special link on your HTML or Text content. Then, with the header, you can define the unsubscribe list where adding the recipient. With the special link, we will be able to know which recipients have clicked on the link

Here parameters to add on the content of your email

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

Here the syntax to define the list

"X-TM-BLACKLIST":"unsub-list"

Personnalize data : X-TM-SUB

Sub header allows you to personnalize the content of the email, to replace dynamic content according the recipient or some arguments.

The most common cases of dynamically replacement is the civility or the recipient's name. With dynamic content, you can go further in customizing your email

The possibilities are endless:

  • Add products to cross sell depending on the recipient's order
  • Change the CSS to your email according to the recipient's gender
  • Send different subjects depending on the destination
  • Add the data of your information system in the email to confirm that the recipient has read your email

Here use cases

Use case 1 : replace the variable

To add personalized content, here is the procedure:

  • Add the variables necessary to be replaced in the content of your email. To identify the variable that we have to replace it, you must surround it by double brackets as shown in the following example: {{name}}
  • Add header in the variable name and its value and for each of the email addresses of the recipients

When Tipimail will generate email, it will scan all email addresses defined by the "To" and check if there are variables to replace.

Use case 2: linking information from a recipient

It may be interesting to add important data (user ID, control) provided by your IT system in an email. These data allow you to connect your users to perform different treatments.

Example:

  • A unique identifier used to identify the recipient where email address is not the primary key
  • Use a username instead of the message ID to track the status of this email

    • To transmit its data without inserting them in the email and therefore it is not visible to the recipient, you simply add the data in the "meta" of the custom header for each recipient.

    Here parameters availables

    Parameters Type Value Example
    email string email adresse of the recipient "email":"email@example.com"
    values array of key-value couple of key value containing the data to replace. The placeholders in the email must be between the following tags {{...}} "values":{"first_name": "Firstname", "last_name": "Lastname"}
    meta array of key-value You can add own meta data to that recipient. "meta":{"unique_id": "987654321", "order_id": "132456798", "shipment_id": "1237498798"}

    Here an example

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

    Here the result of the email

        Hi {{first_name}} {{last_name}}
    
    Thanks for the record, you ID is the : {{unique_id}}

    Here the result for the recipient: email1@example.com

        Hi Firstname1
    
    Thanks for the record, you ID is the : 123456789

    Here the result for the recipient: test2@example.com

        Hi Firstname2
    
    Thanks for the record, you ID is the : 987654321

    Most of the time, email address is used as a key to transmit information. But in some cases, the same email address can be shared between several people, typically M and Ms sharing their email address.

    To use this feature, just need you to do in the sub header, information about each person in two different nodes as shown in the example below. We must pass once the email address in question in the To parameter

            				{
        					"X-TM-SUB":
        					[
        						{
        							"email": "email1@example.com",
        							"values":
        							{
        								"civility" : "Mister",
        							},
        						},
        						{
        							"email": "email1@example.com",
        							"values":
        							{
        								"civility" : "Miss",
        							},
        						}
        					]
        				}

    Template : X-TM-TEMPLATE

    This header allows you to send an email with a template saved on Tipimail. With Template, you just have to send the template name, the value of each variables instead of all your emails.

    Here parameters available

    Parameters Type Example
    string template's name

    Here an example

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

    Using template is better with SUB to replace data. Here a complete example where I want to replace "name" variable on the content of my template

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

    Header limits

    The RFC for SMTP communications impose several limitations:

    • You are limited to a size of 200 octects for the envelope JSON
    • You are limited to 1000 characters per header. If you exceed this limit, it will separate the header
© - Tipimail - Sarbacane Software, All rights reserved.