Mailbridge

Overview

Mailbridge enables you to integrate Taboola recommendations into your newsletters, driving additional revenue and increasing user engagement.

Basic guidelines

📘
Limitations
At present, Mailbridge supports Sponsored Content (SC) only.

🚧
Minimum requirements
In order to use Mailbridge, your email marketing platform must support:

HTML templates

Dynamic macros (see next)

🚧
Dynamic macros
Macros are needed to insert dynamic values.
For example, for GDPR and CCPA, you need to:

Hash (encrypt) the recipient email address and pass it to Taboola.

Pass CMP user consent.

These, as well as other dynamic values, are explained below.
Your email marketing platform might refer to these as variables, functions or macros. The term used is not important, so long as you can pass dynamic values.

📘
A new account for Mailbridge
To get started, your Taboola Account Manager will provide you with a new account for Mailbridge.
This will allow for Mailbridge-specific reporting.

Frequently asked questions

👍
Have more questions?
Take a look at our FAQ.

A bird's-eye view

The following summary provides a bird's-eye view of the integration:

🚧

Add the CSS snippet provided by Taboola to the <head> of your HTML email template.

Optionally tweak the CSS to match your newsletter layout.

For each Taboola unit:

Edit the HTML <table> snippet provided by Taboola. Replace the default placeholders with dynamic macros and custom values.

Add the updated <table> snippet into the <body> of your email template, in the location that you would like the Taboola unit to display.

Which files do I use?

During onboarding, Taboola will provide the following files:

🚧

For each Taboola unit, you will receive a separate file.

In practice, you will typically receive 2 sets of files - one for Flow I (GDPR and CCPA) and the other for Flow II.

Decide which flow you will use - and have the files ready for the steps that follow in this guide.

Each file contains a full HTML page, with:

A <style> tag, in the <head> , with the needed CSS.

A <table> tag, in the <body>, with links and images for that Taboola unit.

For each slot in the Taboola unit, you need to edit 3 URLs (1 anchor tag and 2 image tags).

For example, if the unit contains 4 slots, then there are 12 URLs to edit.

Detailed instructions are provided below.

While following the instructions below, open each file in a text editor (not a web browser).

Add the CSS

Edit any one of the files provided to you by Taboola.

(Each file contains the same CSS.)
Locate the <style> tag (in the <head>) and copy it to the <head>section of your newsletter template.

A sample CSS fragment is shown below:

<style type="text/css">
    #container .reco {
        display: block;
        width: 320px;
        font-size: 0;
    }

    /* show the main option */
    #container .reco .body img {
        width: 100%;
    }

    /* Additional selectors not shown in this sample...  */

    }
</style>

🚧
Guidelines

The CSS code snippet will work for both mobile and desktop.

You can optionally tweak the CSS provided to match your email template more closely.

Edit the HTML

Overall flow

🚧
Guidelines

Perform the following steps for each file (i.e. each Taboola unit).

In practice, you will typically receive 2 sets of files - one for Flow I (GDPR and CCPA) and the other for Flow II. You need to edit one set only.

The HTML snippet will display correctly on both mobile and desktop.

For each Taboola unit:

Edit the file provided, and locate the outermost <table> element.

Each Taboola unit is rendered via a <table> element that contains the needed links and images.
```
   
   <table border="0" cellpadding="0" cellspacing="0" width="258" id="container">
```

Within the above <table element:

Locate each href and src attribute with http://mb.taboola.com.

For each item (aka slot), in the unit, there are 3 URLs that you need to edit (1 anchor tag and 2 image tags). The code fragment below shows the first item, and its 3 URLs.

<!-- In every [src] and [href] attribute,
the [RECIPIENT_HASH_HEX], [sha256|sha1|md5], [INSTANCE_ID],
[SOURCE] and [CMP_VALUE] params should be
replaced with appropriate values -->
<a
    href="http://mb.taboola.com/1.1/png/acme-news/recommendations.click?recipient.hash.hex=[RECIPIENT_HASH_HEX]&recipient.hash.method=[sha256|sha1|md5]&instance.id=[INSTANCE_ID]&widget.placement=thumbnails-a&widget.mode=thumbnails-a&cmp=[CMP_VALUE]&source.url=[SOURCE]&widget.slot=1&newsletter.template=acme-news">
    <img width="250" class="original"
        src="http://mb.taboola.com/1.1/png/acme-news/recommendations.get?recipient.hash.hex=[RECIPIENT_HASH_HEX]&recipient.hash.method=[sha256|sha1|md5]&instance.id=[INSTANCE_ID]&widget.placement=thumbnails-a&widget.mode=thumbnails-a&source.url=[SOURCE]&widget.slot=1&cmp=[CMP_VALUE]&newsletter.template=acme-news" />

    <span class="fallbackWrapper" style="display:none; width: 0px">
        <img class="alt500" style="display:none; width: 0px"
            src="http://mb.taboola.com/1.1/png/acme-news/recommendations.get?recipient.hash.hex=[RECIPIENT_HASH_HEX]&recipient.hash.method=[sha256|sha1|md5]&instance.id=[INSTANCE_ID]&widget.placement=thumbnails-a&widget.mode=thumbnails-a&source.url=[SOURCE]&widget.slot=1&cmp=[CMP_VALUE]&widget.alternative=desktop&newsletter.template=acme-news" />
    </span>
</a>

For each URL, replace the placeholder values with dynamic macros or custom values.

The values that you fill in will be the same across all URLs.
For detailed instructions on filling in macros and custom values, see Flow I and Flow II below.

Flow I - For GDPR and CCPA

🚧
Guidelines

If your users fall under the GDPR or CCPA, then this flow is mandatory.

Otherwise, it is recommended, but not required.

Make sure to copy the code snippets from the relevant file provided - typically labeled with HASH.

E.g. acme-newsletter_HASH_thumbnails-a.txt for the thumbnails-a.txt unit.

For each param in the table below, replace the placeholder text with the required macro or custom value. E.g.

Before: recipient.hash.method=[sha256|sha1|md5]
After: recipient.hash.method=sha256

📘
Which macro should I use?

The exact syntax used will depend on your chosen email marketing platform.

Your platform might refer to these as variables, functions or macros. The term used is not important, so long as you can pass dynamic values.

🚧
All params are required.

Param name	Placeholder text	Type	Instructions
`recipient.hash.hex`	`[RECIPIENT_HASH_HEX]`	Macro	Insert a macro that returns the hashed value of the recipient email address. (The exact syntax will depend on your email marketing platform.) The value generated by the macro in an email run might look like this: `recipient.hash.hex=15dc53cb166c3...23d` ---- For supported hash methods, see the next row.
`recipient.hash.method`	`[sha256\|sha1\|md5]`	Static text	Insert the hash method used. Possible values: `sha256` (preferred method) `sha1` `md5` E.g. `recipient.hash.method=sha256`
`instance.id`	`[INSTANCE_ID]`	Macro	Insert a macro that returns a unique value for each email campaign - e.g. a date stamp or Campaign ID. (The exact syntax will depend on your email marketing platform.) The value generated by the macro in an email run might look like this: `instance.id=1684677174` ---- IMPORTANT: This unique value ensures that different recommendations show for each campaign.
`source.url`	`[SOURCE]`	Static text	Insert the fully-qualified URL for your homepage. E.g. `source.url=https://www.example.com` ---- The URL passed must start with `"https://"` (or `"http://"`).
`cmp`	`[CMP_VALUE]`	Macro	Insert a macro that returns the CMP user-consent value (for GDPR and CCPA compliance). (The exact syntax will depend on your email marketing platform.) Possible values: `0` - user does not consent `1` - user does consent (default) The value generated by the macro in an email run might look like this: `cmp=1`

📘
cmp
If your users fall under the GDPR or CCPA, but are you are unable to pass a CMP signal, consider setting it manually.
For example, you could pass cmp=0 to indicate that recommendations should not be personalized.

👍
For Flow I, continue below: A walkthrough

Flow II - GDPR and CCPA are not applicable

🚧
Guidelines

If your users do not fall under the GDPR or CCPA - and you are unable to hash the recipient email - then use this flow.

Make sure to copy the code snippets from the relevant file provided.

E.g. acme-newsletter_thumbnails-a.txt for the thumbnails-a.txt unit.

For each param in the table below, replace the placeholder text with the required macro or custom value. E.g.

Before: source.url=[SOURCE]
After: source.url=https://www.example.com

📘
Which macro should I use?

The exact syntax used will depend on on your chosen email marketing platform.

Your platform might refer to these as variables, functions or macros. The term used is not important, so long as you can pass dynamic values.

🚧
All params are required.

Param name	Placeholder value	Type	Instructions
`recipient.email`	`[RECIPIENT_EMAIL]`	Macro	Insert a macro that returns the recipient email address (in clear text). (The exact syntax for this macro will depend on your email marketing platform.) The value generated by the macro in an email run might look like this: `[email protected]`
`instance.id`	`[INSTANCE_ID]`	Macro	Insert a macro that returns a unique value for each email campaign - e.g. a date stamp or Campaign ID. (The exact syntax will depend on your email marketing platform.) The value generated by the macro in an email run might look like this: `instance.id=1684677174` ---- This unique value ensures that different recommendations show for each campaign.
`source.url`	`[SOURCE]`	Static text	Insert the fully-qualified URL for your homepage. E.g. `source.url=https://www.example.com` ---- The URL passed must start with `"https://"` (or `"http://"`).

A walkthrough

The following, high-level walkthrough illustrates how to insert dynamic macros and custom values.

To start the walkthrough, click on the button below:

👉

Walkthrough - insert dynamic macros

Open Recipe

Add the HTML

For each Taboola unit:

Add the <table> code snippet (that you edited above) to your email template, in the location that the unit should display.

The HTML snippet will display correctly for both mobile and desktop.

📘
Tip
If your email marketing platform supports custom HTML blocks:

Insert a custom HTML block, in a location of your choosing.

Copy the <table> code snippet to your custom HTML block.

Verify your integration

Now that you have completed the integration, it's time to give your integration a test-run!

To minimize friction, we recommend the following steps.

Perform a test run of your campaign, and open the email received.
Verify that:
1. Each Taboola unit displays as expected.
2. Clicking on an item takes you to its target URL.

Troubleshooting

If you encounter issues, follow the steps below.

📘

Check that you have updated each HTML code snippet correctly, as described above.

Make sure that your updated HTML is well-formed:

Attributes are enclosed in quotation marks - e.g.<img width="200" border="0" class="original" src="http://mb.taboola.com/1.1/png/..."

Each additional param is preceded by an & character - e.g. ...&recipient.hash.method=sha256&...

No spaces were mistakenly added. For example, the following will not work:
src=" http://mb.taboola.com/1.1/png/..."

For assistance, reach out to your Taboola Account Manager. Make sure to forward the email received from your test run of the campaign.

Forward the email itself - not an EML attachment.

Well done!

If everything is working smoothly, your integration is complete! 👏

Appendix

Taboola params

The following params are pre-filled by Taboola. These are provided for your information only - no action is required on your side.

Param name	Type	Description
`widget.placement`	Pre-filled by Taboola	The name of the Taboola unit. ---- - Used for Taboola reports. - Acts as a unique identifier, when there are multiple Taboola units in a single newsletter.
`widget.mode`	Pre-filled by Taboola	The specific UI (layout) for the Taboola unit. ---- The same `mode` is used for both mobile and desktop.
`widget.slot`	Pre-filled by Taboola	The slot (position) of a given item, within the Taboola unit - numbered from left to right, then top to bottom.
`newsletter.template`	Pre-filled by Taboola	When there are multiple Taboola units in a single newsletter, the `newsletter.template` groups the requests to avoid duplicate recommendations.

Mailbridge

Overview

Basic guidelines

📘
Limitations

🚧
Minimum requirements

🚧
Dynamic macros

📘
A new account for Mailbridge

Frequently asked questions

👍
Have more questions?

A bird's-eye view

🚧

Which files do I use?

🚧

Add the CSS

🚧
Guidelines

Edit the HTML

Overall flow

🚧
Guidelines

Flow I - For GDPR and CCPA

🚧
Guidelines

📘
Which macro should I use?

🚧

📘
`cmp`

👍

Flow II - GDPR and CCPA are not applicable

🚧
Guidelines

📘
Which macro should I use?

🚧

A walkthrough

Add the HTML

📘
Tip

Verify your integration

Troubleshooting

📘

Well done!

Appendix

Taboola params

Overview

Basic guidelines

📘Limitations

🚧Minimum requirements

🚧Dynamic macros

📘A new account for Mailbridge

Frequently asked questions

👍Have more questions?

A bird's-eye view

🚧

Which files do I use?

🚧

Add the CSS

🚧Guidelines

Edit the HTML

Overall flow

🚧Guidelines

Flow I - For GDPR and CCPA

🚧Guidelines

📘Which macro should I use?

🚧

📘cmp

👍

Flow II - GDPR and CCPA are not applicable

🚧Guidelines

📘Which macro should I use?

🚧

A walkthrough

Add the HTML

📘Tip

Verify your integration

Troubleshooting

📘

Well done!

Appendix

Taboola params

📘
Limitations

🚧
Minimum requirements

🚧
Dynamic macros

📘
A new account for Mailbridge

👍
Have more questions?

🚧
Guidelines

🚧
Guidelines

🚧
Guidelines

📘
Which macro should I use?

📘
`cmp`

🚧
Guidelines

📘
Which macro should I use?

📘
Tip