Sending Custom Postcards with Driving Directions in Node.js Using Lob’s API

Personalization has a well-known positive effect on the conversion of email campaigns. With today’s wide variety of API services and marketing tools, it’s easy to implement. Past the marketing benefits, if you’re fulfilling an operational need with your messages (invoices, balance statements, privacy statements), personalizing the content of a message is often a requirement. In this tutorial we’ll be building a simple Node.js program capable of sending a postcard with a coupon code, and a map of driving directions to the nearest store located relative to the recipient’s home address.

Historically, sending mail in bulk has required generating a specifically formatted PDF for each and every letter that needs to be sent. Other key steps include contracting with an industrial print shop and arranging a strategy of transferring the files (usually FTP), running address verification, and organizing the PDFs for USPS presort postage rates. This is historically not a process in which it has been feasible to implement personalization. That’s why most physical mail campaigns are batched in bulk with the same content mailed to every recipient.

By implementing Lob’s print and mail API along with our HTML template service, sending letters and postcards with personalized content can be just as simple as sending an automated personalized email.

We’ll skip building a front end interface for this program and build a simple Command Line Interface (CLI). At a high level, this demo program demonstrates the feasibility of implementing such a customized mail-piece in the back end of your own Node.js application.

What We’re Building

Friend of Lob Bob runs a sandwich shop on Haight Street in San Francisco. Bob is a smart business owner who understands the importance of customer loyalty, so he’s built a customer rewards program with a database of his repeat customers’ names and addresses so he can mail them coupons. He’s been mailing his customers manually – which requires all three of his kids to help to sort postcards from the printer, apply postage stamps, and put the customer specific coupon sticker on each postcard.

Bob’s just launched a new sandwich that he wants to promote to his loyal customers with a personalized coupon code. His database has now grown to over 1,000 repeat customers, so manual mailing has become too time-consuming. Instead, he plans to integrate the Lob API with his customer loyalty platform so that any new customer added to the database will be automatically mailed a postcard with a coupon! Additionally, he wants to remind his customers how close they live to Bob’s Sandwiches by including a map with street directions from each customer’s address to his sandwich shop.

Setting Up Our Node Project

If you’ve already got a Node.js app that you are integrating with Lob, you can likely skip this section. The entire working code base with in-depth comments is hosted on Github: https://github.com/lob/postcard-template-example

To begin, create a new directory and initialize it with npm:

Name the project anything you like as part of the npm initialization wizard. Once the project is initialized, we need to install the Lob Node Library, urlencode – for encoding URL parameters for the Google Maps API, and Axios – a fantastic HTTP request library with promise support as a dependencies:

  • lob – The Lob API Node Library
  • axios – HTTP library with A+ promise support for making requests to the Google Map API
  • urlencode – Library for URL encoding strings
  • prompt – Command Line Interface Library

Install all of the dependencies and save them to package.json:

In order to generate a Google Map of driving directions, you’ll need to register for a Google Maps API key, and enable both the Google Maps Static Map API, and the Google Maps Directions API. Additionally, to generate a Short URL that can be used for the generated map in our postcard template, you’ll need to register for a Google Short URL API Key.

We’re now ready to write a simple Node program that will accept a customer name and address as input, generate a coupon code, a map with walking directions to Bob’s Sandwiches, and mail them a postcard using the Lob API!

Overview of Files

This sample Node program is broken up into 3 files. One configuration file and two Javascript files as follows:

  • config.json – Configuration file which specifies API keys for Lob and Google, template id’s for front and back of postcard, postcard size, from address, and the dimensions of the Google map to generate
  • index.js – Entry file for our node program, initiates a command line prompt, and HTTP requests to the Google and Lob APIs
  • utils.js – A module with utility functions for making HTTP requests to Google

Creating the Postcard Templates

Templates for Lob mail-pieces are created in HTML and implement a very simple syntax for merging in variable data such as a customer’s name, a coupon code, or even the URL of an image. We’ve built a Github repository with a number of example HTML templates that can be edited or followed as a guideline for creating your own templates: https://github.com/lob/lob-templates.

For the purposes of this demo application, there are already two HTML templates in this repo – one for the front and another for the back of the postcard: https://github.com/lob/postcard-template-example/tree/master/templates. Notice the placeholders for name, coupon_code, and map_url in the back.html template. To use these templates, we recommend making using of the Lob dashboard, which has a centralized place for any of your team members to view and edit any HTML templates.

The two postcard templates can be added to your Lob dashboard by selecting “HTML Templates” from the left menu, then clicking the “Create” button in the top right. From here, simply specify a name for the templates, and paste in the HTML. Once the templates are saved in the Lob dashboard, a unique id string will be assigned to them which is visible in the top right corner when viewing the template. Save this value in config.json as template_front and template_back.

Once the Lob and Google API keys are also specified in the config.json file, then this program is ready to run and send postcards in live or test mode.

Walking through index.js

The implementation of Lob’s postcard API in this file is relatively simple, relying on just one method of Lob’s Node module, and two HTTP requests to Google’s APIs to generate the map and shorten the map URL.

First, we need to import all of the dependencies required:

Next, we make use of the Node module prompt to collect all of the required values in the array on line 54 of who to send the postcard to on line 65.

Once all of the values are collected, the callback is invoked with an object of the values. We’ve named the values with the same key names as the address object specified in the Lob API Docs, therefore the object passed to the callback will be in the proper format. Let’s implement the callback function:

We are making use of the two Google Maps API methods that we’ve implemented in the utility module. The first method, utils.getDirectionsPath makes an HTTP request to the Google Map API with Axios, and resolves a promise with a URL encoded string of the driving directions polyline path. (include links to google maps api). The second method, utils.getMap returns a promise that constructs a URL for a static Google Map image URL, then uses the Google Short URL API service to generate a Short URL.

Finally, we’ll implement the Lob Node Module to send our postcard:

Walking Through utils.js

We also need a few dependencies for utils.js:

When writing Javascript modules, there is of course the newer ES6 syntax. However, for simplicity of not requiring babel for this example, we’ll be using ES5 to write our utils module. So let’s write an object with three methods, and export it.

Putting It All Together

Lastly, prior to running the program, open config.json and specify all of the relevant values:

Once you’ve finished this, run the program and enter a recipient name and address!

The prompt module will, well… prompt you, for all of the values we specified in the array of inputs we’d like to collect. Lob offers a Test and a Live environment which both have unique API keys. It is always best to first use the Test API key to test how a postcard looks prior to spending real money on sending real postcards. The resulting generated PDF can be viewed in the Lob dashboard, and should look something like below!

Implementing Customized Postcard Templates in Your Own Project

This project was designed to be a stand-alone CLI program to get you up and running with this example quickly. In the real world, you’ll likely use your own application’s database or perhaps a customer-triggered event (such as a purchase or signup) to invoke the Lob.postcards.create method. The possibilities of the types of events that can be used to trigger sending a postcard are endless and specific to your own business.

Regardless of how the postcard send is triggered, we’ve demonstrated here how easy it is to send highly customized postcards. We even included robust graphic content: a map with driving directions printed right on the card! Our customers have implemented a wide variety of customized content such as images of past product purchases and Google street view images. We’re excited to see what you come up with!

Getting started with a Test API key is free and as simple as signing up!