Using HTML and Merge Variables

Merge variables make it easy to personalize your postcards, letters, and checks with whatever custom information you'd like. Common use cases for merge variables are:

  • Customer information (name, phone number, etc)
  • Date
  • Invoice line items
  • Custom images

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 you pass. You can define whatever variables make sense for the design you are creating.

<html style="padding: 1in; font-size: {{fontsize}}; color: {{color}}">
  <p>Hi {{name}}, how are you?</p>
  <img src="{{img}}" style="width: 1in">
</html>

If the HTML above were used with the information below:

name fontsize color img
Harry 20px red https://s3-us-west-2.amazonaws.com/public.lob.com/assets/beach.jpg
Ami 30px green https://s3-us-west-2.amazonaws.com/public.lob.com/assets/jungle.jpg

Then the final two postcards would be rendered like so:

Use this feature to your advantage to create completely custom postcards, letters, and checks for your recipients, without having to generate PDFs on your side.

Objects

NOTE: This is only available on the 2020-02-11 and later API versions.

You have the ability to access merge variables at any depth within your JSON. For instance you can have an object created with a bunch of user information:

{
  "user": {
    "name": "Ami",
    "location": "San Francisco"
  }
}

To access these within your template you can do the following:

Name is: {{user.name}}
Location is: {{user.location}}

This renders the following template:

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:

{{#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.

Conditionals

NOTE: This is only available on the 2020-02-11 and later API versions.

Conditionals allow you to conditionally render any sort of content to the user. A simple use case could be you want to send an extra message to any user who has bought over 1,000 products. To do that would require the following:

Merge variables:

{
  "bought_a_lot": true
}

Template:

<html>
{{#bought_a_lot}}
Thank you for being a loyal customer!
{{/bought_a_lot}}
</html>

This renders:

Thank you for being a loyal customer!

If you want to render some content if a condition does not pass, simply do {{^condition}}{{/condition}}. For example:

Merge variables:

{
  "bought_a_lot": false
}

Template:

<html>
{{^bought_a_lot}}
Buy more products!
{{/bought_a_lot}}
</html>

This renders:

Buy more products!

Loops

NOTE: This is only available on the 2020-02-11 and later API versions.

Loops allow you to display content multiple times for multiple objects. The following is how you would use it:

Merge variables:

{
  "users": [{"name": "Nathan"}, {"name": "Ami"}]
}

Template:

<html>
  List of top users:
  <ul>
  {{#users}}
    <li>{{name}}</li>
  {{/users}}
  </ul>
</html>

This renders:

<html>
  List of top users:
  <ul>
    <li>Nathan</li>
    <li>Ami</li>
  </ul>
</html>

Merge Variable Strictness Setting

Depending on how much control you'd like over your HTML integration, we offer 2 different account settings that affect how we treat merge variables. This account setting affects the POST /v1/postcards, POST /v1/letters, and POST /v1/checks endpoints in both test and live mode:

  • Strict: Lob will send a 422 error if you define a merge variable in your HTML that is not passed in the merge_variables field of that request. Pass '' or null to have a particular defined variable not render.
  • Relaxed: Lob will not send an error if you define a merge variable in your HTML that is not included in the merge_variables field of that request. Instead, we will simply render nothing in the HTML in place of that merge variable.

Regardless of your strictness setting, if you pass merge variables keys that are not defined in your HTML, no error will be thrown. Your HTML will simply be rendered as normal without substituting the extra variable(s).

NOTE: On the 2020-02-11 and later API versions which support JSON in merge variables, merge variable strictness will still apply to the nested object keys, i.e. if a nested merge variable is undefined on the strict setting, then Lob will send an error.

Using HTML and Fonts

With Lob's HTML feature, you can easily make use of any font to make your postcards, letters, and checks as on brand as possible. By default, we only support 1 font family, Deja Vu, within our renderer. To access any other fonts, you must follow one of the steps below.

Using Google Web Fonts

Using Google Web Fonts 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.

After you've gone to their platform and found a font you'd like to use, all you have to do is include a link to the font in the <head> tag of your HTML:

<head>
  <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
</head>

Then, you simply reference the font like so in your <style> tag (or inline if you prefer):

body {
  font-family: 'Roboto';
}

Using Custom Fonts

Outside of Google Fonts, you are free to use any custom font you desire. Simply upload your font files to a performant file hosting platform (such as Amazon S3) and use CSS's @font-face declaration to load them into your design.

For example, in the <style> tag of your HTML, add the rule like so:

@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 <style> tag (or inline if you prefer):

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's page-break-after property.

For example, create a page class in your HTML and apply these styles:

.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:

<div class="page">
  Page 1
</div>
<div class="page">
  Page 2
</div>