h(API) holidays! Mail your holiday cards programmatically

It’s Holiday Card season! But my hand hurts just thinking about addressing all those envelopes, and I can’t remember the last time I bought stamps…let’s be real, ain’t nobody got time for that.

Fortunately, I happen to work for a company that sends direct mail programmatically. Many developers integrate with Lob using one of our SDKs in their preferred programming language, but we recently launched our low-code Campaigns and I thought I’d give it a whirl.

The following is a step-by-step tutorial so you too can create personalized full-color 6”x9” postcards (automatically printed and mailed) for under a dollar each.

Here is a sample of the postcard we will create.

Select and prep your photos

Choose two of your favorite photos: one landscape (for the front), one portrait (for the back). Use your photo editing tool of choice to format each correctly; I used Preview on my Mac. To ensure that they scale proportionally and print at the highest quality they should be 5x7 inches (2100 pixels x 1500 pixels in landscape or 1500 pixels x 2100 pixels in portrait) and at a resolution of 300 pixels per inch. (If you need more support on this part, and/or are snagging photos from your iPhone, see the Appendix.)

You will then need to host your images somewhere; I used a free account at imgbb.com.

Prep your data

1. You will then need to bring up the HTML for the front and back of the postcard. Click each link and view the HTML; we’ll use it in a later step).

2. Next, you will prep your address data. Make a copy of this spreadsheet and input your data:

3. Do not modify or add any column headers!

4. Add the full name in the name column

5. Add the address data (make sure that leading zeroes aren’t being dropped and that the state code is used)

6. Replace the “Lorem ipsum” in the message column with your own personalized message. Make sure that the message fits within the space by being shorter than the placeholder examples (about 65 characters) You can test your holiday card messaging HERE

7. Add the links to your front and back images to every row in the image_front and image_back columns (should look something like this: https://i.ibb.co/fpJ84Js/front.png)

8. Download and save your address file as a .csv.

Create your HTML templates

Now you are ready to create your postcard templates in the Lob dashboard.

1. First you will need to sign up for a free Lob account.

2. Once you have registered you will be taken to the dashboard. In the Developer tier there is no cost to test out the Print & Mail APIs, but if you want to send live requests—and have a postcard printed and mailed—it will run you $0.896 a pop.

3. Payment information can be entered here: Your name (top right) -> Settings -> Payment

4. Create & save HTML templates for the Front and Back of your postcard

5. On the left menu bar, Navigate to HTML Templates.

6. Make sure Live is highlighted!

7. Click on ‘Create’

8. Name this ‘Front Template’ and paste in the HTML code for the front. Click ‘Create’ to save.

9. On left menu, click HTML Templates to go back to main template screen. (You should see your new Front template there under Live templates.)

10. Once again, ensuring Live is highlighted, click ‘Create’ again. Name this ‘Back Template’ and paste in the HTML code for the back. Click 'Create' to save.

11. Click HTML templates to go back to main template screen; you should see your new Back template there under Live templates.

** Make sure you see both templates are listed when Live is highlighted before proceeding.

Create and send your postcards

On the left menu bar, navigate to Campaigns; click on “Create Campaign”

Step 1: Configure Campaign

1. Enter a Name and Description
2. Campaign Type: Marketing
3. Mail Type: Postcard; Size: 6x9
4. Postage references: Return address is not required; Select postage: Up to you, note the listed expected delivery times
5. Cancellation Window: This is set at 5 minutes; you will not have the option to edit on a Developer plan
6. Campaign-Level Metadata: Optional

Step 2: Add Audience

1. Upload your CSV file (created during prep stages), or drag and drop it into the dashboard

2. Map required address variable: These are mapped automatically.

Step 3: Choose Creative

1. Under ‘Postcard Front’, select the HTML Template you created from the dropdown menu. (Note a preview will not show your images or messages as they are not mapped yet)

2. Under ‘Postcard Back’, select the HTML Template you created from the dropdown menu. (Note a preview will not show your images or messages as they are not mapped yet)

3. Connect your creative to your audience:

4. Merge variable strictness: Ignore;

5. Connect/map your merge Variables from HTML to the appropriate column in the CSV: {img_front} to img_front, { img_back} to img_back, {message} to message

Step 4: Review Campaign

If something is not correct, click ‘Previous Step’ to edit. The free Developer tier does not allow you to edit cancellation windows. That said, once you place your order, after 5 minutes, the live request will be sent to Lob. Your postcards will be created and mailed, and you will be charged.

If all looks correct, click ‘Place Order’ and your holiday cards will be on their way! You can view your cards under Campaigns in the Lob dashboard.

Wrap up

Lob was started by two developers who needed to solve a problem, and direct mail APIs were the answer; the goal was to make sending mail just as easy as sending an email. This is a fun personal use case, but Lob is meant to automate direct mail—postcards, letters, checks, self-mailers, and more—at scale. Just like email, each mailpiece can be highly personalized, and for advanced tiers, Mail Analytics is available for each mailpiece to track each postcard along its journey to delivery (and if you included a QR code, you could even track open rate). Check out Lob.com if you want to learn more.

Appendix: How to prep a photo

1. Email/Download a photo from your iPhone onto your computer. The following steps are shown in the Preview app (Mac) but are a good guideline for any editing program.

2. Select your back photo (portrait orientation). Under Tools, select Adjust Size.

1. Change Resolution to 300 pixels/inch.

2. For this photo (portrait orientation): Change Width to 5 inches; and Height will automatically change. Alternatively, update the Height to 7 inches, and the Width will change. It’s highly likely you won’t end up with a perfect 5x7; that’s ok: Change the field that results in one of the measurements being slightly too big; you will crop in the next step).

1. Under Edit, Select All. Drag the dotted line to crop the image to the necessary 1500x2100 (as you move the line, the measurements will display; exaggerated below).

1. Under Tools, Assign Profile select Generic RGB. (Photos must be saved as RGB.)

2. Make sure your photo is named clearly as the BACK. Save!

3. Repeat these steps for **the FRONT photo, but in landscape orientation (7” wide x 5” high, 2100 pixels x 1500 pixels).