Send your first postcard via API

Our direct mail platform is robust, with so many features you can customize to optimize your direct mail campaigns, and you can send one—or one million—mailpieces with our Print & Mail APIs. The following will walk you through sending your first postcard, so you can learn to Lob!

First things first!

• Register for a Lob account or login here.

• There is no cost to work with our APIs in ‘Test’ mode, but you'll need to have payment info added to hit our Live API, and of course to send out mail. You can add your payment details here (select the Billing tab in the left-hand menu navigation and click on Payments).

Send a postcard!

Step 1: Download an API client

1. This is the tool you will use to send the API request. Two common options are Insomnia and Postman. We will use Insomnia for this demo, but all of this can be ported over to Postman as well:

   1. Insomnia - more simple, but offers fewer features

   2. Postman - offers more features, but is slightly more complicated to use

      1. This demo is Insomnia-specific, but here is a video of this same process within Postman

Step 2: Create HTML Templates within Lob

1. We will be creating two templates here, a Postcard Front and Postcard Back. Navigate to the HTML template creation page within your Lob account:

   1. https://dashboard.lob.com/templates

2. Create Postcard Front Template

   1. Click the ‘Create’ button to create a new template (will take you to: https://dashboard.lob.com/templates/create)

   2. For Description, write: “First Postcard - 6x9 - Front”

   3. For the Code Box: Copy the HTML code from this link, and paste into the Code Box

   4. Save, and return to https://dashboard.lob.com/templates

   5. Copy and store the new Template ID (it will start with tmpl_)

3. Create Postcard Back Template

   1. Click the ‘Create’ button to create a new template (will take you to: https://dashboard.lob.com/templates/create)

   2. For Description, write: “First Postcard - 6x9 - Back”

   3. For the Code Box: Copy the HTML code from this link, and paste into the Code Box

   4. Save, and return to https://dashboard.lob.com/templates

   5. Copy and store the new Template ID (it will start with tmpl_)

Step 3: Configure your first API call

We are now ready to send an actual API request to Lob! Open up Insomnia and take the following steps:

1. Click the + Button to create a new HTTP Request

   

   
2. Switch from a GET request to a POST request

   
3. Enter the Endpoint URL: https://api.lob.com/v1/postcards

   
4. Click on the ‘Auth’ drop-down and select ‘Basic Auth’. In the Username field, enter your test API Key. You can find this API Key in your Lob account at https://dashboard.lob.com/settings/api-keys. (**Copy your Test Key, not your Live Key.) Leave the Password field blank.

5. Click on the Headers tab and add a Content-Type Header with the value application/json

6. Click on the Body tab and select JSON from the drop-down menu. In the resulting box beneath, paste in the JSON code copied from this link.

7. Replace the “front” and “back” values with your own Template IDs from Step 3 above.

8. Replace the “firstname” merge variable with your own name.

Step 4: Hit Send!

1. Once you hit send, you will have sent your first API request!

• If it’s successful, you will see a 200 OK message in the right-side panel, and an API response from Lob confirming the creation of the mailpiece

• If it’s unsuccessful, you will see an error with a description of the problem

Step 5: Verify within your Lob account

1. Once you’ve successfully sent your mailpiece, open your Lob account to take a look at it. In the dashboard, under Print & Mail > Postcards, select Test mode. You will see your API-generated postcard and can click it to see more details including a PDF preview.

Step 6: Replicate in ‘Live’ mode & send yourself mail!

There is a cost for any mailpieces printed and sent. In our "Developer" edition, it will currently run you $0.924 for a 6"x9" postcard (inclusive of printing and postage). On our monthly subscription plans you can expect volume discounts in addition to access to more features; learn more here.

1. Follow the steps above, except use your Live API Key and Template IDs. Pass in your own address details in the “To” field, and you can send yourself a live mailpiece by clicking Send.

What's next?

Lob offers unprecedented visibility into where every single individual mail piece is from creation to delivery, and can provide notifications at each stage so that you can build downstream workflows and processes based on these alerts. You can also define, search, and slice and dice your mail piece data in any way you see fit, to better understand channel performance, attribution, and ultimately, ROI. Learn more about getting data & results here.

While it's a fun exercise to create a single postcard, the Lob platform is designed to be used at scale, and there is so much more functionality to explore and take advantage of. Dive in here!

If you need technical support or want more information (or a demo) on a specific product feature or direct mail use case, please reach out to us at [e-mail].