Lob 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 Letters API
version: 1.20.2
description: "Experience direct mail like never before, with unmatched personalization and scalability \x14 all in one intuitive platform."
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:
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
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
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
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"
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});\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}, 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});\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)\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\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 )\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\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})\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);\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);\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)\n\n\ncreatedletter, _, err := apiClient.LettersApi.Create(context).LetterEditable(letterCreate).Execute()\n\nif err != nil {\n return err\n}\n"
label: GO
components:
schemas:
date_created:
type: string
format: date-time
description: A timestamp in ISO 8601 format of the date the resource was created.
tracking_event_details:
type: object
required:
- event
- description
- action_required
properties:
event:
type: string
enum:
- package_accepted
- package_arrived
- package_departed
- package_processing
- package_processed
- package_in_local_area
- delivery_scheduled
- out_for_delivery
- pickup_available
- delivered
- package_forwarded
- returned_to_sender
- address_issue
- contact_carrier
- delayed
- delivery_attempted
- delivery_rescheduled
- location_inaccessible
- notice_left
- package_damaged
- package_disposed
- package_held
- package_lost
- package_unclaimed
- package_undeliverable
- reschedule_delivery
- other
description: 'Find the full table [here](#tag/Tracking-Events). A detailed substatus about the event:
* `package_accepted` - Package has been accepted into the carrier network for delivery.
* `package_arrived` - Package has arrived at an intermediate location in the carrier network.
* `package_departed` - Package has departed from an intermediate location in the carrier network.
* `package_processing` - Package is processing at an intermediate location in the carrier network.
* `package_processed` - Package has been processed at an intermediate location.
* `package_in_local_area` - Package is at a location near the end destination.
* `delivery_scheduled` - Package is scheduled for delivery.
* `out_for_delivery` - Package is out for delivery.
* `pickup_available` - Package is available for pickup at carrier location.
* `delivered` - Package has been delivered.
* `package_forwarded` - Package has been forwarded.
* `returned_to_sender` - Package is to be returned to sender.
* `address_issue` - Address information is incorrect. Contact carrier to ensure delivery.
* `contact_carrier` - Contact the carrier for more information.
* `delayed` - Delivery of package is delayed.
* `delivery_attempted` - Delivery of package has been attempted. Contact carrier to ensure delivery.
* `delivery_rescheduled` - Delivery of package has been rescheduled.
* `location_inaccessible` - Delivery location inaccessible to carrier. Contact carrier to ensure delivery.
* `notice_left` - Carrier left notice during attempted delivery. Follow carrier instructions on notice.
* `package_damaged` - Package has been damaged. Contact carrier for more details.
* `package_disposed` - Package has been disposed.
* `package_held` - Package held at carrier location. Contact carrier for more details.
* `package_lost` - Package has been lost. Contact carrier for more details.
* `package_unclaimed` - Package is unclaimed.
* `package_undeliverable` - Package is not able to be delivered.
* `reschedule_delivery` - Contact carrier to reschedule delivery.
* `other` - Unrecognized carrier status.
'
description:
type: string
description: The description as listed in the description for event.
notes:
type: string
description: Event-specific notes from USPS about the tracking event.
action_required:
type: boolean
description: '`true` if action is required by the end recipient, `false` otherwise.
'
adr_id:
type: string
description: Unique identifier prefixed with `adr_`.
pattern: ^adr_[a-zA-Z0-9]+$
letter:
oneOf:
- allOf:
- title: regular
- $ref: '#/components/schemas/no_extra_service'
- allOf:
- title: registered
- $ref: '#/components/schemas/registered'
- allOf:
- title: certified
- $ref: '#/components/schemas/certified'
send_date:
type: string
description: A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](#section/Cancellation-Windows) applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC.
anyOf:
- format: date-time
- format: date
country_extended:
type: string
description: Must be a 2 letter country short-name code (ISO 3166). Does not accept `US`, `AS`, `PR`, `FM`, `GU`, `MH`, `MP`, `PW`, or `VI`. For these addresses, please use the US verification API. Also does not accept `PS`, which is not currently supported.
enum:
- AD
- AE
- AF
- AG
- AI
- AL
- AN
- AO
- AQ
- AR
- AT
- AU
- AW
- AZ
- BA
- BB
- BD
- BE
- BF
- BG
- BH
- BI
- BJ
- BM
- BN
- BO
- BQ
- BR
- BS
- BT
- BW
- BY
- BZ
- CA
- CD
- CG
- CH
- CI
- CK
- CL
- CM
- CN
- CO
- CR
- CS
- CU
- CV
- CW
- CY
- CZ
- DE
- DJ
- DK
- DM
- DO
- DZ
- EC
- EE
- EG
- EH
- ER
- ES
- ET
- FI
- FJ
- FK
- FO
- FR
- GA
- GB
- GD
- GE
- GH
- GI
- GL
- GM
- GN
- GQ
- GR
- GS
- GT
- GW
- GY
- HK
- HN
- HR
- HT
- HU
- ID
- IE
- IL
- IN
- IO
- IQ
- IR
- IS
- IT
- JM
- JO
- JP
- KE
- KG
- KH
- KI
- KM
- KN
- KP
- KR
- KW
- KY
- KZ
- LA
- LB
- LC
- LI
- LK
- LR
- LS
- LT
- LU
- LV
- LY
- MA
- MC
- MD
- ME
- MG
- MK
- ML
- MM
- MN
- MO
- MR
- MS
- MT
- MU
- MV
- MW
- MX
- MY
- MZ
- NA
- NE
- NF
- NG
- NI
- NL
- 'NO'
- NP
- NR
- NU
- NZ
- OM
- PA
- PE
- PG
- PH
- PK
- PL
- PN
- PT
- PY
- QA
- RO
- RS
- RU
- RW
- SA
- SB
- SC
- SD
- SE
- SG
- SH
- SI
- SK
- SL
- SM
- SN
- SO
- SR
- SS
- ST
- SV
- SX
- SY
- SZ
- TC
- TD
- TG
- TH
- TJ
- TK
- TL
- TM
- TN
- TO
- TR
- TT
- TV
- TW
- TZ
- UA
- UG
- UY
- UZ
- VA
- VC
- VE
- VG
- VN
- VU
- WS
- YE
- ZA
- ZM
- ZW
failure_reason:
type: object
description: An object describing the reason for failure if the resource failed to render.
properties:
remediation:
type: string
description: Instructions on how to resolve the error
failure_reason:
type: string
description: Reason failure occurred
errors:
type: array
nullable: true
items:
$ref: '#/components/schemas/failure_reason_error'
address_editable_intl:
allOf:
- $ref: '#/components/schemas/address_fields_intl'
- type: object
anyOf:
- title: address obj with `name` defined
required:
- name
- title: address obj with `company` defined
required:
- company
properties:
description:
$ref: '#/components/schemas/resource_description'
name:
type: string
description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address.
'
maxLength: 40
nullable: true
company:
$ref: '#/components/schemas/company'
phone:
type: string
description: Must be no longer than 40 characters.
maxLength: 40
nullable: true
email:
type: string
description: Must be no longer than 100 characters.
maxLength: 100
nullable: true
address_country:
$ref: '#/components/schemas/country_extended'
metadata:
$ref: '#/components/schemas/metadata'
tracking_event_normal:
allOf:
- $ref: '#/components/schemas/tracking_event_base'
- type: object
required:
- type
- name
properties:
type:
description: non-Certified postcards, self mailers, letters, checks and snap packs
type: string
enum:
- normal
name:
type: string
enum:
- Mailed
- In Transit
- In Local Area
- Processed for Delivery
- Delivered
- Re-Routed
- Returned to Sender
- International Exit
description: "Name of tracking event (for normal postcards, self mailers, letters, checks and snap packs):\n\n * `Mailed` - The mailpiece has been handed off to and accepted by USPS\n a
# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lob/refs/heads/main/openapi/lob-letters-api-openapi.yml