Source Link: https://help.lob.com/print-and-mail/designing-mail-creatives/maximizing-engagement/dynamic-personalization # Dynamic personalization
## Personalize your creatives with HTML
Personalized messaging is a core component of all modern marketing channels and a key driver of user engagement. Lob brings the power of personalization at scale to direct mail, enabling you to improve the performance of this key channel and improve your return on investment.
Lob makes this possible by supporting HTML creatives with merge variables. This empowers you to leverage your customer data to individually cater your messaging to each recipient in a way that will maximize the impact of a mail piece. You can now design your direct mail similar to how you would an email or other digital channels, leveraging dynamic personalization to drive conversions.
Some best practices that leverage dynamic personalization include:
* **Capture 1-to-1 attribution**: Use dynamic landing pages, QR codes, and unique URLs/promo codes to understand audience response at the individual level
* **Repurpose digital campaign assets**: Orchestrate an omnichannel campaign with cohesive messaging and branding through online and offline channels
* **Experimentation**: Easily execute A/B and multivariate tests by combining audience targeting with dynamic creation of multiple creative permutations. Test the efficacy of different images, layouts, CTA copy, promotions, and more.
* **Integrate into the customer journey**: Automatically send mail at any point in the customer journey by creating automated direct mail triggers at key actions and milestones
Below is an overview of how to leverage personalization within Lob.
## HTML templates
Lob's HTML Templates support the inclusion of dynamic fields, called **merge variables**, which can be populated individually for each mail piece. These merge variables can be mapped to attribute values in your customer records or audience segments. For example, the value for your customer attribute "First Name" can be passed into a merge variable field in your creative called \{{Name\}} to dynamically include each recipient's own name in the content of the mail piece they receive. You can create and name your own merge variables within your template, giving you the flexibility to personalize nearly any aspect of your creative.
{% hint style="success" %}
To utilize an HTML within the [Campaigns](https://dashboard.lob.com/campaigns/live) builder in the dashboard, you must first create a Live template in Lob.
{% endhint %}
### Creating a template
You can create, view, edit, and manage your HTML templates for any mail format by saving them within Lob's system. You can create a template by sending HTML directly to Lob's [Templates API endpoint](https://docs.lob.com/#tag/Templates) or HTML templates can be created within your Lob dashboard under[HTML Templates](https://dashboard.lob.com/templates).
* While it is optional, we highly recommend adding a description so you can easily identify your template within Lob.
* In the dashboard, you must indicate the Mail Format and Size order to save a template.
* Both the description and your HTML can be edited after saving.
#### Test vs Live
* Like all Lob mail pieces, you can create HTML templates in both your [Test and Live Environments](../../../../account-management/api-keys#test-vs-live-environment-keys-2).
* Templates created in the Test Environment will only be available for mail pieces created in the Test Environment, while templates created in the Live Environment will only be available for mail pieces created in the Live Environment.
* While you can move templates from one environment to the other, make sure you are working in the correct environment (don't move a Live template!).
* In Live mode, you can only have as many templates as allotted in your current [Print & Mail edition](https://dashboard.lob.com/#/settings/editions). There is no limit in Test mode.
{% hint style="success" %}
To utilize an HTML template within the [Campaigns](https://dashboard.lob.com/campaigns/live) builder in the dashboard, **you must first create a Live template in Lob.**
{% endhint %}
### Template design
As for the HTML design, you can start off with a [pre-designed template from our gallery](https://www.lob.com/template-gallery) (or see [these examples in GitHub](https://github.com/lob/examples)). Our templates are compatible with [merge variables](#using-html-and-merge-variables-10), which enable dynamic content.
* If you have limited access to designers and developers, consider using our [Figma-to-Lob plugin](../../integrations/creative-conversion-tools/figma-plugin). This plugin will take any creative designed in Figma and convert it into a HTML template with merge variables.
* When designing content with HTML, use inline styles or an internal stylesheet. Do not use an external stylesheet.
* If you are linking to images, please ensure that they are at least 300 dpi (but there is no need to go higher than 300 dpi). Because the content is only being designed for a single size, we recommend using absolute positioning (code snippet shown below).
{% hint style="success" %}
All URLs must be accessible. For example, broken links, missing files, and incorrect permissions will all cause mail pieces to fail before they are sent to print. See here if you are experiencing [rendering errors.](../creative-formatting/rendering-errors)
{% endhint %}
```html
body {
width: 6.25in;
height: 4.25in;
margin: 0;
padding: 0;
background-image: url(https://s3-us-west-2.amazonaws.com/public.lob.com/assets/beach.jpg);
background-size: 6.25in 4.25in;
background-repeat: no-repeat;
}
#safe-area {
position: absolute;
width: 5.875in;
height: 3.875in;
left: 0.1875in;
top: 0.1875in;
background-color: rgba(255,255,255,0.5);
}
```
### Viewing a template
Once you've created an HTML template, you'll be able to view it on your dashboard under [HTML Templates](https://dashboard.lob.com/templates). Clicking any template will bring you to the Template Details page.
From the menu, you can [edit the template](#editing-a-template), view a large [print preview](#print-preview) of the template, or delete the template (from the meatball menu).
Also the this page you can:
* See a small preview of the template
* View the Template ID (completely unique to this particular template)
* View the [Version ID](#template-versions)
* View the template's metadata
* View the HTML for the template
* See previous versions of the template
#### **Print Preview**
When you select View Print Preview, a pop-up will display and auto-populate any merge variables we find in your template, which are dictated by `{{double_curly_braces}}`. After you've filled out these fields (sample data is fine), you'll be able to preview your template as a PDF, which will open in a new tab. You may need to unblock pop-ups in the browser of your choice.
A JSON editor will be required if you need to use [loops, conditionals, or objects](#objects-conditionals-loops). We will not auto-populate any merge variables we find in your template when using the JSON editor.
{% hint style="warning" %}
You won't be able to see any specific proofing elements such as address information, barcodes, or cropping which occur when actually creating a mail piece. The best way to test these elements of your template will be to send it to yourself as a live mail piece.
{% endhint %}
### **Editing a template**
You can edit a template's description as well as its HTML from the Dashboard as well. When you edit a template's HTML, a new published version of that template will be created. Those changes will go into effect immediately. Any subsequent mail piece integration referencing that template ID will reflect the updated changes as soon as they are submitted.
If a template is no longer of use to you, you can delete it from Lob. Once you delete a template, it will no longer be usable for any postcard, self-mailer, letter, or check requests. Before deleting, ensure that the template is not being actively used in any integrations.
#### **Template versions**
The published version of a template will be the first version featured on the page. This is the version that will be used when that template is referenced in a mail piece request. Prior versions of the template can be viewed within the page, along with a unique ID and browser preview for each. This can be helpful for reconciling edits made in the past, or copying a prior template and saving it again in order to revert to it.
## Using HTML and merge variables
Merge variables make it easy to personalize your mail pieces with whatever custom information you'd like to include. Common use cases for merge variables include:
* Personalized customer information (name, city, etc)
* Date
* Invoice line items
* Custom copy or images
* CTAs (URLs, coupon code, phone numbers)
### Usage
Merge variables only work if you use HTML to generate your mail piece. To make use of a merge variable, insert `{{tag_name}}` (with double curly braces) into the HTML template. You can define the merge variable name, and you can enter it into any section of your HTML.
```html
Hi {{name}}, how are you?
```
If the HTML above were used with the information below:
Then the final two postcards would be rendered like so:
Use this feature to your advantage to create dynamic creatives for your recipients, without having to generate PDFs on your side.
{% hint style="success" %}
All URLs must be accessible. For example, broken links, missing files, and incorrect permissions will all cause mail pieces to fail before they are sent to print. See here if you are experiencing [rendering errors.](../creative-formatting/rendering-errors)
{% endhint %}
### Advanced functions
#### Objects, conditionals, loops
{% tabs %}
{% tab title="Objects" %}
You have the ability to access merge variables at any depth within your JSON. For instance, you can have an object created with multiple attributes:
```json
{
"user": {
"name": "Ami",
"location": "San Francisco"
}
}
```
To access these within your template you can do the following:
```html
Name is: {{user.name}}
Location is: {{user.location}}
```
This renders the following template:
```html
Name is: Ami
Location is: San Francisco
```
You can also create a "section" which will change the context of the variables you are accessing. For instance:
```html
{{#user}}
Name is: {{name}}
Location is: {{location}}
{{/user}}
```
This renders the same HTML as above, since you changed the context to the "user" temporarily. This is done by the `{{#user}}` and `{{/user}}` syntax. Everything inside that "section" tries to access a property on the "user" object.
{% endtab %}
{% tab title="Conditionals" %}
Conditionals allow you to conditionally render content in a mail piece. An example use case could be including additional text for any user who has purchased over 1,000 products. To do that would require the following:
Merge variables:
```html
{
"bought_a_lot": true
}
```
Template:
```html
{{#bought_a_lot}}
Thank you for being a loyal customer!
{{/bought_a_lot}}
```
This renders:
```
Thank you for being a loyal customer!
```
\
If you want to render content if a condition does not pass, simply use `^: {{^condition}}{{/condition}}`.
For example:
Merge variables:
```html
{
"bought_a_lot": false
}
```
Template:
```html
{{^bought_a_lot}}
Buy more products!
{{/bought_a_lot}}
```
```
Buy more products!
```
{% endtab %}
{% tab title="Loops" %}
Loops allow you to display content multiple times for multiple objects. The following is an example of how to use loops:
Merge variables:
```html
{
"users": [{"name": "Nathan"}, {"name": "Ami"}]
}
```
Template:
```html
List of top users:
{{#users}}
{{name}}
{{/users}}
```
\
This renders:
```html
List of top users:
Nathan
Ami
```
{% endtab %}
{% endtabs %}
#### **Javascript usage**
While JavaScript can unlock all kinds of new functionality in your Lob templates, it comes with the important caveat that not all client-side JavaScript can be rendered by Lob. Additionally, it is possible that any included JavaScript will not fully execute prior to PDF generation. You are thus strongly encouraged to test all JavaScript prior to utilizing in live mail templates. Test your entire HTML template containing the JavaScript (rather than just the JavaScript snippet itself) using your Test API key before using the template in any live mail API requests.
{% hint style="info" %}
For even more flexibility we recommend using the [Handlebars templating engine](dynamic-personalization/advanced-templating-handlebars).
{% endhint %}
### Merge variable strictness
Lob offers a merge variable strictness setting that dictates how we treat merge variables in your HTML templates, and whether to send out any mail pieces that are missing their merge variable input values. This is a setting that can be set at the account or campaign-level, and is critical to use when handling dynamic creatives. See [Merge variable strictness settings](../../../building-a-mail-strategy/managing-mail-settings#merge-variable-strictness-setting-3) for more information.
### Using HTML and fonts
You can incorporate any font into your Lob HTML Templates by using one of the options below. Links to fonts must be accessible by Lob or they will not render successfully.
#### **Using Google web fonts**
Using [Google Web Fonts](https://fonts.google.com/) is a simple way to import and use a wide variety of fonts within your Lob HTML without having to download or upload any assets.
Once you've identified your font within Google, just include a link to the font in the `` tag of your HTML:
```html
```
Then reference the font in your `` tag or inline:
```html
body {
font-family: 'Roboto';
}
```
#### **Using custom fonts**
You are also free to use any custom font that is accessibly hosted. Upload your font files to a performant file hosting platform (such as Amazon S3) and use [CSS](https://www.w3schools.com/cssref/css3_pr_font-face_rule.asp) @font-face [declaration](https://www.w3schools.com/cssref/css3_pr_font-face_rule.asp) to load them into your design.
For example, in the `` tag of your HTML, add the rule like so:
```html
@font-face {
font-family: 'My Font Name';
font-style: normal;
src: url('https://link-to-your-font/my_font_name.ttf') format('truetype');
}
```
And then reference the font in your `` tag or inline:
```html
body {
font-family: 'My Font Name';
}
```
### Page breaks in HTML
When creating HTML letters within Lob, you may find it necessary to create page breaks in order to split up your content by page. This is easy to do using [CSS](https://www.w3schools.com/cssref/pr_print_pageba.asp)'s `page-break-after` [property](https://www.w3schools.com/cssref/pr_print_pageba.asp).
For example, create a `page` class in your HTML and apply these styles:
```html
.page {
page-break-after: always;
position: relative;
width: 8.5in;
height: 11in;
}
```
And then, divide the pages of content in your HTML by this `page` class:
```html
Page 1
Page 2
```
## Template storage
Templates can be viewed in the [Lob dashboard](https://dashboard.lob.com/templates), where they can be created, managed, and stored.
The total number of templates available is dependent on the Platform Edition; if you need more HTML templates than what is available in your current edition of Lob, we encourage you to upgrade to a higher tier [edition](https://www.lob.com/pricing/print-mail). You may also delete any HTML templates you no longer need to make room for new ones.
## General template best practices
Although anyone versed in HTML/CSS will find the process of creating templates familiar, we recommend these practices.
If you need a place to start, we highly recommend working off an example from our [Template Gallery](https://www.lob.com/template-gallery).
#### **See it before you ink it!**
For the closest visual analog to our own rendering technology, we suggest viewing your template in the Safari browser. This also means that usage of CSS stylings unsupported by the Webkit (Safari) engine may not render correctly. We recommend working at a 300dpi resolution, any higher resolution would be lost once the mail piece is printed.
Be sure to make use of the "Print Preview" option with your HTML templates, whether in Live or in Test mode, to get a basic digital proof of your mail piece. (Keep in mind that templates created in the Test Environment will need to be recreated in the Live Environment before they can be used with Live mail pieces.)
In the Campaigns builder, most mail formats will also display a Creative Proof; this will display merge variables, address block, Lob carbon-neutral logo, and indicia, plus return address and QR codes if included.
{% hint style="success" %}
Where possible, we always recommend sending yourself a printed mailpiece.
{% endhint %}
**RGB vs CMYK**
As it stands today, our rendering engine does not support the CMYK color profile in HTML templates, though we are slated to resolve this in the near future. As such, colors provided in HTML templates will need to undergo a transition from RGB to CMYK which may affect the hue and saturation. This is true even when assets are provided in CMYK. We advise our customers keep this in mind when requesting to print brand logos or skin tones. If preferred, we support [CMYK for static (PDF) formats](../../creative-formatting#pdf-guidelines-14).
#### **Please avoid the following:**
For a successful template creation experience, abstain from the following:
* using the `object-set` property
* images `img` with `opacity` properties
* images using `background-image`, `border-radius`, and `border` properties in unison
* gradients using transparency
* `background-size: contain`
* in these cases, also include `background-repeat: no-repeat;`
* JPEG images with EXIF orientations set to non-zero values; workarounds include:
* using a JPEG header manipulation utility such as [jhead](https://www.sentex.ca/~mwandel/jhead/usage.html) to correct the rotation value
* Example: `jhead -autorot myfile.jpg`
* using a PNG instead
* CSS references that are not utilized in the final HTML template
## Using a template in Campaigns
In the Campaigns tool, Step 3: Choose creative, you will select an HTML template, and then choose from the drop down options. An HTML template must exist in the Live environment for the Campaigns tool to reference.
## Using a template in a mail creation API request
To test and use your HTML template, you'll need to create a mail piece. For parameter details, see the respective documentation for each single endpoint in our [API documentation](https://docs.lob.com/).
For this example, we'll create a postcard. Don't forget to add merge variables to your HTML template for any dynamic fields. Also, remember that the published version of the template is the version that will be used for the request.
```html
curl https://api.lob.com/v1/postcards \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-d "description=Demo Postcard job" \
-d "to=adr_78c304d54912c502" \
-d "from=adr_61a0865c8c573139" \
--data-urlencode "front=tmpl_d2ef51761865901" \
--data-urlencode "back=tmpl_7c9c41753dfea20" \
-d "merge_variables[name]=Harry" \
-d "merge_variables[code]=5dks92"
```
After sending this request, a successful response will include a signed URL to a digital copy of the created postcard. You will also be able to view this in the Lob dashboard, under Print & Mail then the corresponding mail format (in this case, Postcards).
\
For any mail piece that use templates, the Template IDs and Version IDs used will be retrievable from the API (see the respective [documentation](http://docs.lob.com) for each endpoint), as well as viewable on the dashboard under HTML Templates listing and each Template Details page. \
```
If the HTML above were used with the information below:
