API quickstart guide

Jump in and explore our APIs

Overview of sending mail with Lob's APIs

The following quickstart guide allows you to jump in and explore the Lob Print & Mail API in your preferred programming language.

Lob account basics

In order to follow this Quickstart guide, you will need:

  • A Lob account; create your account here.

  • Your API keys (you can find these in your Dashboard under Settings → API Keys)

Language setup guides

These brief sections are aimed at developers who are less familiar with the languages with which they will be working with Lob API. Currently, Lob provides client libraries in the following languages:

(Note: If you are a TypeScript user, you can jump right in with a video tutorial: Sending a postcard with Typescript.)

Follow the instructions on the TypeScript download page. For Windows, installing through the Visual Studio text editor is the best option.

Follow the download and setup instructions on the official Node.js website.

To make switching between Node versions easy, install nvm on your local machine, following the instructions in the official Node Version Manager GitHub repository. To get the latest LTS release, run:

// nvm install --lts

Alternatively, Windows users should install the latest release of nvm-windows by following the instructions in its home repository.

Installing Lob’s API client

This Quickstart guide provides a code example of one of Lob’s core services: creating a postcard through our Print & Mail API. Make sure you are in the correct directory before running the code samples (creating one for the purpose of running these is advised, but not required).

Create a new directory and switch to it from your terminal app with these commands.

mkdir lob-qs

cd lob-qs

The next step is to install the version of Lob API which matches the language you are working in:

Install Lob's TypeScript SDK

npm install @lob/lob-typescript-sdk

Creating a Postcard via API

Now that a Lob API wrapper has been installed on your local machine, we can begin by sending a request to the API with the data necessary for postcard creation.

Open the text editor of your choice (if you need to download one, we recommend Visual Studio Code) and paste the code in the language of your choice: (As a note, if the address in question has a suite or apartment number, you can add in a data point for it as such: -d "to[address_line2]=<OPTIONAL SECONDARY INFORMATION>")

In your working directory:

  • Create a new file app.ts

  • Copy and paste the code below into app.ts

  • Replace <YOUR_TEST_KEY> with your Lob Test API Key in the code.

import {Configuration, Postcard, PostcardsApi, PostcardEditable, AddressEditable } from "@lob/lob-typescript-sdk"
async function demo() {
    const config: Configuration = new Configuration({
        username: "<YOUR_TEST_KEY>"
    const postcardData : PostcardEditable = new PostcardEditable({
        to: new AddressEditable({
          name: "Harry Zhang",
          address_line1: "210 King Street",
          address_city: "San Francisco",
          address_state: "CA",
          address_zip: "94107"
        from: new AddressEditable({
          name: "Leore Avidar",
          address_line1: "210 King Street",
          address_city: "San Francisco",
          address_state: "CA",
          address_zip: "94107"
        front:   "https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf",
        back:   "https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf"
    try {
        const result : Postcard = await new PostcardsApi(config).create(postcardData)
        return result
    } catch (err: any) {
 demo().then((result)=> console.log(result)).catch()

In your typescript project folder:

Compile your code

tsc app.ts Run your app:

node app.js

Data formatting

To ensure your requests are processed efficiently and without error, it's crucial to submit data in the precise format outlined in our documentation. Adhering to these specifications guarantees the continued reliability and performance of our API services.

For fields that are intended to accept only string values, submitting JSON objects in string format (stringified JSON objects) is not supported. Our system automatically parses and validates incoming data according to their expected types. As a result, providing a stringified JSON object in a field designated for string input can cause parsing errors or lead to unexpected validation results.

Understanding the response

This is a sample of the postcard object you will receive upon sending a creation request. Some information breakdowns:

  • As you can see, the to and from address objects have been expanded with more detail, including optional fields, creation and modification dates, and sanitized, verified address lines.

  • The postcard object also includes a signed URL to a digital copy of the created postcard, as well as thumbnails in three different sizes of the postcard’s front and back.

  • front_template_id and back_template_id are null in this particular object because we used inline HTML in the templates, rather than referencing a previously-saved HTML template.

  • Because we did not specify a size, the postcard is the default size of 4x6".

  • Both the send_date and the expected_delivery_date of the postcard are provided for transparency in the mailing process.

To see the postcards you have created, log into your Lob dashboard account and navigate to the “Postcards” tab on the left-side navigation menu. You can toggle between the ones you have created using either your test or live key:

More resources


For more comprehensive code examples for the different languages supported by Lob, see the individual GitHub repositories for each language:


You can also explore our APIs with Postman.

Last updated