HTML Templates

Easily create, view, edit, and manage your postcard, letter, and check HTML templates by saving them within Lob's system.

NOTE: In Live mode, you can only have as many non-deleted templates as allotted in your current Print & Mail Edition. There is no limit in Test mode.

Creating a Template

Templates can be created from your Dashboard. Any parameter that accepts HTML in postcard, letter, or check creation can also accept a template. When creating a template, you need to pass two pieces of information:

  • An optional description
  • The HTML for your template

While it is optional, we highly recommend adding a description so you can easily identify your template within Lob. As for the HTML design, you can start off with a pre-designed template from our gallery or follow these basic guidelines to get started. Templates are compatible with merge variables, which we encourage using for creating dynamic, custom content. For more detailed guidelines and best practices around creating HTML designs, please see our documentation.

Both the description and your HTML can be edited easily afterwards, so don't worry about getting things perfect.

Like all Lob resources, you can create templates in both your Test and your Live Environment. Templates created in the Test Environment will only be usable by postcards, letters, and checks created in the Test Environment, while templates created in the Live Environment will only be usable by postcards, letters, and checks created in the Live Environment. Be sure to work closely with your developer to make sure you are working in the correct environment.

Viewing a Template

Once you've created a template, you'll be able to view it on your Dashboard. You can do a couple things on this page:

Finding a Template's ID

At the top right-hand corner the page is the template ID, which is completely unique to this particular template. The template ID is how you will refer to this template when ultimately creating a postcard, letter, or check.

Previewing a Template

On this page, you can view the raw HTML for your template, as well as preview the design by clicking the "Preview" button.

When you preview a template, you'll first need to choose a product to preview it as. We will also auto-populate any merge variables we find in your template, which are dictated by {{double_curly_braces}}. After you've filled out these fields, 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).

On the 2020-02-11 and later API versions, the JSON editor is required if you need to use loops, conditionals, or objects. We will not auto-populate any merge variables we find in your template when using the JSON editor.

Keep in mind that you won't be able to see any specific proofing elements such as address information, barcodes, or cropping that happen when actually creating a mailing. Ultimately, the best way to test your template will be to send it as a test postcard, letter, or check.

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 postcard, letter, or check integrations referencing that template ID will reflect the updated changes as soon as they are submitted.

Deleting a Template

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 in any postcard, letter, or check requests, so make sure that the template is not being actively used in any integrations!

Template Versions

At the top of the page will always be the published version, which is the version that will be used when that template is referenced in a postcard, letter, or check request. Historical versions of the template can be viewed for your reference, along with a unique ID and browser preview for each. This can be helpful for reconciling edits made in the past.

Using a Template in a Postcard, Letter, or Check Request

To test out and use your HTML template, you'll need to create a postcard, letter, or check. For parameter details, please see the respective documentation for each endpoint: Postcards, Letters, Checks).

For this example, we'll create a postcard. Don't forget to add in any merge variables you'd like to interpolate in. Remember that the published version of the template is the version which will be used for the request.

curl \
  -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, you'll be able to see your final postcard design:

For any postcards, letters, or checks that use templates, the template IDs and version IDs used will be retrievable from the API (see the respective documentation for each endpoint: Postcards, Letters, Checks), as well as viewable on the Dashboard: