LogoLogo
API DocsTemplate GalleryProduct UpdatesContact Us
  • 📬Print & Mail
    • Ready to get started?
      • Pricing details
      • Fast Track Guide
    • Integrations
      • API integrations
        • Action IQ
        • Adobe Marketo Engage
        • Blueshift
        • Braze
        • Customer.io
        • Hubspot
        • Iterable
        • Jotform
        • Klayvio
        • Listrak
        • Make
        • Optimove
        • Salesforce
        • Salesforce Marketing Cloud
        • Segment
        • Simon Data
        • Zapier
      • No-code integrations
        • Agile CRM
        • Freshsales Suite
        • HubSpot
        • Microsoft Dynamics 365
        • Pipedrive
        • Salesforce
        • Salesforce Marketing Cloud
        • Zoho
      • Creative conversion tools
        • Figma plugin
    • Reaching your audience
      • Lob Audience
        • Target Audiences
        • Lookalike Audiences
        • Purchasing Audiences
      • All about addresses
      • Campaign audience guide
      • Additional Lob NCOA functionality
    • Designing mail creatives
      • Artboard layout
      • Creative formatting
        • PDF preflight checklist
        • Exporting PDFs from InDesign
        • Rendering errors
      • Mail piece design specs
        • Postcards
        • Self-Mailers
        • Letters
        • Letter envelopes
        • Letter add-ons
        • Checks
        • Snap packs
        • Booklets
        • Custom mail
      • Maximizing engagement
        • Dynamic personalization
          • Advanced templating (Handlebars)
            • Dynamic table tutorial
        • Adding QR codes
        • Short URLs
        • Informed Delivery
    • Building a mail strategy
      • One-time campaigns or triggered sends?
      • Choosing a delivery strategy
      • Managing mail settings
        • Using metadata
        • Declaring mail use type
      • USPS Promotions Through Lob
        • Tactile, Sensory & Interactive Promotion
        • Integrated Technology Promotion
        • First Class Mail Advertising Promotion
        • Add-Ons
      • Mailing class and postage
        • Certified Mail or Registered Mail
      • International mail
    • Send mail!
      • Launch your first campaign
      • Send mail via Print & Mail API
      • Send campaigns via the Campaigns API
      • USPS Secure Destruction
    • Getting data & results
      • Tracking your mail
      • Mail analytics
      • Measuring attribution
      • Using webhooks
      • Exporting mail data
  • 🏠Address Verification
    • Ready to start AV?
      • US AV product suite
      • International AV suite
      • AV pricing
    • AV best practices
    • AV integrations & libraries
      • AV Elements
      • Shopify App: Address Cleanser
    • AV FAQs
  • đź’»Developer Docs
    • API quickstart guide
    • SDKs & libraries
    • Postman & similar tools
    • Error reference
    • Upgrading API version
    • Technical use case guides
      • Mass deletion setup
      • NCOA responses
      • Override cancellation window
      • Visibility of address changes
      • Ingesting tracking events with webhooks
  • 🔑Account Management
    • Signing into Lob
    • API keys
    • Account settings
      • Account-level data logs
    • User settings
    • Billing
      • Lob Credits
      • Lob Payment Methods
      • Sales Tax FAQ
        • Applicable sales tax by state
          • ​Subscriptions and Services
          • Lob Audience
          • Delivery Location for Operational Mail
          • Customer Billing Address for Operational Mail
          • Delivery Location for Marketing Mail
          • Postage Exemption
          • Professional Services
        • Tax exemption guide
  • 📞Resources
    • Getting support
    • Security & privacy
    • Data retention
    • Sustainability
    • Private labeling Lob
    • Direct mail glossary
Powered by GitBook
On this page
  • Lob account basics
  • Language setup guides
  • Installing Lob’s API client
  • Creating a Postcard via API
  • Data formatting
  • Understanding the response
  • More resources
  • Github
  • Postman

Was this helpful?

Export as PDF
  1. Developer Docs

API quickstart guide

Jump in and explore our APIs

PreviousAV FAQsNextSDKs & libraries

Last updated 2 months ago

Was this helpful?

The following quickstart guide allows you to jump in and explore the in your preferred programming language.

Lob account basics

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

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:

// nvm install --lts

Mac

Windows

Mac

Runphp -vto check whether it’s pre-installed.

Windows

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

Create a new virtual environment

python3 -m venv venv

Activate the environment

source venv/bin/activate

Install lob python from pypi

pip install lob_python

gem install lob

curl -sS https://getcomposer.org/installer | php
php composer.phar require lob/lob-php
php composer.phar install

From the command line, create a new maven project.

mvn archetype:generate -DgroupId=com.company.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Edit the pom.xml file in the my-app folder to include this bit of code:

 <dependencies>
  <dependency>
    <groupId>com.lob</groupId>
    <artifactId>lob-java</artifactId>
    <version>13.0.0</version>
  </dependency>
  ...
 </dependencies>

In the pom.xml file update the source and target to 1.8

 <maven.compiler.source>1.8</maven.compiler.source>
 <maven.compiler.target>1.8</maven.compiler.target> 

Create a new C# project

dotnet new console

Install Lob's .NET SDK

dotnet add package lob.dotnet

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) {
        console.error(err)
    }
}
 
 demo().then((result)=> console.log(result)).catch()

In your typescript project folder:

Compile your code

tsc app.ts Run your app:

node app.js

In your working directory:

  • Create a new file app.py

  • Copy and paste the code below into app.py

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

import lob_python
from lob_python.exceptions import ApiException

from lob_python.model.postcard_editable import PostcardEditable
from lob_python.model.address_editable import AddressEditable
from lob_python.model.merge_variables import MergeVariables
from lob_python.model.country_extended import CountryExtended

from lob_python.api.postcards_api import PostcardsApi

configuration = lob_python.Configuration(
  username = "<YOUR_TEST_KEY>"
)

postcard_editable = PostcardEditable(
  description = "First Postcard",
  front = "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
  back = "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>",
  to = AddressEditable(
    name = "Harry Zhang",
    address_line1 = "210 King Street",
address_city = "San Francisco",
address_state = "CA",
address_zip = "94107",
  ),
  _from = AddressEditable(
    name = "Leore Avidar",
    address_line1 = "210 King Street",
    address_city = "San Francisco",
    address_state = "CA",
    address_zip = "94107",
    address_country = CountryExtended("US")
  ),
  merge_variables = MergeVariables(
    name = "Harry",
  ),
)

with lob_python.ApiClient(configuration) as api_client:
  api = PostcardsApi(api_client)

try:
  created_postcard = api.create(postcard_editable)
  print(created_postcard)
except ApiException as e:
  print(e)

In your working directory:

Run your app:

python app.py

In your working directory:

  • Create a new file app.rb

  • Copy and paste the code below into app.rb

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

require 'lob.rb'
require 'pp'
 
lob = Lob::Client.new(api_key: "<TEST_API_KEY>")
 
pp lob.postcards.create(
 description: "First Postcard",
  to: {
    name: "Harry Zhang",
    address_line1: "210 King Street",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: {
    name: "Leore Avidar",
    address_line1: "210 King Street",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  merge_variables: { name: "Harry" },
  front: "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
  back: "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>"
)

In your working directory:

Run your app:

ruby app.rb

In your working directory:

  • Create a new file app.php

  • Copy and paste the code below into app.php

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

<?php require __DIR__ . '/vendor/autoload.php';
 
$lob = new \Lob\Lob('<TEST_API_KEY');
 
$postcard = $lob->postcards()->create(array(
    "description" => "First Postcard",
    "to[name]"              => "HARRY ZHANG",
    "to[address_line1]"     => "210 KING STREET",
    "to[address_city]"      => "SAN FRANCISCO",
    "to[address_state]"     => "CA",
    "to[address_zip]"       => "94107",
    "from[name]"            => "LEORE AVIDAR",
    "from[address_line1]"   => "210 KING STREET",
    "from[address_city]"    => "SAN FRANCISCO",
    "from[address_state]"   => "CA",
    "from[address_zip]"     => "94107",
    "front"                 => "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
    "back"                  => "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>",
    "merge_variables[name]" => "Harry"
  ));
 print_r($postcard);
?>

In your working directory:

Run your app:

php app.php

In your new maven project:

  • Locate the App.java file in main/java/com/company/app

  • Copy and paste the code below into App.java

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

package com.company.app;

import com.lob.api.ApiClient;
import com.lob.api.ApiException;
import com.lob.api.Configuration;
import com.lob.api.auth.*;
import com.lob.model.*;
import com.lob.api.client.PostcardsApi;

public class App
{
    public static void main( String[] args )
    {

        ApiClient lobClient = Configuration.getDefaultApiClient();

        // Configure HTTP basic authorization: basicAuth
        HttpBasicAuth basicAuth = (HttpBasicAuth) lobClient.getAuthentication("basicAuth");
        basicAuth.setUsername("<YOUR_LOB_API_KEY>");

        PostcardsApi apiInstance = new PostcardsApi(lobClient);
        PostcardEditable postcardEditable = new PostcardEditable();

        AddressEditable to = new AddressEditable();
        to.setName("MORTICIA ADDAMS");
        to.setAddressLine1("1313 CEMETERY LN");
        to.setAddressCity("WESTFIELD");
        to.setAddressState("NJ");
        to.setAddressZip("07091");

        AddressEditable to = new AddressEditable();
        to.setName("MORTICIA ADDAMS");
        to.setAddressLine1("1313 CEMETERY LN");
        to.setAddressCity("WESTFIELD");
        to.setAddressState("NJ");
        to.setAddressZip("07091");

        AddressEditable from = new AddressEditable();
        from.setName("FESTER");
        from.setAddressLine1("001 CEMETERY LN");
        from.setAddressLine2("SUITE 666");
        from.setAddressCity("WESTFIELD");
        from.setAddressState("NJ");
        from.setAddressZip("07091");

        Gson gson = new Gson();
        postcardEditable.setTo(gson.toJson(to));
        postcardEditable.setFrom(gson.toJson(from));
        postcardEditable.setFront("https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf");
        postcardEditable.setBack("https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf");

        try {
            Postcard result = apiInstance.create(postcardEditable);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling PostcardsApi#postcardCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

In your maven project folder:

Compile your code:

mvn clean install

Run your app:

mvn exec:java -Dexec.mainClass="com.company.app.App"

In your working directory:

  • In your working directory, you should have a file named Program.cs from running the dotnet new console command.

  • Copy and paste the code below into Program.cs.

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

using System;
using System.Collections.Generic;
using System.Diagnostics;
using lob.dotnet.Api;
using lob.dotnet.Client;
using lob.dotnet.Model;

namespace test_dotnet
{
   class Program
   {
       static void Main(string[] args)
       {
           Configuration config = new Configuration();
           config.BasePath = "https://api.lob.com/v1";
           // Configure HTTP basic authorization: basicAuth
           config.Username = "<YOUR_TEST_KEY>";

           Dictionary<string, string> mergeVariables = new Dictionary<string, string>();
           mergeVariables.Add("name", "Harry");

           PostcardsApi apiInstance = new PostcardsApi(config);

           AddressEditable to = new AddressEditable(
               "210 King St",  // addressLine1
               null,  // addressLine2
               "San Francisco",  // addressCity
               "CA",  // addressState
               "94107",  // addressZip
               CountryExtended.US,  // addressCounty
               "First Postcard",  // description
               "Harry Zhang" // name
           );

           AddressEditable from = new AddressEditable(
               "210 King St",  // addressLine1
               null,  // addressLine2
               "San Francisco",  // addressCity
               "CA",  // addressState
               "94107",  // addressZip
               CountryExtended.US,  // addressCounty
               null,  // description
               "Leore Avidar" // name
           );

           PostcardEditable postcardEditable = new PostcardEditable(
               to.ToJson(),  // to
               from.ToJson(),  // from
               default(PostcardSize),  // size
               "First Postcard",  // description
               null,  // metadata
               default(MailType),  // mailType
               mergeVariables,  // mergeVariables
               default(DateTime),  // sendDate
               "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",  // front
               "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>" // back
           );

           try
           {
               // create
               Postcard result = apiInstance.create(postcardEditable);
               Console.WriteLine(result.ToString());
           }
           catch (ApiException e)
           {
               Console.WriteLine("Exception when calling PostcardsApi.create: " + e.Message );
               Console.WriteLine("Status Code: "+ e.ErrorCode);
               Console.WriteLine(e.StackTrace);
           }
       }
   }
}

In your working directory:

Run your app:

dotnet run

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.

More resources

Github

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

Postman

A Lob account; create your account .

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

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

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

Follow the download and setup instructions on .

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

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

Download and set up the appropriate version from .

Run ruby -v to check whether it’s pre-installed. If not, run brew install ruby (make sure to first if you haven’t already). Add the path for your version of Ruby to your environment’s PATH variable.

Download the appropriate version from .

If not, runbrew install php(make sure to first if you haven’t already). Add the path for your version of PHP to your environment’s PATH variable.

Download the appropriate version from

Download either the Arm 64 or x64 DMG Installer from .

Download from .

In this guide, we will be using .

To see the postcards you have created, log into your 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:

(see also, video)

You can also .

đź’»
here
API keys
Sending a postcard with Typescript
TypeScript download page
the official Node.js website
the instructions
latest release
the instructions
Python’s official website
install Homebrew
Ruby’s official downloads page
install Homebrew
PHP's official downloads page.
Java’s official downloads page
Microsoft's official website
Maven
Lob dashboard account
TypeScript
Get started sending postcards with TypeScript
Python
Ruby
PHP
Java
Elixir
C#/.NET
explore our APIs with Postman
Lob Print & Mail API
Overview of sending mail with Lob's APIs