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


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">

If the HTML above were used with the information below:

name fontsize color img
Harry 20px red
Ami 30px green

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.

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

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:

  <link href="" rel="stylesheet">

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 class="page">
  Page 2