Using Preprocessor

A preprocessor is a tool for substituting dynamic content into emails. For example, you can generate product recommendations, add a random selection of products to campaigns, make relevant offers for different segments, etc.

With a preprocessor, you can implement all this without integration with a third service, routine, and useless updating of additional contact fields. You can substitute dynamic content both in bulk and in triggered campaigns.

You can take advantage of two preprocessor types available in eSputnik:

• Key
• Random

Key Preprocessor

The key preprocessor selects a structure from a data array by contacts’ email and passes it to the email template before sending. You can prepare a list of personal recommendations for each contact in the format {email: JSON with recommendations} where email is the key. And when sending a campaign for all contacts with emails from the preprocessor list, each contact will receive their own JSON structure.

This way, you can show each subscriber a unique set of recommended products, promotions and special offers.

File example:

{
    "[email protected]": [
    {
        "name": "book",
        "price": "11"
    },
    {
        "name": "ball",
        "price": "22"
    }, 
    {
        "name": "game",
        "price": "33"
    }],
    "[email protected]": [
    {
        "name": "food",
        "price": "44"
    },
    {
        "name": "drink",
        "price": "55"
    }]
}

Random Preprocessor

The random preprocessor selects several random JSON structures from the prepared data array and sends them to the message.

Use case

You need to sell a large assortment of school backpacks. If you add a static selection of a limited number of bags to the email, they will quickly sell out, while many alternative options will remain unclaimed.

Instead, you can load 100 backpacks with similar quality and prices into the random preprocessor. Then 3 random models will be added to each email. Bags will sell more evenly, and the demand for each item can be verified by the number of sales/clicks generated.

File example:

{
    "recommendations": [
    {
        "name": "rnd1",
        "price": "11"
    },
    {
        "name": "rnd2",
        "price": "22"
    }, 
    {
        "name": "rnd3",
        "price": "33"
    }]
}

The number of elements to be subtracted can be specified in the email in two ways:

a) specify variable in velocity code: $forEachLimit=2
b) don’t use cycle in velocity; instead of this, access elements by index: $data.get('recommendations').get(0) - then the maximum index will be calculated, and the corresponding number of elements will be subtracted.

Implementation Features

For the preprocessor mechanism to work, it is necessary to configure two of its interconnected parts. First, create a file with the data structure in the format required for loading; secondly, add code to the email, with the help of which dynamic content will be generated and substituted into the message when sent.

The key preprocessor allows you to load a personal selection of products for each user, so the data structure should look like this:

{“[email protected]” : [{...}, {...}], “[email protected]” : [{...}, {...}, {...}], “[email protected]” : [{...}, {...}]},

where [email protected], [email protected], [email protected] - recipients’ email addresses, each corresponds to a data array for substitution in the email.

The random preprocessor allows you to select random structures from a selection to substitute them in recipients’ emails. The file structure looks like this:

{“[email protected]” : [{...}, {...}, {...}, {...}, {...}, {...}]},

in this case, you can specify any email; and a single array contains the entire dataset for random selection.

When sending an email, the preprocessor determines which data structure to transfer. The resulting data array can be used in the email using special instructions given in the form of a code. These instructions include conditional statements and loops, allowing you to display dynamic content in the body of the message flexibly.

How to Download a Preprocessor File

There are two options for transferring data files to the system.

Option 1. Using the API

1. Upload a file containing dynamic content in JSON format to be inserted into a message using velocity (API method POST). The response to this request returns a file identifier, which can later be used to update it.
2. Update the already uploaded file (API method POST).
3. Get the status of the uploaded file (API method GET).
4. Select a file in the email and use content substitution for bulk or triggered campaigns (IMCallout - workflow or smartsend method).

You can update the file occasionally, but neither the message nor the workflow needs to be changed. After re-uploading the file, the new content will automatically be used instead of the old one.

Option 2. In your account

1. Go to your account settings -> Preprocessor and click the Upload file button.

2. Select a preprocessor type. For example, let's choose the Key type (the preprocessor with the Random type is configured similarly).
3. Set the file storage time in days. By default, this value is 10 days, with a maximum of 60 days. After this time has elapsed, the file will be deleted from the system and from the list of available files.
4. Upload the file up to 200 MB in the JSON, zip, or tar.gz format.

How to Create Email Using Preprocessor

Apache Velocity engine is used to insert dynamic content into messages. It allows you to implement conditional statements, loops, and other data operations directly in the message body. All dynamic content available on submission is stored in the $data system variable. Select the downloaded preprocessor file in the email. For this:

1. Click on the three dots -> Select PreProcessor in the message editor.

2. Select an already downloaded file from the dropdown list and click Apply.

The file imported at the previous stage will be used when sending the current email.

The data array defined by the preprocessor is placed in the array called recommendations. To access it, use the following construct:

$data.get('recommendations')

To loop through this array, write this:

#foreach($item in $data.get('recommendations'))
$item.get('name')
…
#end

The name of the variable $item can be arbitrary, but the name field must be in each element in the data file, if you are going to address it with such a name in the email.

The conditional operation:

#if($item.get('discount') == 0)
	…
#else
	…
#end

Instead of three dots in both cases, you can substitute an arbitrary HTML code fragment (while maintaining its overall integrity within the email).

If you have any problems with the formation of the velocity code in the email or have questions about more complex examples of its use, please contact our support.

How to Test Message Data

For the key preprocessor, you need to form a group of several contacts with emails from the data file; then, select the desired file in the email and send it to this group.

For the random preprocessor, you can send test email for any address.

Examples of Using Preprocessor

Accessing elements by index

This is what the email looks like in the edit mode:

This is what the result might look like after substituting dynamic content:

Accessing elements in a loop

This is what the email looks like in the edit mode:

This is what the result might look like after substituting dynamic content: