Lob.com Letters API
The letters endpoint allows you to easily print and mail letters. The API provides endpoints for creating letters, retrieving individual letters, canceling letters, and retrieving a list of letters. back to top
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/lobcom-letters-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
title: Lob Letters API
version: 1.22.0
description: 'The Lob API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and uses HTTP response codes to indicate any API errors. <p>
'
license:
name: MIT
url: https://mit-license.org/
contact:
name: Lob Developer Experience
url: https://support.lob.com/
email: lob-openapi@lob.com
termsOfService: https://www.lob.com/legal
servers:
- url: https://api.lob.com/v1
description: production
security:
- basicAuth: []
tags:
- name: Letters
description: 'The letters endpoint allows you to easily print and mail letters. The API provides endpoints for
creating letters, retrieving individual letters, canceling letters, and retrieving a list of letters.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
'
paths:
/letters/{ltr_id}:
parameters:
- in: path
name: ltr_id
description: id of the letter
required: true
schema:
$ref: '#/components/schemas/ltr_id'
get:
operationId: letter_retrieve
summary: Retrieve
description: Retrieves the details of an existing letter. You need only supply the unique letter identifier that was returned upon letter creation.
tags:
- Letters
responses:
'200':
description: Returns a letter object
content:
$ref: '#/components/mediaTypes/letter'
default:
$ref: '#/components/responses/mailpiece_error'
x-codeSamples:
- lang: Shell
source: "curl https://api.lob.com/v1/letters/ltr_4868c3b754655f90 \\\n -u REDACTED_LOB_KEY:\n"
label: CURL
- lang: Typescript
source: "try {\n const letter= await new LettersApi(config).get('ltr_xxxx');\n} catch (err: any) {\n console.error(err);\n}\n"
label: TYPESCRIPT
- lang: Javascript
source: "Lob.letters.retrieve('ltr_4868c3b754655f90', function (err, res) {\n console.log(err, res);\n});\n"
label: NODE
- lang: Ruby
source: "letterApi = LettersApi.new(config)\n\nbegin\n retrievedLetter = letterApi.get(\"ltr_4868c3b754655f90\")\nrescue => err\n p err.message\nend\n"
label: RUBY
- lang: Python
source: "with ApiClient(configuration) as api_client:\n api = LettersApi(api_client)\n\ntry:\n letter = api.get(\"ltr_4868c3b754655f90\")\nexcept ApiException as e:\n print(e)\n"
label: PYTHON
- lang: PHP
source: "$apiInstance = new OpenAPI\\Client\\Api\\LettersApi($config, new GuzzleHttp\\Client());\n\ntry {\n $result = $apiInstance->get(\"ltr_4868c3b754655f90\");\n} catch (Exception $e) {\n echo $e->getMessage(), PHP_EOL;\n}\n"
- lang: Java
source: "LettersApi apiInstance = new LettersApi(config);\n\ntry {\n Letter response = apiInstance.get(\"ltr_4868c3b754655f90\");\n} catch (ApiException e) {\n e.printStackTrace();\n}\n"
label: JAVA
- lang: Elixir
source: 'Lob.Letter.find("ltr_4868c3b754655f90")
'
label: ELIXIR
- lang: CSharp
source: "LettersApi api = new LettersApi(config);\n\ntry {\n Letter response = api.get(\"ltr_4868c3b754655f90\");\n} catch (ApiException e) {\n Console.WriteLine(e.ToString());\n}\n"
label: CSHARP
- lang: Go
source: "var context = context.Background()\ncontext = context.WithValue(suite.ctx, lob.ContextBasicAuth, lob.BasicAuth{UserName: os.Getenv(\"<YOUR_API_KEY>\")})\n\nvar apiClient = *lob.NewAPIClient(configuration)\n\nfetchedLetter, _, err := apiClient.LettersApi.Get(context,\"ltr_4868c3b754655f90\").Execute()\n\nif err != nil {\n return err\n}\n"
label: GO
delete:
operationId: letter_cancel
summary: Cancel
description: Completely removes a letter from production. This can only be done if the letter has a `send_date` and the `send_date` has not yet passed. If the letter is successfully canceled, you will not be charged for it. Read more on [cancellation windows](#section/Cancellation-Windows) and [scheduling](#section/Scheduled-Mailings). Scheduling and cancellation is a premium feature. Upgrade to the appropriate <a href="https://dashboard.lob.com/#/settings/editions" target="_blank">Print & Mail Edition</a> to gain access.
tags:
- Letters
responses:
'200':
$ref: '#/components/responses/letter_deleted'
default:
$ref: '#/components/responses/mailpiece_error'
x-codeSamples:
- lang: Shell
source: "curl -X DELETE https://api.lob.com/v1/letters/ltr_4868c3b754655f90 \\\n -u REDACTED_LOB_KEY:\n"
label: CURL
- lang: Typescript
source: "try {\n const deleteLetter = await new LettersApi(config).cancel('ltr_xxxx')\n} catch (err: any) {\n console.error(err);\n}\n"
label: TYPESCRIPT
- lang: Javascript
source: "Lob.letters.cancel('ltr_4868c3b754655f90', function (err, res) {\n console.log(err, res);\n});\n"
label: NODE
- lang: Ruby
source: "letterApi = LettersApi.new(config)\n\nbegin\n deletedLetter = letterApi.cancel(\"ltr_4868c3b754655f90\")\nrescue => err\n p err.message\nend\n"
label: RUBY
- lang: Python
source: "with ApiClient(configuration) as api_client:\n api = LettersApi(api_client)\n\ntry:\n deleted_resource = api.cancel(\"ltr_4868c3b754655f90\")\nexcept ApiException as e:\n print(e)\n"
label: PYTHON
- lang: PHP
source: "$apiInstance = new OpenAPI\\Client\\Api\\LettersApi($config, new GuzzleHttp\\Client());\n\ntry {\n $result = $apiInstance->cancel(\"ltr_4868c3b754655f90\");\n} catch (Exception $e) {\n echo $e->getMessage(), PHP_EOL;\n}\n"
- lang: Java
source: "LettersApi apiInstance = new LettersApi(config);\n\ntry {\n LetterDeletion response = apiInstance.cancel(\"ltr_4868c3b754655f90\");\n} catch (ApiException e) {\n e.printStackTrace();\n}\n"
label: JAVA
- lang: Elixir
source: 'Lob.Letter.destroy("ltr_4868c3b754655f90")
'
label: ELIXIR
- lang: CSharp
source: "LettersApi api = new LettersApi(config);\n\ntry {\n LetterDeletion response = api.cancel(\"ltr_4868c3b754655f90\");\n} catch (ApiException e) {\n Console.WriteLine(e.ToString());\n}\n"
label: CSHARP
- lang: Go
source: "var context = context.Background()\ncontext = context.WithValue(suite.ctx, lob.ContextBasicAuth, lob.BasicAuth{UserName: os.Getenv(\"<YOUR_API_KEY>\")})\n\nvar apiClient = *lob.NewAPIClient(configuration)\n\ndeletedLetter, _, err := apiClient.LettersApi.Cancel(context, \"ltr_4868c3b754655f90\").Execute()\n\nif err != nil {\n return err\n}\n"
label: GO
/letters:
get:
operationId: letters_list
summary: List
description: Returns a list of your letters. The letters are returned sorted by creation date, with the most recently created letters appearing first.
tags:
- Letters
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/before_after'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/date_created'
- $ref: '#/components/parameters/metadata'
- $ref: '#/components/parameters/campaign_id'
- $ref: '#/components/parameters/status'
- in: query
name: color
description: Set to `true` to return only color letters. Set to `false` to return only black & white letters.
schema:
type: boolean
- $ref: '#/components/parameters/scheduled'
- $ref: '#/components/parameters/send_date'
- $ref: '#/components/parameters/mail_type'
- $ref: '#/components/parameters/sort_by'
responses:
'200':
$ref: '#/components/responses/all_letters'
default:
$ref: '#/components/responses/mailpiece_error'
x-codeSamples:
- lang: Shell
source: "curl -X GET \"https://api.lob.com/v1/letters?limit=2\" \\\n -u REDACTED_LOB_KEY:\n"
label: CURL
- lang: typescript
source: "try {\n const letters = await new LettersApi(config).list(2);\n} catch (err: any) {\n console.error(err);\n}\n"
label: TYPESCRIPT
- lang: Javascript
source: "Lob.letters.list({limit: 2}, function (err, res) {\n console.log(err, res);\n});\n"
label: NODE
- lang: Ruby
source: "lettersApi = LettersApi.new(config)\n\nbegin\n letters = lettersApi.list({ limit: 2 })\nrescue => err\n p err.message\nend\n"
label: RUBY
- lang: Python
source: "with ApiClient(configuration) as api_client:\n api = LettersApi(api_client)\n\ntry:\n letters = api.list(limit=2)\nexcept ApiException as e:\n print(e)\n"
label: PYTHON
- lang: PHP
source: "$apiInstance = new OpenAPI\\Client\\Api\\LettersApi($config, new GuzzleHttp\\Client());\n\ntry {\n $result = $apiInstance->list(\n 2, // limit\n );\n} catch (Exception $e) {\n echo $e->getMessage(), PHP_EOL;\n}\n"
- lang: Java
source: "LettersApi apiInstance = new LettersApi(config);\n\ntry {\n LetterList response = apiInstance.list(\n 2, // limit\n null, // before\n null, // after\n null, // include\n null, // dateCreated\n null, // metadata\n null, // color\n null, // scheduled\n null, // sendDate\n null, // mailType\n null // sortBy\n );\n} catch (ApiException e) {\n e.printStackTrace();\n}\n"
label: JAVA
- lang: Elixir
source: 'Lob.Letter.list(%{limit: 2})
'
label: ELIXIR
- lang: CSharp
source: "LettersApi api = new LettersApi(config);\n\nList<string> includeList = new List<string>();\nincludeList.Add(\"total_count\");\nDictionary<String, String> metadata = new Dictionary<String, String>();\nmetadata.Add(\"name\", \"Harry\");\nDictionary<String, DateTime> dateCreated = new Dictionary<String, DateTime>();\nDateTime dateCreatedDate = DateTime.Today.AddMonths(-1);\ndateCreated.Add(\"lt\", dateCreatedDate);\nDictionary<String, String> sendDate = new Dictionary<String, String>();\nsendDate.Add(\"lt\", DateTime.Now.ToString(\"yyyy-MM-ddTHH\\\\:mm\\\\:ss.fffffffzzz\"));\nSortBy3 sortBy = new SortBy3(SortBy3.DateCreatedEnum.Asc);\n\ntry {\n LetterList response = api.list(\n 2, // limit\n null, // before\n null, // after\n includeList, // include\n dateCreated, // dateCreated\n metadata, // metadata\n true, // color\n true, // scheduled\n sendDate, // sendDate\n MailType.FirstClass, // mailType\n sortBy // sortBy\n );\n} catch (ApiException e) {\n Console.WriteLine(e.ToString());\n}\n"
label: CSHARP
- lang: Go
source: "var context = context.Background()\ncontext = context.WithValue(suite.ctx, lob.ContextBasicAuth, lob.BasicAuth{UserName: os.Getenv(\"<YOUR_API_KEY>\")})\n\nvar apiClient = *lob.NewAPIClient(configuration)\nLetterList = apiClient.LettersApi.List(context).Execute()\nif err != nil {\n return err\n}\n"
label: GO
post:
operationId: letter_create
summary: Create
description: Creates a new letter given information
tags:
- Letters
parameters:
- $ref: '#/components/parameters/idem-header'
- $ref: '#/components/parameters/idem-query'
- $ref: '#/components/parameters/lob-version'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/letter_editable'
example:
description: demo
to:
description: Harry - Office
name: Harry Zhang
company: Lob
email: harry@lob.com
phone: '5555555555'
address_line1: 210 King St
address_line2: '# 6100'
address_city: San Francisco
address_state: CA
address_zip: '94107'
address_country: US
from:
name: Harry
address_line1: 210 King St
address_line2: '# 6100'
address_city: San Francisco
address_state: CA
address_zip: '94107'
file: '<html style=''padding-top: 3in; margin: .5in;''>HTML Letter for {{name}}</html>'
color: true
cards:
- card_c51ae96f5cebf3e
double_sided: false
address_placement: bottom_first_page
mail_type: usps_first_class
return_envelope: true
perforated_page: 1
merge_variables:
name: Harry
metadata:
spiffy: 'true'
send_date: '2017-11-01T00:00:00.000Z'
extra_service: registered
custom_envelope: null
use_type: marketing
qr_code:
position: relative
redirect_url: https://www.lob.com
width: '2'
top: '2'
right: '2'
pages: 1-2,4-5
fsc: true
print_speed: core
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/letter_editable'
example:
description: demo
to:
description: Harry - Office
name: Harry Zhang
company: Lob
email: harry@lob.com
phone: '5555555555'
address_line1: 210 King St
address_line2: '# 6100'
address_city: San Francisco
address_state: CA
address_zip: '94107'
address_country: US
from:
name: Harry
address_line1: 210 King St
address_line2: '# 6100'
address_city: San Francisco
address_state: CA
address_zip: '94107'
file: '<html style=''padding-top: 3in; margin: .5in;''>HTML Letter for {{name}}</html>'
color: true
cards:
- card_c51ae96f5cebf3e
double_sided: false
address_placement: top_first_page
mail_type: usps_first_class
return_envelope: true
perforated_page: 1
merge_variables:
name: Harry
metadata:
spiffy: 'true'
send_date: '2017-11-01T00:00:00.000Z'
extra_service: registered
custom_envelope: null
use_type: marketing
qr_code:
position: relative
redirect_url: https://www.lob.com
width: '2'
bottom: '2'
right: '2'
pages: 1,4
fsc: true
print_speed: core
encoding:
to:
style: deepObject
explode: true
from:
style: deepObject
explode: true
merge_variables:
style: deepObject
explode: true
metadata:
style: deepObject
explode: true
multipart/form-data:
schema:
$ref: '#/components/schemas/letter_editable'
example:
description: demo
to:
description: Harry - Office
name: Harry Zhang
company: Lob
email: harry@lob.com
phone: '5555555555'
address_line1: 210 King St
address_line2: '# 6100'
address_city: San Francisco
address_state: CA
address_zip: '94107'
address_country: US
from:
name: Harry
address_line1: 210 King St
address_line2: '# 6100'
address_city: San Francisco
address_state: CA
address_zip: '94107'
file: '<html style=''padding-top: 3in; margin: .5in;''>HTML Letter for {{name}}</html>'
color: true
cards:
- card_c51ae96f5cebf3e
double_sided: false
address_placement: top_first_page
mail_type: usps_first_class
return_envelope: true
perforated_page: 1
merge_variables:
name: Harry
metadata:
spiffy: 'true'
send_date: '2017-11-01T00:00:00.000Z'
extra_service: registered
custom_envelope: null
use_type: marketing
qr_code:
position: relative
redirect_url: https://www.lob.com
width: '2'
bottom: '2'
left: '2'
pages: 1,3-5
fsc: true,
print_speed: core
responses:
'200':
$ref: '#/components/responses/post_letter'
default:
$ref: '#/components/responses/mailpiece_error'
x-codeSamples:
- lang: Shell
source: "curl https://api.lob.com/v1/letters \\\n -u YOUR_API_KEY \\\n -d 'description=Demo Letter' \\\n -d 'to[name]=Harry Zhang' \\\n -d 'to[address_line1]=210 King St' \\\n -d 'to[address_line2]=# 6100' \\\n -d 'to[address_city]=San Francisco' \\\n -d 'to[address_state]=CA' \\\n -d 'to[address_zip]=94107' \\\n -d 'from=adr_210a8d4b0b76d77b' \\\n --data-urlencode 'file=<html style=\"padding-top: 3in; margin: .5in;\">HTML Letter for {{name}}</html>' \\\n -d 'merge_variables[name]=Harry' \\\n -d 'color=true' \\\n -d 'cards[]=card_c51ae96f5cebf3e' \\\n -d 'qr_code[position]=relative' \\\n -d 'qr_code[redirect_url]=https://www.lob.com' \\\n -d 'qr_code[width]=2' \\\n -d 'qr_code[bottom]=2' \\\n -d 'qr_code[left]=2' \\\n -d 'qr_code[pages]=3,4-5' \\\n -d 'fsc=true' \\\n -d 'print_speed=core'\n"
label: CURL
- lang: Typescript
source: "const letterCreate = new LetterEditable({\n to: {\n name: 'Harry Zhang',\n address_line1: '210 King St',\n address_line2: '# 6100',\n address_city: 'San Francisco',\n address_state: 'CA',\n address_zip: '94107'\n },\n from: 'adr_xxxx',\n color: true,\n extra_service: LetterEditableExtraServiceEnum.Certified,\n file: 'https://s3-us-west-2.amazonaws.com/public.lob.com/assets/us_letter_1pg.pdf',\n use_type: 'marketing',\n qr_code : {\n position: 'relative',\n redirect_url: 'https://www.lob.com',\n width: '2',\n bottom: '2',\n left: '2',\n pages: '2,5'\n },\n fsc: true,\n print_speed: 'core'\n});\n\ntry {\n const myLetter = await new LettersApi(config).create(letterCreate);\n} catch (err: any) {\n console.error(err);\n}\n"
label: TYPESCRIPT
- lang: Javascript
source: "Lob.letters.create({\n description: 'Demo Letter',\n to: {\n name: 'Harry Zhang',\n address_line1: '210 King St',\n address_line2: '# 6100',\n address_city: 'San Francisco',\n address_state: 'CA',\n address_zip: '94107'\n },\n from: 'adr_210a8d4b0b76d77b',\n file: '<html style=\"padding-top: 3in; margin: .5in;\">HTML Letter for {{name}}</html>',\n merge_variables: {\n name: 'Harry'\n },\n color: true,\n cards: ['card_c51ae96f5cebf3e'],\n use_type: 'marketing',\n qr_code : {\n position: 'relative',\n redirect_url: 'https://www.lob.com',\n width: '2',\n bottom: '2',\n left: '2',\n pages: '2,4-5'\n },\n fsc: true,\n print_speed: 'core'\n}, function (err, res) {\n console.log(err, res);\n});\n"
label: NODE
- lang: Ruby
source: "letterCreate = LetterEditable.new({\n description: \"Demo Letter\",\n from: \"adr_210a8d4b0b76d77b\",\n file: \"<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>\",\n color: \"true\",\n to: AddressEditable.new({\n name: \"Harry Zhang\",\n address_line1: \"210 King St\",\n address_line2: \"# 6100\",\n address_city: \"San Francisco\",\n address_state: \"CA\",\n address_zip: \"94107\",\n }),\n merge_variables: {\n name: \"Harry\"\n },\n cards: [\n \"card_c51ae96f5cebf3e\",\n ],\n use_type: \"marketing\",\n fsc: true,\n print_speed: 'core'\n});\n\nletterApi = LettersApi.new(config)\n\nbegin\n createdLetter = letterApi.create(letterCreate)\nrescue => err\n p err.message\nend\n"
label: RUBY
- lang: Python
source: "letter_editable = LetterEditable(\n description = \"Demo Letter\",\n _from = \"adr_210a8d4b0b76d77b\",\n file = \"<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>\",\n color = True,\n to = AddressEditable(\n name = \"Harry Zhang\",\n address_line1 = \"210 King St\",\n address_line2 = \"# 6100\",\n address_city = \"San Francisco\",\n address_state = \"CA\",\n address_zip = \"94107\",\n ),\n merge_variables = MergeVariables(\n name = \"Harry\",\n ),\n cards = [\n \"card_c51ae96f5cebf3e\",\n ],\n use_type = \"marketing\",\n qr_code = {\n \"position\" : \"relative\",\n \"redirect_url\" : \"https://www.lob.com\",\n \"width\" : \"2\",\n \"bottom\" : \"2\",\n \"left\" : \"2\",\n \"pages\" : \"1,3\"\n },\n fsc = true,\n print_speed = 'core'\n)\n\nwith ApiClient(configuration) as api_client:\n api = LettersApi(api_client)\n\ntry:\n created_letter = api.create(letter_editable)\nexcept ApiException as e:\n print(e)\n"
label: PYTHON
- lang: PHP
source: "$to = new OpenAPI\\Client\\Model\\AddressEditable(\n array(\n \"name\" => \"Harry Zhang\",\n \"address_line1\" => \"210 King St\",\n \"address_line2\" => \"# 6100\",\n \"address_city\" => \"San Francisco\",\n \"address_state\" => \"CA\",\n \"address_zip\" => \"94107\",\n )\n);\n\n$qr_code = new OpenAPI\\Client\\Model\\QRCode(\n array(\n \"position\" => \"relative\",\n \"redirect_url\" => \"https://www.lob.com\",\n \"width\" => \"2\",\n \"bottom\" => \"2\",\n \"left\" => \"2\",\n \"pages\" => \"1,3,5\",\n )\n);\n\n$merge_variables = new stdClass;\n$merge_variables->name = \"Harry\";\n\n$use_type = \"marketing\";\n$fsc = true;\n$print_speed = 'core';\n\n$apiInstance = new OpenAPI\\Client\\Api\\LettersApi($config, new GuzzleHttp\\Client());\n$letter_editable = new OpenAPI\\Client\\Model\\LetterEditable(\n array(\n \"description\" => \"Demo Letter\",\n \"from\" => \"adr_210a8d4b0b76d77b\",\n \"file\" => \"<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>\",\n \"color\" => \"true\",\n \"to\" => $to,\n \"merge_variables\" => $merge_variables,\n \"cards\" => array(\n \"card_c51ae96f5cebf3e\",\n \"card_thingy\",\n ),\n \"use_type\" => $use_type;\n \"qr_code\" => $qr_code,\n \"fsc\" => $fsc,\n \"print_speed\" => $print_speed,\n )\n);\n\ntry {\n $result = $apiInstance->create($letter_editable);\n} catch (Exception $e) {\n echo $e->getMessage(), PHP_EOL;\n}\n"
- lang: Java
source: "Map<String, String> merge_variables = new HashMap<String, String>();\nmerge_variables.put(\"name\", \"Harry\");\n\nLettersApi apiInstance = new LettersApi(config);\n\nAddressEditable to = new AddressEditable();\nto.setName(\"Harry Zhang\");\nto.setAddressLine1(\"210 King St\");\nto.setAddressLine2(\"# 6100\");\nto.setAddressCity(\"San Francisco\");\nto.setAddressState(\"CA\");\nto.setAddressZip(\"94107\");\n\nQRCode qrCode = new QRCode();\nqrCode.setPosition(\"relative\");\nqrCode.setRedirectUrl(\"https://www.lob.com\");\nqrCode.setWidth(\"2\");\nqrCode.setLeft(\"2\");\nqrCode.setBottom(\"2\");\nqrCode.setPages(\"1,3,5\");\n\nList<String> cards = new ArrayList<String>();\ncards.add(\"card_c51ae96f5cebf3e\");\ncards.add(\"card_thingy\");\n\ntry {\n LetterEditable letterEditable = new LetterEditable();\n letterEditable.setDescription(\"Demo Letter\");\n letterEditable.setFrom(\"adr_210a8d4b0b76d77b\");\n letterEditable.setFile(\"<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>\");\n letterEditable.setColor(true);\n letterEditable.setTo(to);\n letterEditable.setMergeVariables(merge_variables);\n letterEditable.setCards(cards);\n letterEditable.setUseType(\"operational\");\n letterEditable.setQRCode(qrCode);\n letterEditable.setFsc(true);\n letterEditable.setPrintSpeed(\"core\");\n\n Letter result = apiInstance.create(letterEditable, null);\n} catch (ApiException e) {\n e.printStackTrace();\n}\n"
label: JAVA
- lang: Elixir
source: "Lob.Letter.create(%{\n description: 'Demo Letter',\n to: %{\n name: 'Harry Zhang',\n address_line1: '210 King St',\n address_line2: '# 6100',\n address_city: 'San Francisco',\n address_state: 'CA',\n address_zip: '94107'\n },\n from: 'adr_210a8d4b0b76d77b',\n file: '<html style=\"padding-top: 3in; margin: .5in;\">HTML Letter for {{name}}</html>',\n merge_variables: %{\n name: 'Harry'\n },\n color: true,\n cards: ['card_c51ae96f5cebf3e'],\n use_type: 'marketing',\n qr_code: %{\n position: 'relative',\n redirect_url: 'https://www.lob.com',\n width: '2',\n bottom: '2',\n left: '2',\n pages: '1-2,5'\n },\n fsc: true,\n print_speed: 'core'\n})\n"
label: ELIXIR
- lang: CSharp
source: "Dictionary<string, string> mergeVariables = new Dictionary<string, string>();\nmergeVariables.Add(\"name\", \"Harry\");\n\nLettersApi api = new LettersApi(config);\n\nAddressEditable to = new AddressEditable(\n \"210 King St\", // addressLine1\n \"# 6100\", // addressLine2\n \"San Francisco\", // addressCity\n \"CA\", // addressState\n \"94107\", // addressZip\n default(CountryExtended), // addressCounty\n null, // description\n \"Harry Zhang\" // name\n);\n\nUseType usetype = new UseType(\"marketing\");\n\nQRCode qrCode = new QRCode(\n \"relative\", //position,\n \"https://www.lob.com\", //redirect_url\n \"2\", //width\n \"2\", //left\n \"2\", //bottom\n \"1-2,5\", //pages\n);\n\nFsc fsc = new Fsc(true);\nPrintSpeed printSpeed = new PrintSpeed(\"core\");\n\nList<String> cards = new List<String>();\ncards.Add(\"card_c51ae96f5cebf3e\");\n\nLetterEditable letterEditable = new LetterEditable(\n \"Demo Letter\", // description\n default(Dictionary<string, string>), // metadata\n default(MailType), // mailType\n mergeVariables, // mergeVariables\n default(DateTime), // sendDate\n true, // color\n true, // doubleSided\n LetterEditable.AddressPlacementEnum.TopFirstPage, // addressPlacement\n default(Object), // returnEnvelope\n default(int?), // perforatedPage\n default(LetterEditableCustomEnvelope), // customEnvelope\n to.ToJson(), // to\n \"adr_249af768103d2810\", // from\n \"<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>\", // file\n default(LetterEditable.ExtraServiceEnum?), // extraService\n cards, // cards\n usetype,\n qrCode,\n fsc,\n printSpeed\n);\n\ntry {\n Letter result = api.create(letterEditable, null);\n} catch (ApiException e) {\n Console.WriteLine(e.ToString());\n}\n"
label: CSHARP
- lang: Go
source: "var context = context.Background()\ncontext = context.WithValue(suite.ctx, lob.ContextBasicAuth, lob.BasicAuth{UserName: os.Getenv(\"<YOUR_API_KEY>\")})\n\nvar apiClient = *lob.NewAPIClient(configuration)\n\nvar to = *lob.NewAddressEditable()\nto.SetAddressLine1(\"210 King St\")\nto.SetAddressLine2(\"# 6100\")\nto.SetAddressCity(\"San Francisco\")\nto.SetAddressState(\"CA\")\nto.SetAddressZip(\"94107\")\nto.SetAddressCountry(lob.COUNTRYEXTENDED_US)\nto.SetDescription(\"\")\nto.SetName(\"Harry Zhang\")\n\nvar letterCreate = *lob.NewLetterEditable()\nletterCreate.SetDescription(\"Demo Letter\")\nletterCreate.SetFrom(\"adr_210a8d4b0b76d77b\")\nletterCreate.SetFile(\"<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>\")\nletterCreate.SetColor(\"true\")\nletterCreate.SetTo(to)\nletterCreate.SetFsc(true)\nletterCreate.SetPrintSpeed(\"core\")\n\ncreatedletter, _, err := apiClient.LettersApi.Create(context).LetterEditable(letterCreate).Execute()\n\nif err != nil {\n return err\n}\n"
label: GO
components:
schemas:
tmpl_id:
type: string
description: Unique identifier prefixed with `tmpl_`. ID of a saved [HTML template](#section/HTML-Templates).
pattern: ^tmpl_[a-zA-Z0-9]+$
error:
type: object
description: Lob uses RESTful HTTP response codes to indicate success or failure of an API request. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end.
required:
- error
properties:
error:
type: object
required:
- message
- status_code
- code
properties:
message:
type: string
description: A human-readable message with more details about the error
example: Rate limit exceeded. Please wait 5 seconds and try your request again.
status_code:
$ref: '#/components/schemas/failure_status_code'
code:
type: string
enum:
- bad_request
- conflict
- feature_limit_reached
- internal_server_error
- invalid
- not_deletable
- not_found
- request_timeout
- service_unavailable
- unrecognized_endpoint
- unsupported_lob_version
- address_length_exceeds_limit
- bank_account_already_verified
- bank_error
- billing_address_required
- custom_envelope_inventory_depleted
- deleted_bank_account
- failed_deliverability_strictness
- file_pages_below_min
- file_pages_exceed_max
- file_size_exceeds_limit
- foreign_return_address
- inconsistent_page_dimensions
- invalid_bank_account
- invalid_bank_account_verification
- invalid_check_international
- invalid_country_covid
- invalid_file
- invalid_file_dimensions
- invalid_file_download_time
- invalid_file_url
- invalid_image_dpi
- invalid_international_feature
- invalid_perforation_return_envelope
- invalid_template_html
- mail_use_type_can_not_be_null
- merge_variable_required
- merge_variable_whitespace
- payment_method_unverified
- pdf_encrypted
- special_characters_restricted
- unembedded_fonts
- email_required
- invalid_api_key
- publishable_key_not_allowed
- rate_limit_exceeded
- unauthorized
- unauthorized_token
description: 'A pre-defined string identifying an error. Error codes fall into three categories:
**GENERIC**
* `bad_request` - 422: an invalid request was made. See error message for details.
* `conflict` - 409/422: this operation would leave data in a conflicted state.
* `feature_limit_reached` - 403: the account has reached its resource limit and requires upgrading to add more.
* `internal_server_error` - 500: an error has occured on Lob''s servers. Please try request again.
* `invalid` - 422: an invalid request was made. See error message for details.
* `not_deletable` - 422: an attempt was made to delete a resource, but the resource cannot be deleted.
* `not_found` - 404: the requested resource was not found.
* `request_timeout` - 408: the request took too long. Please try again.
* `service_unavailable` - 503: the Lob servers are temporarily unavailable. Please try agian.
* `unrecognized_endpoint` - 404: the requested endpoint doesn''t exist.
* `unsupported_lob_version` - 422: an unsupported Lob API version was requested.
**ADVANCED**
* `address_length_exc
# --- truncated at 32 KB (133 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lobcom/refs/heads/main/openapi/lobcom-letters-api-openapi.yml