Dictionaries allow for endless personalization of content for each contact. If you use contact fields, you are limited to standard fields like first name, last name and around 20 custom fields. Even though our custom fields are generous at 1000 characters each, it may not be enough in number and size.
If you run out of the limit with contact fields, you can use dictionaries.
Your content can be loaded into dictionaries, which can be images, entire paragraphs, text or any other content, and then you can cross-reference content and people. This way, you can have as many "custom fields" as you need. In some extreme cases, our customers have loaded a few hundred thousand of their products into our system and cross-referenced them across hundreds of thousands of their subscribers.
Dictionaries add the capability to store name/value pairs on your account to merge into templates.
They remove the need to send the same data over and over to the API and allow you to endlessly expand the merging options for your audience.
A single dictionary may represent a product with attributes, where each attribute name is some property of a product (name, description, price, URL to image, etc.).
In other cases, a dictionary can be a set of internationalized messages, where each dictionary is a collection of messages in different languages (English, French, etc.)
Example A dictionary has a name and a number of key/value pairs. For example:
Dictionary name: sandwitch1
Key | Value |
---|---|
name | Turkey Pastrami |
image_url | <img src='http://sandwitchblink.com/images/turkey.png'> |
Dictionary name: sandwitch2
Key | Value |
---|---|
name | Rye Ruben |
image_url | <img src='http://sandwitchblink.com/images/ruben.png'> |
In addition, we allow creation of up to 20 special dictionary mapping sets. Dictionary Mapping sets exist for each and every contact and allow to map a contact to data stored in dictionaries during a merge process.
Dictionary Mappings (also called recommendation sets) for contacts contain so-called JSON documents. Example of such document for one subscriber:
{
"name" : "sandwich1.name",
"description" : "sandwich1.description",
"price" : "sandwich1.price",
"image_url" : "sandwich1.url"
}
and for another subscriber:
{
"name" : "sandwich2.name",
"description" : "sandwich2.description",
"price" : "sandwich2.price",
"image_url" : "sandwich2.url"
}
Each document is loaded into a corresponding Mapping Set for each contact. You can configure up to 20 such sets per contact. In the documents above, the keys are placeholders matching template merge tags, and values are pointers to specific dictionary keys.
The newsletter template will simply refer to merge fields using keys from the JSON documents:
<html>
<body>
Best sandwich money can buy: ${name}!<br>
Satisfy your hunger:
<hr>
${image_url}
</body>
</html>
This will result in the first subscriber to see offer for sandwich1
, and the second will see the sandwich2
from the dictionary.
Merging process:
When we process this template for a customer, we:
${name}
.name
-> sandwich1.name
.sandwich1
and pull up a value of its attribute name
.Setting up a campaign with dictionaries follow these steps:
A personalized campaign will be send, where each contact will be getting content that was set according to dictionaries and personal mappings.
ExpressPigeon provides 20 dictionary sets. This allows customers to rotate them in and out of campaigns.
For example, if a field 1 was used today, a sender has 19 more fields left to map subscribers to products before they run out.
When a customer clicks “View online” link, EP displays the same newsletter in browser. If the corresponding mapping field is preserved, EP will display a merged newsletter with exactly the same content as was sent. If the merge field was augmented, EP will display products that map to new values. This feature can be used to advantage when selling perishable products or any content that expires.
Dictionary Mappings make possible some interesting scenarios. Lets say dictionary mappings are loaded, an so are lists of contacts. Newsletter are created and use keys from dictionary mapping documents. At this point, the sender can simply update data in the dictionary pairs using API, and trigger new campaigns.
## Merge preview in UI
You can preview a template for a specific person an have all dictionary data as well as custom fields merged. This allows to view the email complete with merged data for an individual before sending.
Here are the steps:
https://api.expresspigeon.com/dictionaries
You can create multiple dictionaries in a single API call (do not forget to set Content-type header to application/json
).
Request Parameters
Parameter | Required | Description |
---|---|---|
name | Yes | Name of a new or existing dictionary |
values | Yes | Collection of name/value pairs |
Example Request
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
|
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
Example Response
1 2 3 4 5 6 |
|
Where 123 and 456 are IDs of created or updated dictionaries.
You can see and edit dictionaries using a browser. First, login into your account, and navigate to https://expresspigeon.com/dictionaries.
Enter * or a dictionary name into the search field and press Enter.
https://api.expresspigeon.com/dictionaries
Allows to list multiple dictionaries.
Example Request
1 2 |
|
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 8 9 |
|
1 |
|
1 2 3 4 |
|
Example Response
1 2 3 4 5 6 7 8 9 10 11 12 |
|
https://api.expresspigeon.com/dictionaries
Lookup a single dictionary
Example Request
1 2 |
|
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 8 9 |
|
1 |
|
1 2 3 4 |
|
Where "dict_id" is a dictionary ID.
Example Response
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
curl -X DELETE -H "X-auth-key: XXXX" https://api.expresspigeon.com/dictionaries/dict_id
This is simply a text file that has the following format:
john@doe.com {"productx":"dict1.product1","producty":"dict1.product4","salex":"dict1.sale1","saley":"dict1.sale2"}
jane@doe.com {"productx":"dict2.product1","producty":"dict2.product4","salex":"dict2.sale1","saley":"dict2.sale2"}
Each line is expected to have an email address that corresponds to a contact followed by space, followed by a JSON document that contains mappings for this contact.
The mappings file needs to be zipped. File name can be anything, and zipped file name can be anything as well. Only one file inside a zip is expected.
Example:
mappings.txt
mappings.txt.zip
curl -H "X-auth-key: XXXX" -H "Content-Type: octet/stream" \
--data-binary @mappings.txt.zip https://api.expresspigeon.com/dictionaries/mapping/dictionary_mapping_X
Where the X
can span the values from 1 to 20, depending what recommendation set you need to update.
Sending a campaign with dictionaries is similar to sending a regular campaign. You just need to include a dictionary_mapping
argument:
curl -X POST -H "X-auth-key: XXXX" -H "Content-type: application/json" -d \'
{
"list_id":"293",
"template_id" : "20047", "name": "Merge campaign test",
"from_name" : "Igor", \
"reply_to" : "igor@expresspigeon.com", "subject" : "${producty} ${salex}",
"google_analytics" : "false",\
"dictionary_mapping": "dictionary_mapping_1"
}'
https://api.expresspigeon.com/campaigns
For more information, see campaign creation.
You can browse to any conmtact details screen and click on the "Recommendation mappings" tab for that contact:
that will allow you to see recommendation mappings for that contact in the same JSON format: