Lob Letters API

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