Skip to main content

Integration: Email Integration (Legacy)

Note: This Email Integration method is not available to new clients.  See Email Setup in our Recommend documentation for current implementation.


This document will provide guidance on integrating Recommend+Email on a retailer’s ESP (Email Service Provider). Starting with setting up a layout and a placement on Algonomy's system, and then inserting the code on the email campaign, this document guides you through making all the preparations to send Algonomy's Recommendations in emails.


Clients interested in using Recommendations+Email will benefit most from this document if they are familiar with HTML and JavaScript, have a background in the ecommerce/retail industry, and understand how to populate values in an ESP template.


Recommend enhances emails by displaying relevant, targeted product recommendations on a customer-by-customer basis, driving site visits and higher sales while strengthening customer relationships. It seamlessly integrates into your existing email campaigns and automatically generates product recommendations targeted towards specific marketing and merchandising objectives.


Each ESP has a different process for going live.  Be sure to understand the requirements before getting started.

How It Works

At a high level, the HTML “stub” which lives in the email source, gets populated by the ESP with a number of product- and customer-related fields in the image source and imagemap HREF parameters.

  • When the user opens an email containing {rr} HTML, an image request is made to the recommendations platform, passing parameters such as Order ID, Customer ID, Product ID(s), etc.
  • {rr} sends back the recommended products as an image map. The image is built by applying an HTML template to product data, and is returned to the user’s email.
  • Upon image generation, {rr} tracks which products were recommended, caches the image, and stores the matching clickthru URLs for products in each position in the image.

Note: Please make sure to work with your Client Services Team in order to properly configure the solution and receive the platform training.


Integration method overview

Website (one-time) Set up

*Note: if Recommend is already installed on your website, you can skip to Email Setup

Integrating Recommend into email begins by placing JavaScript tags on select pages of your website so Algonomy can collect the product and behavioral data necessary to serve targeted recommendations in email.

Please work with your Client Services team to get your website set up. 

Email Setup  

After you identify which email campaigns to add recommendations to, you need to copy/paste your Algonomy generated HTML into the email templates in order for personalized product recommendations to be displayed when the email is opened.

A typical workflow follows:

  1. The Merchant (or the Merchant’s ESP) delivers the look and feel for the e-mail recommendations to Algonomy in the form of:
    1. A mock-up of the entire e-mail as it will appear to the merchant’s customers (including recommendations)
    2. The email templates, with comments indicating where our markup is to go so the recommendations show up in the right place
    3. Pixel dimensions and hex codes for all attributes in the recommendation slot
  2. If applicable, the Merchant delivers the product IDs for any desired “default” recommendations to Algonomy. Default recommendations are used when the context provided is so narrow that no recommendations apply or when strategies have no recommendations to display.

At this point, Algonomy sets up the HTML layout that will be returned when a call is made to Algonomy. Algonomy Integration Engineer will provide the name of the layout (used for parameter ZoneName) back to the Merchant.

The Merchant can now set up any chosen campaign, using a unique name for each for reporting/tracking purposes. Using the variables defined in this document, the merchant can pass specific context given the purpose of the campaign.

After the customizations are finalized, the ESP triggers a test email for final approval by the merchant.

*Note: If the ESP grants us the ability to trigger test mails, Algonomy can handle this step.

All steps up to this point are performed in an integration environment. Once Algonomy has sign-off, we will migrate the layout to the production environment and make any necessary changes to the Algonomy markup in the email template. Once we have sign-off on the HTML customizations from the merchant and ESP, we will go live in production.

Note: Each ESP has a different process for going live.

Algonomy caches the email HTML for three months for each user so that the same images return even if the memory cache is reset. After three months, the recs are rebuilt from scratch to avoid stale recs, inaccurate pricing, or product unavailability.

By default, the proposed solution follows the steps described below:


  1. The ESP prepares the email campaign, with Algonomy's code in the right position;
  2. The ESP sends the email;
  3. The customer opens the email in an email client;
  4. The email client requests the recommendations from Algonomy's servers;
  5. Algonomy’s solution will prepare the recommendations based on the strategies and rules configured;
  6. Algonomy's servers send the generated recommendations back to the email client;
  7. The email client displays the campaign to the customer.

Note that the generated recommendation images will be cached on Algonomy's servers for 48 hours. This will allow a faster rendering when the customer opens the campaign email again.

Dashboard configuration


The first configuration we need to do is to add a new layout on Personalization Cloud dashboard. This must be a HTML layout that matches the visual identity of the campaign. Typically, it has tables and in-line CSS for cross-client compatibility (e.g. Gmail, Outlook, Yahoo, etc.).

NOTE: You can work with Algonomy's Client Services Team to set up the layout.


After creating the layout, we need to create the placement for the campaign and associate the layout with it. The placement will:

  • Specify the minimum number of items returned;
  • Specify the maximum number of items returned;
  • Serve as reference to create merchandising rules;

Layout and Placement testing

In order to test the layout and placement created in Personalization Cloud dashboard, please ask your Client Services Team to send you an example page. They will set up a sample page where you can verify the layout rendering and the configured rules.

ESP Integration

For the ESP integration there is a need to insert some <a> and <img> tags on the campaign. Moreover, there is a need to change some required parameters in order to have the recommendations fully functional. To view the available parameters, see Email Integration Parameters

Sample HTML code

For a sample of the HTML code to be used, see Email Integration Sample HTML Code


  • Was this article helpful?