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
OpenAPI Specification
openapi: 3.0.3
info:
title: Lob Accounts 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 test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:\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 test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:\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 test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:\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:
parameters:
metadata:
in: query
name: metadata
description: Filter by metadata key-value pair`.
schema:
$ref: '#/components/schemas/metadata'
style: deepObject
explode: true
idem-header:
in: header
name: Idempotency-Key
required: false
description: 'A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our <a href="https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12" target="_blank">implementation guide</a>.
'
schema:
type: string
maxLength: 256
example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5
status:
in: query
name: status
description: 'A string describing the render status:
* `processed` - the rendering process is currently underway.
* `rendered` - the rendering process has completed successfully.
* `failed` - the rendering process has failed.
'
schema:
$ref: '#/components/schemas/status'
send_date:
in: query
name: send_date
description: 'Filter by ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤.
'
schema:
$ref: '#/components/schemas/send_date'
date_created:
in: query
name: date_created
description: 'Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤.'
schema:
$ref: '#/components/schemas/date_filter'
style: deepObject
explode: true
idem-query:
in: query
name: idempotency_key
required: false
description: 'A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our <a href="https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12" target="_blank">implementation guide</a>.
'
schema:
type: string
maxLength: 256
example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5
include:
in: query
name: include
description: 'Request that the response include the total count by specifying `include=["total_count"]`.
'
schema:
type: array
items:
type: string
explode: true
campaign_id:
in: query
name: campaign_id
required: false
description: Filters resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`.
schema:
$ref: '#/components/schemas/campaign_id'
limit:
in: query
name: limit
required: false
description: How many results to return.
schema:
type: integer
minimum: 1
default: 10
maximum: 100
example: 10
lob-version:
in: header
name: Lob-Version
required: false
description: 'A string representing the version of the API being used. Specifically for letters, if this header is set to `2024-01-01` and above, the `size` property is automatically included with the default value of `us_letter`. Refer to `size` for all possible values. For more information on versioning, refer to our [Versioning and Changelog](#tag/Versioning-and-Changelog) documentation.
'
schema:
type: string
example: '2024-01-01'
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
scheduled:
in: query
name: scheduled
description: '* `true` - only return orders (past or future) where `send_date` is
greater than `date_created`
* `false` - only return orders where `send_date` is equal to `date_created`
'
# --- 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