Weekly mail integration

The weekly mail is a staple of batch integrations for retailers. The goal of the mail is to drive traffic to the website, by personalizing these mails the content is tuned to the user, who is therefore more likely to click and go to the website.

In this example we cover a Froomle batch integration for an imaginary retailer "Lorem" that shows the user 2 lists. The first one contains items that are interesting for the user from the whole catalog. The second list contains items that have as brand the "Lorem" house brand.

To set up the batch integration there are 2 major steps:

Getting batch recommendations

Getting batch recommendations is done by uploading a request file to the requests folder on the SFTP. For more information on how to use the SFTP see the API Reference section on the batch recommendations API

Given that we want to send a mail the users will be identified by their user_id. That is a long lived identifier typically linked to the user’s email address.

In this example we will use only 2 users for simplicity, but a typical batch integration has hundreds of thousands of users.

The request file will look as follows:

"lorem","AbaT1sagqq1r",,"Recommended for you",4,"weekly_mail",
"lorem","CdgAgagewaga",,"Recommended for you",4,"weekly_mail",
"lorem","AbaT1sagqq1r",,"From our brand",4,"weekly_mail","Lorem"
"lorem","CdgAgagewaga",,"From our brand",4,"weekly_mail","Lorem"

Things to note about this request file:

  • Per user 2 lines (1 per list to fill in the mail) with a different list_name field.

  • list_name field matches the titles of the lists that will be shown in the mail.

  • lines per user don’t need to be next to each other, they can be, but it is not required.

  • if the recommendations don’t need to be filtered the category_filter field is empty.

  • device_id fields are empty, this is a mail integration, and therefore not linked to devices.

Once the file is uploaded on the SFTP the batch API will start processing it. When ready it will put the response file in the responses folder.

This response file will contain a row per item recommended.

"AbaT1sagqq1r",,"froomle","11211211","12411511511","Recommended for you","item_id_1",1
"AbaT1sagqq1r",,"froomle","11211211","12411511511","Recommended for you","item_id_2",2
"AbaT1sagqq1r",,"froomle","11211211","12411511511","From our brand","item_id_lorem_7",1
"AbaT1sagqq1r",,"froomle","11211211","12411511511","From our brand","item_id_lorem_9",2
"CdgAgagewaga",,"froomle","11211211","52411511541","Recommended for you","item_id_1",1
"CdgAgagewaga",,"froomle","11211211","52411511541","Recommended for you","item_id_10",2

Things to note about the response file:

  • user_id, device_id, list_name are exactly the same as the request

  • If you want to collect the recommendations for a user you combine each row with that user’s identifier, split on list_name so that the items are in their respective lists.

  • campaign_id is the same value for each row in the file. This is the identifier for the batch of recommendations generated. In the events this will need to be used.

  • request_id is the same value for each row per user_identifier, this is the identifier of a user’s recommendation. In the events this also needs to be sent to Froomle.

  • rank is a field used for sorting within a list of recommendations. In our example the 2 lists will each have items with ranks 1 - 4.

Integration events

Using the batch integration introduces a set of specific integration events which you will need to communicate to Froomle. To link these events to the recommendations you will have to use the campaign_id and request_id from the response file in the events. Froomle will use these events to monitor performance and improve the algorithm through AB testing.

Batch open

When the user opens the mail, a batch open event should be sent to Froomle with the campaign_id used to generate recommendations in the mail.


Once a user has opened a mail, the recommendations in that mail will be impressed. At this point a batch impression event for each recommendation should be communicated to Froomle.

Batch click on recommendation

Once a user clicks on one of the recommendation in the mail a batch click on recommendation has to be sent to Froomle.