Quickstart guide
Table of Contents
Lob account basicsLanguage setup guidesInstalling Lob’s API clientCreating a postcardUnderstanding the responseFurther resourcesLob account basics
In order to follow this quickstart guide, you will need:
- A Lob account
- Your API keys
- Settings → API Keys
- Read more about how Lob uses API Keys in our official documentation
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 these languages:
TypeScript (NodeJS)
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
Alternately, Windows users should install the latest release of nvm-windows by following the instructions in its home repository.
DeleteRuby
Mac
Run ruby -v
to check whether it’s pre-installed. If not, run brew install ruby
(make sure to install Homebrew first if you haven’t already). Add the path for your version of Ruby to your environment’s PATH
variable.
Windows
Download the appropriate version from Ruby’s official downloads page.
DeletePHP
Mac
Run php -v
to check whether it’s pre-installed. If not, run brew install php
(make sure to install Homebrew first if you haven’t already). Add the path for your version of PHP to your environment’s PATH variable.
https://www.php.net/downloads.php
Windows
Download the appropriate version from Ruby’s official downloads page.
DeleteInstalling Lob’s API client
This QuickStart guide provides a code example of Lob’s services: creating a postcard through Lob’s 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:
Typescript
Install Lob's TypeScript SDK
npm install @lob/lob-typescript-sdk
Install tslib a runtime library for TypeScript that contains all of the TypeScript helper functions.
npm i tslib
Delete
Python
Create a new virtual environment python3 -m venv venv
Activate the environment source venv/bin/activate
Install lob python from pypi pip install lob
PHP
curl -sS https://getcomposer.org/installer | php
php composer.phar require lob/lob-php
php composer.phar install
Java
In this guide, we will be using Maven.
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>12.3.7</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>
Delete
Creating a postcard
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>")
TypeScript
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, CountryExtended } from "@lob/lob-typescript-sdk"
async function demo() {
const config: Configuration = new Configuration({
username: "<YOUR_TEST_KEY>"
})
const postcardData : PostcardEditable = {
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",
address_country: CountryExtended.Us
},
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:
tsc app.ts
Run your app:
node app.js
Delete
Python
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
lob.api_key = "<YOUR_TEST_KEY>"
postcard = lob.Postcard.create(
description = "First Postcard",
to_address = {
"name": "Harry Zhang",
"address_line1": "210 King Street",
"address_city": "San Francisco",
"address_state": "CA",
"address_zip": "94107"
},
from_address = {
"name": "Leore Avidar",
"address_line1": "210 King Street",
"address_city": "San Francisco",
"address_state": "CA",
"address_zip": "94107",
"address_country": "US"
},
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(postcard)
In your working directory:
Run your app:python app.py
Delete
Ruby
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
Delete
PHP
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
Delete
Java
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;
// HashMap for Java 8 and below
// import java.util.HashMap;
import java.util.Map;
import com.lob.Lob;
import com.lob.model.Address;
import com.lob.model.Postcard;
import com.lob.net.LobResponse;
public class App
{
public static void main( String[] args )
{
Lob.init("<TEST_API_KEY>");
Map<String, String> mergeVariables = Map.of(
"name", "Harry"
);
// FOR JAVA VERSIONS 8 AND BELOW:
// Map<String, String> merge_variables = new HashMap<String, String>() {{
// put("name", "Harry");
// }};
try {
LobResponse<Postcard> response = new Postcard.RequestBuilder()
.setDescription("First Postcard")
.setTo(
new Address.RequestBuilder()
.setName("HARRY ZHANG")
.setLine1("210 KING STREET")
.setCity("SAN FRANCISCO")
.setState("CA")
.setZip("94107")
)
.setFrom(
new Address.RequestBuilder()
.setName("LEORE AVIDAR" )
.setLine1("210 KING STREET")
.setCity("SAN FRANCISCO")
.setState("CA")
.setZip("94107")
)
.setFront("<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>")
.setBack("<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>")
.setMergeVariables(mergeVariables)
.create();
Postcard postcard = response.getResponseBody();
System.out.println(postcard);
} catch (Exception err) {
System.out.println("Error on postcard creation: " + err);
}
}
}
In your maven project folder:
Compile your code: mvn clean install
Run your app:
mvn exec:java -Dexec.mainClass="com.company.app.App"
Delete
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 4in by 6in.
- Both the send date and the expected delivery date of the postcard are provided for transparency in the mailing process.
{
"id": "psc_9303c02190b14023",
"description": "First Postcard",
"metadata": {},
"to": {
"id": "adr_db9d33f9264e44f7",
"description": null,
"name": "HARRY ZHANG",
"company": null,
"phone": null,
"email": null,
"address_line1": "210 KING ST",
"address_line2": null,
"address_city": "SAN FRANCISCO",
"address_state": "CA",
"address_zip": "94107-1702",
"address_country": "US",
"metadata": {},
"date_created": "2022-02-08T18:10:41.383Z",
"date_modified": "2022-02-08T18:10:41.383Z",
"deleted": true,
"object": "address"
},
"from": {
"id": "adr_210a8d4b0b76d77b",
"description": null,
"name": "LEORE AVIDAR",
"company": null,
"phone": null,
"email": null,
"address_line1": "185 BERRY ST STE 6100",
"address_line2": null,
"address_city": "SAN FRANCISCO",
"address_state": "CA",
"address_zip": "94107-1741",
"address_country": "UNITED STATES",
"metadata": {},
"date_created": "2018-12-08T03:01:07.651Z",
"date_modified": "2018-12-08T03:01:07.651Z",
"object": "address"
},
"url": "https://lob-assets.com/postcards/psc_9303c02190b14023.pdf?version=v1&expires=1646935841&signature=G7LXMWoAn8HE9AVZXsJGO7GT5Mc0-iKLxUQf4lj1b7D0ms8qsMMtpxPKlidd5vatVMNvayXW_BbOgxgRxyO5BA",
"front_template_id": null,
"back_template_id": null,
"carrier": "USPS",
"tracking_events": [],
"thumbnails": [
{
"small": "https://lob-assets.com/postcards/psc_9303c02190b14023_thumb_small_1.png?version=v1&expires=1646935841&signature=WpiNeBNhR0Lo37_nq4CDGRoHYPvhAyCQKKIl7hhIfqodyXmQTN3YSYM9y9HwOPsPYnGqB0Jd_FCBJY5lVxkEBQ",
"medium": "https://lob-assets.com/postcards/psc_9303c02190b14023_thumb_medium_1.png?version=v1&expires=1646935841&signature=oHf6KUk1CG1BtKiaxrMBT16ADy0KZHCxtML5LyVJWG66Dy6lju7f5u7rgKGgPmuaC-lOVSPCPk--QDkyfKLNDg",
"large": "https://lob-assets.com/postcards/psc_9303c02190b14023_thumb_large_1.png?version=v1&expires=1646935841&signature=ZQRgvcdIObYS8UerLfb3QtZwAgCStNLkVq-ydaILqrx24L9au54rJCunCkeQuLPpuk4hixFJ6ptAKRlsztoeDQ"
},
{
"small": "https://lob-assets.com/postcards/psc_9303c02190b14023_thumb_small_2.png?version=v1&expires=1646935841&signature=zFAQaWytDMagDSjqKbZTCasAXCfm0SLifjAvS1xCcY3mT-n9hjhBEzsq4Rhb27X3V4y6c9NJe2ScLIhI5gLjAQ",
"medium": "https://lob-assets.com/postcards/psc_9303c02190b14023_thumb_medium_2.png?version=v1&expires=1646935841&signature=faayAHB04eyWFWNikcUscBzm1-_RE7MYtojUPYEiIfSat0BOOk8Pa-0dhT0LH9fOZZrQ0SFyeBy6m4UlX0dDDA",
"large": "https://lob-assets.com/postcards/psc_9303c02190b14023_thumb_large_2.png?version=v1&expires=1646935841&signature=3DSNOfS9Q80EZ4GIjKSYrI9qMqiLkAi5vKZBoHlfpQewzbJfUuI7O9p-78OCdVEixm1g1NDrv0jEUyZjDDicBw"
}
],
"merge_variables": {
"name": "Harry"
},
"size": "4x6",
"mail_type": "usps_first_class",
"expected_delivery_date": "2022-02-16",
"date_created": "2022-02-08T18:10:41.810Z",
"date_modified": "2022-02-08T18:10:41.810Z",
"send_date": "2022-02-08T18:10:41.810Z",
"object": "postcard"
}
In order 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:
Further resources
For more comprehensive code examples for the different languages supported by Lob, see the individual GitHub repositories for each language: