Using Preprocessor

Preprocessor is a mechanism for constructing dynamic content in letters on the basis of data prepared beforehand: recommendations in letters, the mutual order of blocks, random selection of goods, and urgent offers for different user categories.

All these can be realized with a preprocessor without integration with the third service, routine and useless updates of additional contact’s fields, and using both for mass mailing and trigger emails.

Besides, you can use personalization not only in emails but also in SMS messages. 

Сapabilities of Preprocessor are very wide, and they are not limited by existing functionality. We can easily expand them by adding new logic of external data handling. So if you need a unique or even “strange” feature, email us; we will discuss it and try to shortly realize your requirements.

Supported Types

Next types of preprocessors are available now for public use:

• Key 
• Random

Key Preprocessor

Chooses the structure from the data array by indicated key, for example, by email, and transfers it into the email template before sending. You can prepare the list of personal recommendations especially for each contact in {email: json with recommendations} format, where email acts as a key. And when sending the mailing for all contacts with the email from the list of a preprocessor, one’s JSON will be received, and it will be used in the letter.  

This approach can show each subscriber its own set of recommended goods, the sales, 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

Chooses randomly several JSON structures from the prepared data array and transfers them in the letter. You certainly heard that block in the letter with good offers works very well. Imagine that you have a big contact database and a huge assortment of goods. For example, you want to propose rucksacks for school for the very fetching price. If a specific rucksack will be indicated, it will be sold fast and there needs to be an alternative for other clients.

At the same time, you have 100 identical rucksacks in quality and attraction. They can all be loaded in Random preprocessor, and 3 random models can be shown in each letter. Then rucksacks will be sold approximately evenly, and success of each item can be checked by the sale quantity / transfers that they brought.

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

The recipient address is not used in this case. Data is selected randomly from a single array.

The number of elements to be selected can be defined in the message in one of the following ways:

1. Specify a variable in the Velocity code, for example: $forEachLimit = 2;
2. Do not use a Velocity loop and access elements by index instead, for example: $data.get('recommendations').get(0).

In this case, the maximum index is calculated and the corresponding number of elements is selected.

How It Works

In this section, the accent is more for the technical part of realization. If you are not a programmer and understood nothing here, don’t be upset – it is not necessary. But for receiving the conception of insides – I recommend you to become acquainted with this section.

It is necessary to configure two interrelated parts of the preprocessor for its mechanism started to work. Firstly, to create a file with the data structure in necessary format for loading. Secondly, add code in the letter, with the help of which the dynamic content will be generated and placed in the letter on-the-fly when sending it.

The Key type preprocessor allows loading personal set of goods for each client that is why the data structure needs to be next:

{
  "[email protected]": [
    {},
    {}
  ],
  "[email protected]": [
    {},
    {},
    {}
  ],
  "[email protected]": [
    {},
    {}
  ]
}

where [email protected], [email protected], [email protected] – recipient email-address (or phone number), the data array for substitution in the letter corresponds to each of them.

Random type preprocessor allows choosing random structure from the set for placing them in letters for recipients. The file structure for it looks following:

{
  "[email protected]": [
    { ... },
    { ... },
    { ... },
    { ... },
    { ... },
    { ... }
  ]
}

in this case, any email can be indicated – it doesn’t matter; and the only array contains all data set for random selection.

When sending messages, the preprocessor determines, exactly what data structure will be transferred in the letter. If Key type is used – the structure, assigned for a specific recipient, is transferred; if Random type is used – the structure is determined in random order. The resulting data array can be used in the letter with the help of special instructions, indicated as a code. These instructions include conditional operators and cycles that allows showing in a sufficiently flexible way the dynamic content in the body of the letter.

📘

Note

The preprocessor also can be used for SMS-mailing. The principles of its work for SMS stay the same.

Uploading a Preprocessor File

There are two ways to transfer a data file to the system.

Option 1. Using API

The API-based file upload mechanism that allows you to transfer a data file to the system works as follows:

1. Upload a file containing dynamic content in JSON format for insertion into an email using Velocity (API method POST Upload file for preprocessor).
2. Update the previously uploaded file (API method POST Update file for preprocessor).
3. Get the status of the file being uploaded or already uploaded (API method GET Get preprocessor file status).
4. Select the file in the email and use content substitution during campaigns or triggered single sends (IMCallout — via a workflow or the Send prepared message method).

Option 2. In Personal Account

To upload a file using the Personal account, carry out the following actions:

1. Go to your account settings → Preprocessor tab and click Upload file.

2. Choose preprocessor type, for example, we will choose Key type (setting preprocessor with Random type will be similar).

3. Set the file storage time in days. The default value is 10 days, and the maximum is 60 days. After this period expires, the file is deleted from the system and removed from the list of available files.
4. Drag and drop the file into this area or click to upload it from your computer. The file must be in json, zip, or tar.gz format. The maximum file size is 200 MB.

5. Click Upload.

The notification about successful uploading will be sent as a message in your Personal account and via email.

Creating Email Using Preprocessor

For inserting dynamic content in the message the special template processor is used – Apache Velocity. Exactly it allows realizing conditional operators, cycles and other operations with data directly in the body of the letter. All dynamic content, available when sending, is contained in special system variable $data. After loading the file it needs to be chosen when forming the message.

Selecting a Preprocessor File

1. Create an email in the editor.
2. Open the three-dot menu and click Select preprocessor.

3. Choose preprocessor type (for example we chosen Key type, for adding file with Random type preprocessor actions will be similar).

4. Choose file, uploaded during the previous stage.

Thus, the file uploaded in the previous step will be used when sending the current message.

Using Preprocessor Data in Velocity

Data array, determined by the preprocessor, is contained in the array with recommendations name. To obtain access to it, use the following construction:

$data.get('recommendations')

For organizing cycle by this array, write the following.

The name of $item variable can be arbitrary, but the field with the name name needs to be contained for each element in the file with data, if you are going to address to it in the letter by such name.
Conditional operation can also be easily done:

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

Instead of ellipsis in both cases you can substitute arbitrary fragment of HTML-code (though keeping its general integrity within the limits of the letter).

Testing Data for Campaign

There is very convenient functionality in the development stage: the review of a prepared letter for a specific recipient. When it will be ready, you will be able to specify email of a specific recipient and see the letter, which will be formed for him by the preprocessor. We will make all efforts for realizing this opportunity as soon as possible.

From already available facilities for testing, we can offer the mailing for the test group. For Key type preprocessor it is necessary for you to form a group of several contacts, whose emails will be contained in the data file; then choose necessary file in the message and activate mailing for this group. In the case with Random type preprocessor there is no need to additionally worry about existence of addresses in the file – it can be tested for any addresses.

Examples of Use

Addressing Elements by Index

The result after substitution of dynamic content can look in the following way:

The letter in edit mode looks in the following way:

Addressing Elements In the Cycle

The letter in edit mode looks in the following way:

The result after substitution the dynamic content can look in the following way:

If you have problems with forming velocity-code in the letter, or you have more questions for more difficult examples of its use, then described in this section – address to our technical support.