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    and is en route. <a href=\"https://help.lob.com/print-and-mail/getting-data-and-results/tracking-your-mail#mailed-tracking-events-4\" target=\"_blank\">More about\n    Mailed.</a>\n    Note this data is only available in Enterprise editions of\n    Lob. <a href=\"https://lob.com/support/contact#contact\" target=\"_blank\">Contact Sales</a> if\n    you want access to this feature.\n\n  * `In Transit` - The mailpiece is being processed at the entry/origin facility.\n\n  * `In Local Area` - The mailpiece is being processed at the destination facility.\n\n  * `Processed for Delivery` - The mailpiece has been greenlit for\n    delivery at the recipient's nearest postal facility. The mailpiece\n    should reach the mailbox within 1 business day of this tracking\n    event.\n\n  * `Delivered` - The mail piece has been delivered to \n    the recipients address. The final scan is generated when the mail \n    carrier's GPS unit leaves the delivery area.\n\n  * `Re-Routed` - The mailpiece is re-routed due to recipient change of\n    address, address errors, or USPS relabeling of barcode/ID tag\n    area.\n\n  * `Returned to Sender` - The mailpiece is being returned to sender due\n    to barcode, ID tag area, or address errors.\n  \n  * `International Exit` - The mail piece has been processed to \n    ship to a destination abroad. This is typically the last \n    scan a US-originated international mail piece will receive \n    from the USPS.\n\n<a href=\"https://help.lob.com/print-and-mail/getting-data-and-results/tracking-your-mail#mailed-tracking-events-4\" target=\"_blank\">More about tracking</a>\n"
          details:
            description: Will be `null` for `type=normal` events
            type: object
            enum:
            - null
            nullable: true
          location:
            type: string
            description: 'The zip code in which the scan event occurred. Null for `Mailed` events.

              '
            nullable: true
    inline_address_us:
      allOf:
      - $ref: '#/components/schemas/address_editable_us'
      - type: object
        required:
        - address_line1
        - address_city
        - address_state
        - address_zip
    card_id:
      type: string
      description: Unique identifier prefixed with `card_`.
      pattern: ^card_[a-zA-Z0-9]+$
    address_placement:
      type: string
      enum:
      - top_first_page
      - insert_blank_page
      - bottom_first_page_center
      - bottom_first_page
      description: "Specifies the location of the address information that will show through the double-window envelope. To see how this will impact your letter design, view our letter template.\nSome values are exclusive to certain customers. Upgrade to the appropriate <a href=\"https://dashboard.lob.com/#/settings/editions\" target=\"_blank\">Print & Mail Edition</a> to gain access.\n  * `top_first_page` - (default) print address information at the top of your provided first page\n  * `insert_blank_page` - insert a blank address page at the beginning of your file (you will be charged for the extra page)\n  * `bottom_first_page_center` - **(exclusive, deprecation planned within a few months)** print address information at the bottom center of your provided first page\n  * `bottom_first_page` - **(exclusive)** print address information at the bottom of your provided first page\n"
      default: top_first_page
    address_intl:
      allOf:
      - $ref: '#/components/schemas/lob_base'
      - type: object
        required:
        - id
        - address_line1
        - address_country
        anyOf:
        - title: address obj with `name` defined
          required:
          - name
        - title: address obj with `company` defined
          required:
          - company
        properties:
          id:
            $ref: '#/components/schemas/adr_id'
          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
          metadata:
            $ref: '#/components/schemas/metadata'
          address_line1:
            type: string
            maxLength: 200
          address_line2:
            type: string
            maxLength: 200
            nullable: true
          address_city:
            type: string
            maxLength: 200
            nullable: true
          address_state:
            description: Will be returned as a full string
            type: string
            maxLength: 200
            nullable: true
          address_zip:
            type: string
            description: Optional postal code.
            maxLength: 40
            nullable: true
          address_country:
            description: Full name of country
            type: string
            maxLength: 200
            enum:
            - AFGHANISTAN
            - ALBANIA
            - ALGERIA
            - AMERICAN SAMOA
            - ANDORRA
            - ANGOLA
            - ANGUILLA
            - ANTARCTICA
            - ANTIGUA AND BARBUDA
            - ARGENTINA
            - ARUBA
            - AUSTRALIA
            - AUSTRIA
            - AZERBAIJAN
            - BAHRAIN
            - BANGLADESH
            - BARBADOS
            - BELARUS
            - BELGIUM
            - BELIZE
            - BENIN
            - BERMUDA
            - BHUTAN
            - BOLIVIA (PLURINATIONAL STATE OF)
            - BONAIRE, SAINT EUSTATIUS AND SABA
            - BOSNIA AND HERZEGOVINA
            - BOTSWANA
            - BRAZIL
            - BRITISH INDIAN OCEAN TERRITORY
            - BRITISH VIRGIN ISLANDS
            - BRUNEI DARUSSALAM
            - BULGARIA
            - BURKINA FASO
            - BURUNDI
            - CABO VERDE
            - CAMBODIA
            - CAMEROON
            - CANADA
            - CAYMAN ISLANDS
            - CENTRAL AFRICAN REPUBLIC
            - CHAD
            - CHILE
            - CHINA
            - COLOMBIA
            - COMOROS
            - CONGO
            - CONGO, DEMOCRATIC REPUBLIC OF THE
            - COOK ISLANDS
            - COSTA RICA
            - C�TE D'IVOIRE
            - CROATIA
            - CUBA
            - CURA�AO
            - CYPRUS
            - CZECH REPUBLIC
            - DENMARK
            - DJIBOUTI
            - DOMINICA
            - DOMINICAN REPUBLIC
            - ECUADOR
            - EGYPT
            - EL SALVADOR
            - EQUATORIAL GUINEA
            - ERITREA
            - ESTONIA
            - ESWATINI
            - ETHIOPIA
            - FALKLAND ISLANDS (MALVINAS)
            - FAROE ISLANDS
            - FIJI
            - FINLAND
            - FRANCE
            - GABON
            - GAMBIA
            - GEORGIA
            - GERMANY
            - GHANA
            - GIBRALTAR
            - GREECE
            - GREENLAND
            - GRENADA
            - GUATEMALA
            - GUINEA
            - GUINEA-BISSAU
            - GUYANA
            - HAITI
            - HOLY SEE
            - HONDURAS
            - HONG KONG
            - HUNGARY
            - ICELAND
            - INDIA
            - INDONESIA
            - IRAN (ISLAMIC REPUBLIC OF)
            - IRAQ
            - IRELAND
            - ISRAEL
            - ITALY
            - JAMAICA
            - JAPAN
            - JORDAN
            - KAZAKHSTAN
            - KENYA
            - KIRIBATI
            - KOREA (DEMOCRATIC PEOPLES REPUBLIC OF)
            - KOREA, REPUBLIC OF
            - KUWAIT
            - KYRGYZSTAN
            - LAO PEOPLES DEMOCRATIC REPUBLIC
            - LATVIA
            - LEBANON
            - LESOTHO
            - LIBERIA
            - LIBYA
            - LIECHTENSTEIN
            - LITHUANIA
            - LUXEMBOURG
            - MACAO
            - MACEDONIA
            - MADAGASCAR
            - MALAWI
            - MALAYSIA
            - MALDIVES
            - MALI
            - MALTA
            - MAURITANIA
            - MAURITIUS
            - MEXICO
            - MOLDOVA, REPUBLIC OF
            - MONACO
            - MONGOLIA
            - MONTENEGRO
            - MONTSERRAT
            - MOROCCO
            - MOZAMBIQUE
            - MYANMAR
            - NAMIBIA
            - NAURU
            - NEPAL
            - NETHERLAND ANTILLES
            - NETHERLANDS
            - NEW ZEALAND
            - NICARAGUA
            - NIGER
            - NIGERIA
            - NIUE
            - NORFOLK ISLAND
            - NORWAY
            - OMAN
            - PAKISTAN
            - PANAMA
            - PAPUA NEW GUINEA
            - PARAGUAY
            - PERU
            - PHILIPPINES
            - PITCAIRN
            - POLAND
            - PORTUGAL
            - QATAR
            - ROMANIA
            - RUSSIAN FEDERATION
            - RWANDA
            - SAINT HELENA
            - SAINT KITTS AND NEVIS
            - SAINT LUCIA
            - SAINT VINCENT AND THE GRENADINES
            - SAMOA
            - SAN MARINO
            - SAO TOME AND PRINCIPE
            - SAUDI ARABIA
            - SENEGAL
            - SERBIA
            - SEYCHELLES
            - SIERRA LEONE
            - SINGAPORE
            - SINT MAARTEN
            - SLOVAKIA
            - SLOVENIA
            - SOLOMON ISLANDS
            - SOMALIA
            - SOUTH AFRICA
            - SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS
            - SOUTH SUDAN
            - SPAIN
            - SRI LANKA
            - SUDAN
            - SURINAME
            - SWEDEN
            - SWITZERLAND
            - SYRIAN ARAB REPUBLIC
            - TAIWAN
            - TAJIKISTAN
            - TANZANIA
            - THAILAND
            - THE BAHAMAS
            - TIMOR-LESTE
            - TOGO
            - TOKELAU
            - TONGA
            - TRINIDAD AND TOBAGO
            - TUNISIA
            - TURKEY
            - TURKMENISTAN
            - TURKS AND CAICOS ISLANDS
            - TUVALU
            - UGANDA
            - UKRAINE
            - UNITED ARAB EMIRATES
            - UNITED KINGDOM
            - URUGUAY
            - UZBEKISTAN
            - VANUATU
            - VENEZUELA
            - VIET NAM
            - WESTERN SAHARA
            - YEMEN
            - ZAMBIA
            - ZIMBABWE
          object:
            type: string
            description: Value is resource type.
            enum:
            - address
            default: address
        example:
          id: adr_e68217bd744d65c8
          description: Harry - Office
          name: Harry Zhang
          company: Lob
          phone: '5555555555'
          email: harry@lob.com
          metadata: {}
          address_line1: 370 WATER ST
          address_line2: ''
          address_city: SUMMERSIDE
          address_state: PRINCE EDWARD ISLAND
          address_zip: C1N 1C4
          address_country: CANADA
    deleted:
      type: boolean
      description: Only returned if the resource has been successfully deleted.
    address_editable_us:
      allOf:
      - $ref: '#/components/schemas/address_fields_us'
      - 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:
            type: string
            enum:
            - US
            default: US
          metadata:
            $ref: '#/components/schemas/metadata'
    address:
      oneOf:
      - $ref: '#/components/schemas/address_us'
      - $ref: '#/components/schemas/address_intl'
    tracking_event_certified:
      allOf:
      - $ref: '#/components/schemas/tracking_event_base'
      - type: object
        required:
        - type
        - name
        properties:
          type:
            description: a Certified letter tracking event
            type: string
            enum:
            - certified
          name:
            type: string
            enum:
            - Mailed
            - In Transit
            - In Local Area
            - Processed for Delivery
            - Pickup Available
            - Delivered
            - Re-Routed
            - Returned to Sender
            - Issue
            description: "Name of tracking event for Certified letters. Letters sent with USPS Certified Mail are fully tracked by USPS, therefore their tracking events have an additional details object with more detailed information about the tracking event. Some certified tracking event names have multiple meanings, noted in the list here. See the description of the details object for the full set of combined certified tracking event name meanings.\n\n  * `Mailed` - Package has been accepted into the carrier network for delivery.\n\n  * `In Transit` - Maps to four distinct stages of transit.\n\n  * `In Local Area` - Package is at a location near the end destination.\n\n  * `Processed for Delivery` - Maps to two distinct stages of delivery.\n\n  * `Pickup Available` - Package is available for pickup at carrier location.\n\n  * `Delivered` - Package has been delivered.\n\n  * `Re-Routed` - Package has been forwarded.\n\n  * `Returned to Sender` - Package is to be returned to sender.\n\n  * `Issue` - Maps to (at least) 15 possible issues, some of which are actionable.\n"
          details:
            $ref: '#/components/schemas/tracking_event_details'
          location:
            type: string
            description: 'The zip code in which the event occurred if it exists, otherwise will be the name of a Regional Distribution Center if it exists, otherwise will be null.

              '
            nullable: true
    address_fields_us:
      type: object
      required:
      - address_line1
      - address_city
      - address_state
      - address_zip
      properties:
        address_line1:
          type: string
          description: The primary number, street name, and directional information.
          maxLength: 64
        address_line2:
          type: string
          description: An optional field containing any information which can't fit into line 1.
          maxLength: 64
          nullable: true
        address_city:
          type: string
          maxLength: 200
        address_state:
          type: string
          description: 2 letter state short-name code
          pattern: ^[a-zA-Z]{2}$
        address_zip:
          type: string
          description: 'Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234`.

            '
          pattern: ^\d{5}(-\d{4})?$
    card:
      allOf:
      - $ref: '#/components/schemas/lob_base'
      - $ref: '#/components/schemas/card_base'
      - required:
        - description
      - type: object
        required:
        - id
        - url
        - auto_reorder
        - reorder_quantity
        - raw_url
        - front_original_url
        - back_original_url
        - thumbnails
        - available_quantity
        - pending_quantity
        - status
        - orientation
        - threshold_amount
        - object
        properties:
          id:
            $ref: '#/components/schemas/card_id'
          url:
            description: The signed link for the card.
            maxLength: 2083
            minLength: 1
            type: string
            format: uri
          auto_reorder:
            description: True if the cards should be auto-reordered.
            type: boolean
            default: false
          reorder_quantity:
            description: The number of cards to be reordered.
            type: integer
            nullable: true
          raw_url:
            description: The raw URL of the card.
            maxLength: 2083
            minLength: 1
            type: string
            format: uri
          front_original_url:
            description: The original URL of the front template.
            maxLength: 2083
            minLength: 1
            type: string
            format: uri
          back_original_url:
            description: The original URL of the back template.
            maxLength: 2083
            minLength: 1
            type: string
            format: uri
          thumbnails:
            type: array
            items:
              $ref: '#/components/schemas/thumbnail'
          available_quantity:
            description: The available quantity of cards.
            type: integer
            default: 0
          pending_quantity:
            description: The pending quantity of cards.
            type: integer
            default: 0
          status:
            title: The status of the card.
            enum:
            - processed
            - rendered
            type: string
          orientation:
            description: The orientation of the card.
            enum:
            - horizontal
            - vertical
            type: string
            default: horizontal
          threshold_amount:
            description: The threshold amount of the card
            type: integer
            default: 0
          object:
            description: object
            enum:
            - card
            type: string
            default: card
    failure_reason_error:
      type: object
      description: Failure error details
      properties:
        url:
          type: string
          description: Failed URL of asset
          nullable: true
        host:
          type: string
          description: URL host
          nullable: true
        path:
          type: string
          description: URL path
          nullable: true
        protocol:
          type: string
          description: Network protocol
          nullable: true
        remediation:
          type: string
          description: Instructions on how to resolve the error
          nullable: true
        error_type:
          type: string
          description: HTTP response status code message or service defined error
          nullable: true
        status_code:
          type: number
          description: HTTP response status codes if the error is asset related
          nullable: true
    date_modified:
      type: string
      format: date-time
      description: A timestamp in ISO 8601 format of the date the resource was last modified.
    user_provided:
      type: string
      description: Accepts an envelope ID for any customized envelope with available inventory. If no inventory is available for the specified ID, the letter will not be sent, and an error will be returned. If the letter has more than 6 sheets, it will be sent in a blank flat envelope. Custom envelopes may be created and ordered from the dashboard. This feature is exclusive to certain customers. Upgrade to the appropriate <a href="https://dashboard.lob.com/#/settings/editions" target="_blank">Print & Mail Edition</a> to gain access.
      nullable: true
      pattern: ^env_[a-zA-Z0-9]+$
    input_to:
      type: object
      properties:
        to:
          description: 'Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Depending on your <a href="https://dashboard.lob.com/#/settings/editions" target="_blank">Print & Mail Edition</a>, US addresses may also be run through <a href="#tag/National-Change-of-Address">National Change of Address Linkage(NCOALink)</a>. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your accounts <a href="https://dashboard.lob.com/#/settings/account" target="_blank">US Mail strictness setting</a>, the request will fail. <a href="https://help.lob.com/print-and-mail/all-about-addresses" target="_blank">Lob Guide: Verification of Mailing Addresses</a>'
          oneOf:
          - $ref: '#/components/schemas/adr_id'
          - $ref: '#/components/schemas/inline_address'
    certified:
      allOf:
      - type: object
        required:
        - extra_service
        - tracking_events
        - color
        properties:
          extra_service:
            type: string
            enum:
            - certified
            - certified_return_receipt
            description: "Add an extra service to your letter. See <a href=\"https://www.lob.com/pricing/print-mail#compare\" target=\"_blank\">pricing</a> for extra costs incurred.\n  * `certified` - track and confirm delivery for domestic destinations. An extra sheet (1 PDF page single-sided or 2 PDF pages double-sided) is added to the beginning of your letter for address and barcode information. See here for templates: <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_certified_template.pdf\" target=\"_blank\">#10 envelope</a> and <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_certified_flat_template.pdf\" target=\"_blank\">flat envelope</a> (used for letters over 6 pages single-sided or 12 pages double-sided). You will not be charged for this extra sheet.\n  * `certified_return_receipt` - request an electronic copy of the recipient's signature to prove delivery of your certified letter\n"
          tracking_number:
            type: string
            description: 'The tracking number will be here immediately upon creation.

              Dummy tracking numbers are created in test mode.'
            nullable: true
          tracking_events:
            description: An array of certified tracking events ordered by ascending `time`. Not populated in test mode.
            type: array
            items:
              $ref: '#/components/schemas/tracking_event_certified'
          return_address:
            $ref: '#/components/schemas/return_address'
          description:
            $ref: '#/components/schemas/resource_description'
          metadata:
            $ref: '#/components/schemas/metadata'
          merge_variables:
            $ref: '#/components/schemas/merge_variables'
          send_date:
            $ref: '#/components/schemas/send_date'
          mail_type:
            $ref: '#/components/schemas/mail_type'
          color:
            $ref: '#/components/schemas/color'
          double_sided:
            $ref: '#/components/schemas/double_sided'
          address_placement:
            $ref: '#/components/schemas/address_placement'
          return_envelope:
            $ref: '#/components/schemas/return_envelope_returned'
          perforated_page:
            type: integer
            description: Required if `return_envelope` is `true`. The number of the page that should be perforated for use with the return envelope. Must be greater than or equal to `1`. The blank page added by `address_placement=insert_blank_page` will be ignored when considering the perforated page number. To see how perforation will impact your letter design, view our <a href="https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_perf_template.pdf" target="_blank">perforation guide</a>.
            nullable: true
          custom_envelope:
            $ref: '#/components/schemas/custom_envelope_returned'
      - $ref: '#/components/schemas/letter_generated_base'
    buckslip_order:
      allOf:
      - $ref: '#/components/schemas/lob_base'
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/bo_id'
          buckslip_id:
            $ref: '#/components/schemas/buckslip_id'
          status:
            description: The status of the buckslip order.
            enum:
            - pending
            - printing
            - available
            - cancelled
            - depleted
            type: string
          quantity_ordered:
            description: The quantity of buckslips ordered.
            type: number
            default: 0
          unit_price:
            description: The unit price for the buckslip order.
            type: number
            default: 0
          inventory:
            description: The inventory of the buckslip order.
            type: number
            default: 0
          cancelled_reason:
            description: The reason for cancellation.
            type: string
          availability_date:
            type: string
            format: date-time
            description: A timestamp in ISO 8601 format of the date the resource was created.
          expected_availability_date:
            type: string
            format: date-time
            description: The fixed deadline for the buckslips to be printed.
    ltr_file:
      description: 'Notes:

        - HTML merge variables should not include delimiting whitespace.

        - All pages of a supplied PDF file must be sized at 8.5"x11", while supplied HTML will be rendered and trimmed to as many 8.5"x11" pages as necessary.

        - For design specifications, please see our <a href="https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_template.pdf" target="_blank">PDF</a> and [HTML](#section/HTML-Examples) templates.

        - If a `custom_envelope` is used, follow <a href="https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_custom_envelope.pdf" target="_blank">this template</a>.

        - For domestic destinations, the file limit is 60 pages single-sided or 120 pages double-sided. For international destinations, the file limit is 6 pages single-sided or 12 pages double-sided. PDFs that surpass the file limit will error, while HTML that renders more pages than the file limit will be trimmed.

        - Any letters over 6 pages single-sided or 12 pages double-sided will be placed in a <a href="https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_flat_template.pdf" target="_blank">flat envelope</a> instead of the standard double window envelope.


        See <a href="https://lob.com/pricing/print-mail#compare" target="_blank">pricing</a> for extra costs incurred.'
      oneOf:
      - $ref: '#/components/schemas/html_string'
      - $ref: '#/components/schemas/tmpl_id'
      - $ref: '#/components/schemas/remote_file_url'
      - type: string
        pattern: ^(?!https://)[a-zA-Z0-9@:%._+~#=/]{1,256}.(html?|pdf)$
    remote_file_url:
      type: string
      description: 'The location of a remote file. Remote URLs have a 5 MB file size limit and must be downloaded within 40 seconds.

        '
      pattern: ^https://[-a-zA-Z0-9@:%._+~#=/]{1,256}.(html?|pdf|png|jpg)$
    ltr_id:
      type: string
      description: Unique identifier prefixed with `ltr_`.
      pattern: ^ltr_[a-zA-Z0-9]+$
    date_filter:
      type: object
      additionalProperties:
        type: string
      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 e, and `lte` is d.'
    from:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/address'
    address_us:
      allOf:
      - $ref: '#/components/schemas/lob_base'
      - type: object
        required:
        - id
        - address_line1
        - address_city
        - address_state
        - address_zip
        anyOf:
        - title: address obj with `name` defined
          required:
          - name
        - title: address obj with `company` defined
          required:
          - company
        properties:
          id:
            $ref: '#/components/schemas/adr_id'
          object:
            type: string
            description: Value is resource type.
            enum:
            - address
            default: address
          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:
            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. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc).

              '
            maxLength: 40
            nullable: true
          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_line1:
            type: string
            description: The primary number, street name, and directional information.
            maxLength: 64
          address_line2:
            type: string
            description: An optional field containing any information which can't fit into line 1.
            maxLength: 64
            nullable: true
          address_city:
            type: string
            maxLength: 200
          address_state:
            type: string
            description: 2 letter state short-name code
            pattern: ^[a-zA-Z]{2}$
          address_zip:
            type: string
            description: 'Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234`.

              '
            pattern: ^\d{5}(-\d{4})?$
          address_country:
            type: string
            enum:
            - UNITED STATES
            description: Full name of country
            minLength: 13
            maxLength: 13
          metadata:
            $ref: '#/components/schemas/metadata'
          recipient_moved:
            type: boolean
            description: 'Only returned for accounts on certain <a href="https://dashboard.lob.com/#/settings/editions" target="_blank">Print &amp; Mail Editions</a>. Value is `true` if the address was altered because the recipient filed for a <a href="#tag/National-Change-of-Address">National Change of Address Linkage (NCOALink)</a>, `false` if the NCOALink check was run but no altered address was found, and `null` if the NCOALink check was not run. The NCOALink check does not happen for non-US addresses, for non-deliverable US addresses, or for addresses created before the NCOALink feature was added to your account.

              '
            nullable: true
        example:
          id: adr_e68217bd744d65c8
          description: Harry - Office
          name: HARRY ZHANG
          company: LOB
          phone: '5555555555'
          email: harry@lob.com
          address_line1: 210 KING ST STE 6100
          address_line2: null
          address_city: SAN FRANCISCO
          address_state: CA
          address_zip: 94107-1741
          address_country: UNITED STATES
          metadata: {}
          recipient_moved: false
          date_created: '2019-08-12T00:16:00.361Z'
          date_modified: '2019-08-12T00:16:00.361Z'
          object: address
    extra_service:
      type: string
      enum:
      - certified
      - certified_return_receipt
      - registered
      - null
      description: "Add an extra service to your letter. Can only be non-`null` if `mail_type` isn't `usps_standard`. See <a href=\"https://www.lob.com/pricing/print-mail#compare\" target=\"_blank\">pricing</a> for extra costs incurred.\n  * `certified` - track and confirm delivery for domestic destinations. An extra sheet (1 PDF page single-sided or 2 PDF pages double-sided) is added to the beginning of your letter for address and barcode information. See here for templates: <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_certified_template.pdf\" target=\"_blank\">#10 envelope</a> and <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_certified_flat_template.pdf\" target=\"_blank\">flat envelope</a> (used for letters over 6 pages single-sided or 12 pages double-sided). You will not be charged for this extra sheet.\n  * `certified_return_receipt` - request an electronic copy of the recipient's signature to prove delivery of your certified letter\n  * `registered` - provides tracking and confirmation for international addresses\n  \nNot available for `us_legal` letter size.\n"
      nullable: true
    buckslip_base:
      type: object
      properties:
        description:
          $ref: '#/components/schemas/buckslip_description'
        size:
          description: The size of the buckslip
          enum:
          - 8.75x3.75
          type: string
          default: 8.75x3.75
    thumbnail:
      type: object
      properties:
        small:
          $ref: '#/components/schemas/signed_link'
        medium:
          $ref: '#/components/schemas/signed_link'
        large:
          $ref: '#/components/schemas/signed_link'
    billing_group_id:
      type: string
      description: An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See <a href="#tag/Billing-Groups">Billing Group API</a> for more information.
    evnt_id:
      type: string
      description: Unique identifier prefixed with `evnt_`.
      pattern: ^evnt_[a-zA-Z0-9]+$
    mail_type:
      type: string
      enum:
      - usps_first_class
      - usps_standard
      description: 'A string designating the mail postage type:

        * `usps_first_class` - (default)

        * `usps_standard` - a <a href="https://lob.com/pricing/print-mail#compare" target="_blank">cheaper option</a> which is

        less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6`

        postcards or for any postcards sent outside of the United States.

        '
      default: usps_first_class
    ltr_use_type:
      description: The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our  [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type).
      type: string
      enum:
      - marketing
      - operational
      - null
      nullable: true
    generated:
      type: object
      required:
      - to
      - carrier
      properties:
        to:
          $ref: '#/components/schemas/address'
        carrier:
          type: string
          enum:
          - USPS
          default: USPS
        thumbnails:
          type: array
          items:
            $ref: '#/components/schemas/thumbnail'
        expected_delivery_date:
          $ref: '#/components/schemas/expected_delivery_date'
        date_created:
          $ref: '#/components/schemas/date_created'
        date_modified:
          $ref: '#/components/schemas/date_modified'
        deleted:
          $ref: '#/components/schemas/deleted'
    metadata:
      type: object
      additionalProperties:
        type: string
      description: 'Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. ''{"customer_id" : "NEWYORK2015"}'' Nested objects are not supported.  See [Metadata](#section/Metadata) for more information.'
      maxLength: 500
      pattern: '[^"\\]{0,500}'
    buckslip_description:
      type: string
      description: Description of the buckslip.
      maxLength: 255
      nullable: true
    object:
      type: string
      description: Value is resource type.
    buckslip_id:
      type: string
      description: Unique identifier prefixed with `bck_`.
      pattern: ^bck_[a-zA-Z0-9]+$
    buckslip:
      allOf:
      - $ref: '#/components/schemas/lob_base'
      - $ref: '#/components/schemas/buckslip_base'
      - required:
        - description
      - type: object
        required:
        - id
        - auto_reorder
        - reorder_quantity
        - threshold_amount
        - url
        - raw_url
        - front_original_url
        - back_original_url
        - thumbnails
        - available_quantity
        - allocated_quantity
        - onhand_quantity
        - pending_quantity
        - projected_quantity
        - buckslip_orders
        - stock
        - weight
        - finish
        - status
        - object
        properties:
          id:
            $ref: '#/components/schemas/buckslip_id'
          auto_reorder:
            description: True if the buckslips should be auto-reordered.
            type: boolean
            default: false
          reorder_quantity:
            description: The number of buckslips to be reordered.
            type: integer
            nullable: true
          threshold_amount:
            description: The threshold amount of the buckslip
            type: integer
            default: 0
          url:
            description: The signed link for the buckslip.
            maxLength: 2083
            minLength: 1
            type: string
            format: uri
          raw_url:
            description: The raw URL of the buckslip.
            maxLength: 2083
            minLength: 1
            type: string
            format: uri
          front_original_url:
            description: The original URL of the front template.
            maxLength: 2083
            minLength: 1
            type: string
            format: uri
          back_original_url:
            description: The original URL of the back template.
            maxLength: 2083
            minLength: 1
            type: string
            format: uri
          thumbnails:
            type: array
            items:
              $ref: '#/components/schemas/thumbnail'
          available_quantity:
            description: The available quantity of buckslips.
            type: number
            default: 0
          allocated_quantity:
            description: The allocated quantity of buckslips.
            type: number
            default: 0
          onhand_quantity:
            description: The onhand quantity of buckslips.
            type: number
            default: 0
          pending_quantity:
            description: The pending quantity of buckslips.
            type: number
            default: 0
          projected_quantity:
            description: The sum of pending and onhand quantities of buckslips.
            type: number
            default: 0
          buckslip_orders:
            description: An array of buckslip orders that are associated with the buckslip.
            type: array
            items:
              $ref: '#/components/schemas/buckslip_order'
            minItems: 0
          stock:
            title: The stock of the buckslip.
            enum:
            - text
            - cover
            type: string
          weight:
            title: The weight of the buckslip.
            enum:
            - 80#
            type: string
          finish:
            title: The finish of the buckslip.
            enum:
            - gloss
            - matte
            type: string
          status:
            title: The status of the buckslip.
            enum:
            - processed
            - rendered
            - failed
            type: string
          object:
            description: object
            enum:
            - buckslip
            type: string
            default: buckslip
    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_exceeds_limit` - 422: the sum of to.address_line1 and to.address_line2 cannot surpass 50 characters.

                * `bank_account_already_verified` - 422: the bank account has already been verified.

                * `bank_error` - 422: there''s an issue with the bank account.

                * `billing_address_required` - 403: in order to create a live mail piece, your account needs to set up a billing address.

                * `custom_envelope_inventory_depleted` - 422: custom envelope inventory is depleted, and more will need to be ordered.

                * `deleted_bank_account` - 404: checks cannot be created with a deleted bank account.

                * `failed_deliverability_strictness` - 422: the `to` address doesn''t meet strictness requirements. See <a href="https://dashboard.lob.com/#/settings/account" target="_blank">Account Settings</a> to configure strictness.

                * `file_pages_below_min` - 422: not enough pages.

                * `file_pages_exceed_max` - 422: too many pages.

                * `file_size_exceeds_limit` - 422: the file size is too large. See description for details.

                * `foreign_return_address` - 422: the `from` address must be a US address.

                * `inconsistent_page_dimensions` - 422: all pages of the input file must have the same dimensions.

                * `invalid_bank_account` - 422: the provided bank routing number is invalid.

                * `invalid_bank_account_verification` - 422: verification amounts do not match.

                * `invalid_check_international` - 422: checks cannot be sent internationally.

                * `invalid_country_covid` - 422: the postal service in the specified country is currently unable to process the request due to COVID-19 restrictions.

                * `invalid_file` - 422: the file is invalid.

                * `invalid_file_dimensions` - 422: file dimensions are incorrect for the selected mail type.

                * `invalid_file_download_time` - 422: file download from remote server took too long.

                * `invalid_file_url` - 422: the file URL when creating a resource is invalid.

                * `invalid_image_dpi` - 422: DPI must be at least 300.

                * `invalid_international_feature` - 422: the specified product cannot be sent to the destination.

                * `invalid_perforation_return_envelope` - 422: both `return_envelope` and `perforation` must be used together.

                * `invalid_template_html` - 422: the provided HTML is invalid.

                * `mail_use_type_can_not_be_null` - 422: use_type must be one of "marketing" or "operational". Alternatively, an admin can set the account default use type in Account Settings.

                * `merge_variable_required` - 422: a required merge variable is missing.

                * `merge_variable_whitespace` - 422: merge variable names cannot contain whitespace.

                * `payment_method_unverified` - 401: you must have a verified bank account or credit card to submit live requests.

                * `pdf_encrypted` - 422: an encrypted PDF was provided.

                * `special_characters_restricted` - 422: cannot use special characters for merge variable names.

                * `unembedded_fonts` - 422: the provided PDF contains non-standard unembedded fonts. See description for details.


                **AUTHENTICATION**

                * `email_required` - 401: account must have a verified email address before creating live resources.

                * `invalid_api_key` - 401/403: the API key is invalid.

                * `publishable_key_not_allowed` - 403: the requested operation needs a secret key, not a publishable key. See [API Keys](#section/API-Keys) for more information.

                * `rate_limit_exceeded` - 429: requests were sent too quickly and must be slowed down.

                * `unauthorized` - 401: the request isn''t authorized.

                * `unauthorized_token` - 401: token isn''t authorized.

                '
    count:
      type: integer
      description: number of resources in a set
    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]+$
    campaign_id:
      title: campaign_id
      description: Denotes 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_`.
      type: string
      pattern: ^(cmp|camp)_[a-zA-Z0-9]+$
      nullable: true
    registered:
      allOf:
      - type: object
        required:
        - extra_service
        - color
        properties:
          extra_service:
            type: string
            enum:
            - registered
            description: "Add an extra service to your letter. See <a href=\"https://www.lob.com/pricing/print-mail#compare\" target=\"_blank\">pricing</a> for extra costs incurred.\n  * registered - provides tracking and confirmation for international addresses\n"
          tracking_number:
            type: string
            description: 'The tracking number will appear here when it becomes available.

              Dummy tracking numbers are not created in test mode.'
            nullable: true
          tracking_events:
            description: Tracking events are not populated for registered letters.
            type: array
            items:
              $ref: '#/components/schemas/tracking_event_normal'
            maxItems: 0
          return_address:
            $ref: '#/components/schemas/return_address'
          description:
            $ref: '#/components/schemas/resource_description'
          metadata:
            $ref: '#/components/schemas/metadata'
          merge_variables:
            $ref: '#/components/schemas/merge_variables'
          send_date:
            $ref: '#/components/schemas/send_date'
          mail_type:
            $ref: '#/components/schemas/mail_type'
          color:
            $ref: '#/components/schemas/color'
          double_sided:
            $ref: '#/components/schemas/double_sided'
          address_placement:
            $ref: '#/components/schemas/address_placement'
          return_envelope:
            $ref: '#/components/schemas/return_envelope_returned'
          perforated_page:
            type: integer
            description: Required if `return_envelope` is `true`. The number of the page that should be perforated for use with the return envelope. Must be greater than or equal to `1`. The blank page added by `address_placement=insert_blank_page` will be ignored when considering the perforated page number. To see how perforation will impact your letter design, view our <a href="https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_perf_template.pdf" target="_blank">perforation guide</a>.
            nullable: true
          custom_envelope:
            $ref: '#/components/schemas/custom_envelope_returned'
      - $ref: '#/components/schemas/letter_generated_base'
    return_envelope_user_provided:
      oneOf:
      - type: boolean
      - type: string
      description: 'Indicates if a return envelope is requested for the letter. The value corresponding to this field is by default a boolean. But if the account is signed up for custom return envelopes, the value is of type string and is `no_9_single_window` for a standard return envelope and a custom `return_envelope_id` for non-standard return envelopes.


        To include a return envelope with your letter, set to `true` and specify the `perforated_page`. See <a href="https://www.lob.com/pricing/print-mail#compare" target="_blank">pricing</a> for extra costs incurred.'
      default: false
    bo_id:
      type: string
      description: Unique identifier prefixed with `bo_`.
      pattern: ^bo_[a-zA-Z0-9]+$
    input_from:
      type: object
      properties:
        from:
          description: Must either be an address ID or an inline object with correct address parameters. Must be a US address unless using a `custom_envelope`. All addresses will be standardized into uppercase without being modified by verification.
          oneOf:
          - $ref: '#/components/schemas/adr_id'
          - $ref: '#/components/schemas/inline_address'
    card_description:
      type: string
      description: Description of the card.
      maxLength: 255
      nullable: true
    vrsn_id:
      type: string
      description: Unique identifier prefixed with `vrsn_`.
      pattern: ^vrsn_[a-zA-Z0-9]+$
    qr_code:
      type: object
      description: Customize and place a QR code on the creative at the required position.
      required:
      - position
      - redirect_url
      - width
      properties:
        position:
          type: string
          enum:
          - relative
          description: Sets how a QR code is being positioned in the document. Together with this, you should provide one of 'top' or 'bottom', and one of 'left' or 'right'.
        top:
          type: number
          description: Vertical distance (in inches) to place QR code from the top. Only allowed if "bottom" isn't provided.
        right:
          type: number
          description: Horizontal distance (in inches) to place QR code from the right. Only allowed if "left" isn't provided.
        left:
          type: number
          description: Horizontal distance (in inches) to place QR code from the left. Only allowed if "right" isn't provided.
        bottom:
          type: number
          description: Vertical distance (in inches) to place QR code from the bottom. Only allowed if "top" isn't provided.
        redirect_url:
          type: string
          description: The url to redirect the user when a QR code is scanned. The URL can be a literal URL, a template URL containing merge variables, or consist entirely of merge variables. For example, `https://www.example.com` or `https://www.example.com?q={{name}}` or `{{name}}`, respectively. When a merge variable exists in the URL, it is replaced with data from merge_variables. If the variable does not exist, then nothing with be replaced and the destination URL will be the same as the input URL. More details on merge variables can be found in <a href="https://help.lob.com/print-and-mail/designing-mail-creatives/adding-qr-codes#destination-url-and-redirects" target="_blank">our help center</a>.
        width:
          type: number
          description: The size (in inches) of the QR code with a minimum of 1 inch. All QR codes are generated as a square.
        pages:
          type: string
          description: Specify the pages where the QR code should be stamped in a comma separated format. Your QR code can be printed in the same position on multiple pages. For postcards, the values should either be "front", "back" (for either front or back) or "front,back" (for the QR code to be printed on both sides). For self-mailers and snap packs, the values should either be "inside", "outside" (for either inside or outside) or "inside,outside" (for the QR code to be printed on both sides). For letters and booklets, the values can be specific page numbers ("1", "3"), page number ranges such as "1-3", or a comma separated combination of both ("1,3,5-7").
        logo:
          type: object
          description: Allows specifying a logo to be placed over the center of the QR code.  Logos must be in PNG or JPEG format and have a maximum file size of 1 MB.
          properties:
            url:
              type: string
              description: The public URL of the logo image to be retrieved and placed over the center of the QR code.
              pattern: ^https://[-a-zA-Z0-9@:%._+~#=/]{1,256}.(png|jpe?g)$
        style:
          type: object
          description: Customizes the appearance of the QR code.
          properties:
            background_color:
              type: string
              description: The background color of the QR code in hexadecimal format. For example, `#000000` is black and `#FFFFFF` is white.
              pattern: ^#[A-Fa-f0-9]{6}$
            foreground_color:
              type: string
              description: The foreground color of the QR code in hexadecimal format. For example, `#000000` is black and `#FFFFFF` is white.
              pattern: ^#[A-Fa-f0-9]{6}$
    resource_description:
      type: string
      description: 'An internal description that identifies this resource. Must be no longer than 255 characters.

        '
      maxLength: 255
      nullable: true
    letter_editable:
      allOf:
      - $ref: '#/components/schemas/input_to'
      - $ref: '#/components/schemas/input_from'
      - $ref: '#/components/schemas/editable'
      - type: object
        required:
        - to
        - from
        - file
        - color
        - use_type
        properties:
          file:
            $ref: '#/components/schemas/ltr_file'
          extra_service:
            $ref: '#/components/schemas/extra_service'
          cards:
            description: A single-element array containing an existing card id in a string format. See [cards](#tag/Cards) for more information. Not available for `us_legal` letter size.
            type: array
            items:
              $ref: '#/components/schemas/card_id'
            minItems: 0
            maxItems: 1
            nullable: true
          mail_type:
            $ref: '#/components/schemas/mail_type'
          color:
            allOf:
            - $ref: '#/components/schemas/color'
            - default: false
          double_sided:
            $ref: '#/components/schemas/double_sided'
          address_placement:
            $ref: '#/components/schemas/address_placement'
          return_envelope:
            $ref: '#/components/schemas/return_envelope_user_provided'
          perforated_page:
            type: integer
            description: Required if `return_envelope` is `true`. The number of the page that should be perforated for use with the return envelope. Must be greater than or equal to `1`. The blank page added by `address_placement=insert_blank_page` will be ignored when considering the perforated page number. To see how perforation will impact your letter design, view our <a href="https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_perf_template.pdf" target="_blank">perforation guide</a>.
            nullable: true
          custom_envelope:
            $ref: '#/components/schemas/user_provided'
          billing_group_id:
            $ref: '#/components/schemas/billing_group_id'
          qr_code:
            $ref: '#/components/schemas/qr_code'
          use_type:
            $ref: '#/components/schemas/ltr_use_type'
          fsc:
            type: boolean
            description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `A4` and `us_legal` letter size.
            default: false
          size:
            $ref: '#/components/schemas/ltr_size'
    tracking_event_base:
      type: object
      description: As mail pieces travel through the mail stream, USPS scans their unique barcodes, and Lob processes these mail scans to generate tracking events.
      required:
      - id
      - date_created
      - date_modified
      - object
      properties:
        id:
          $ref: '#/components/schemas/evnt_id'
        time:
          type: string
          format: date-time
          description: A timestamp in ISO 8601 format of the date USPS registered the event.
        date_created:
          $ref: '#/components/schemas/date_created'
        date_modified:
          $ref: '#/components/schemas/date_modified'
        object:
          allOf:
          - $ref: '#/components/schemas/object'
          - type: string
            enum:
            - tracking_event
            default: tracking_event
    failure_status_code:
      type: integer
      enum:
      - 401
      - 403
      - 404
      - 413
      - 422
      - 429
      - 500
      description: "A conventional HTTP status code:\n  * `401` - Authorization error with your API key or account\n  * `403` - Forbidden error with your API key or account\n  * `404` - The requested item does not exist\n  * `413` - Payload too large\n  * `422` - The query or body parameters did not pass validation\n  * `429` - Too many requests have been sent with an API key in a given amount of time\n  * `500` - An internal server error occurred, please contact support@lob.com\n"
    status:
      type: string
      enum:
      - processed
      - rendered
      - failed
      description: 'A string describing the PDF render status:

        * `processed` - the rendering process is currently in progress.

        * `rendered` - a PDF has been successfully rendered of the mailpiece.

        * `failed` - one or more issues has caused the rendering process to fail.

        '
    card_base:
      type: object
      properties:
        description:
          $ref: '#/components/schemas/card_description'
        size:
          description: The size of the card
          enum:
          - 3.375x2.125
          - 2.125x3.375
          type: string
          default: 2.125x3.375
    list:
      type: object
      description: Multiple items returned in order
      properties:
        object:
          $ref: '#/components/schemas/object'
        next_url:
          type: string
          description: Url of next page of items in list.
          nullable: true
        previous_url:
          type: string
          description: Url of previous page of items in list.
          nullable: true
        count:
          $ref: '#/components/schemas/count'
        total_count:
          type: integer
          description: Indicates the total number of records. Provided when the request specifies an "include" query parameter
    custom_envelope_returned:
      type: object
      description: A nested custom envelope object containing more information about the custom envelope used or `null` if a custom envelope was not used.
      required:
      - id
      - url
      - object
      properties:
        id:
          type: string
          description: The unique identifier of the custom envelope used.
          maxLength: 40
        url:
          type: string
          description: The url of the envelope asset used.
        object:
          type: string
          enum:
          - envelope
          default: envelope
      nullable: true
    return_envelope_returned:
      oneOf:
      - type: boolean
      - type: object
      properties:
        id:
          type: string
          description: The unique ID of the Return Envelope.
        alias:
          type: string
          description: A quick reference name for the Return Envelope.
        url:
          type: string
          description: The url of the return envelope.
        object:
          type: string
          description: Value is resource type.
    signed_link:
      type: string
      description: A [signed link](#section/Asset-URLs) served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated.
      pattern: ^https://lob-assets.com/(letters|postcards|bank-accounts|checks|self-mailers|cards|order-creatives)/([a-z]{3,4}_[a-z0-9]{15,16}|[a-z]{3}_[a-z0-9]{26}_[a-z]{4}_[a-z0-9]{26})('|_signature)(.pdf|_thumb_[a-z]+_[0-9]+.png|.png)?(version=[a-z0-9]*&)expires=[0-9]{10}&signature=[a-zA-Z0-9-_]+
    company:
      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. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc).

        '
      maxLength: 40
      nullable: true
    ltr_size:
      type: string
      enum:
      - us_letter
      - us_legal
      description: 'Specifies the size of the letter. It accepts two values `us_letter` and `us_legal`. If the [Lob-Version header](#tag/Versioning-and-Changelog) in the request is set to `2024-01-01` and above, the `size` property is automatically included with the default value of `us_letter`, unless explicitly specified.


        Please note that attempting to include the `size` property in the request with the `Lob-Version` header predating to `2024-01-01` will result in an error.

        '
      default: us_letter
    letter_generated_base:
      allOf:
      - $ref: '#/components/schemas/generated'
      - $ref: '#/components/schemas/from'
      - type: object
        required:
        - id
        - from
        - use_type
        properties:
          url:
            $ref: '#/components/schemas/signed_link'
          id:
            $ref: '#/components/schemas/ltr_id'
          template_id:
            allOf:
            - description: The unique ID of the HTML template used for the letter.
            - $ref: '#/components/schemas/tmpl_id'
          template_version_id:
            allOf:
            - description: The unique ID of the specific version of the HTML template used for the letter.
              type: string
            - $ref: '#/components/schemas/vrsn_id'
          campaign_id:
            $ref: '#/components/schemas/campaign_id'
          use_type:
            $ref: '#/components/schemas/ltr_use_type'
          fsc:
            type: boolean
            description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `A4` letter size.
            default: false
          status:
            $ref: '#/components/schemas/status'
          failure_reason:
            allOf:
            - $ref: '#/components/schemas/failure_reason'
            - nullable: true
          object:
            type: string
            description: Value is resource type.
            enum:
            - letter
            default: letter
    color:
      type: boolean
      description: Set this key to `true` if you would like to print in color. Set to `false` if you would like to print in black and white.
    no_extra_service:
      allOf:
      - type: object
        required:
        - color
        properties:
          tracking_events:
            description: An array of tracking events ordered by ascending `time`.
            type: array
            items:
              $ref: '#/components/schemas/tracking_event_normal'
          cards:
            description: An array of cards associated with a specific letter
            type: array
            items:
              $ref: '#/components/schemas/card'
            nullable: true
          buckslips:
            description: An array of buckslip(s) associated with a specific letter
            type: array
            items:
              $ref: '#/components/schemas/buckslip'
            nullable: true
          return_address:
            $ref: '#/components/schemas/return_address'
          description:
            $ref: '#/components/schemas/resource_description'
          metadata:
            $ref: '#/components/schemas/metadata'
          merge_variables:
            $ref: '#/components/schemas/merge_variables'
          send_date:
            $ref: '#/components/schemas/send_date'
          mail_type:
            $ref: '#/components/schemas/mail_type'
          color:
            $ref: '#/components/schemas/color'
          double_sided:
            $ref: '#/components/schemas/double_sided'
          address_placement:
            $ref: '#/components/schemas/address_placement'
          return_envelope:
            $ref: '#/components/schemas/return_envelope_returned'
          perforated_page:
            type: integer
            description: Required if `return_envelope` is `true`. The number of the page that should be perforated for use with the return envelope. Must be greater than or equal to `1`. The blank page added by `address_placement=insert_blank_page` will be ignored when considering the perforated page number. To see how perforation will impact your letter design, view our <a href="https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_perf_template.pdf" target="_blank">perforation guide</a>.
            nullable: true
          custom_envelope:
            $ref: '#/components/schemas/custom_envelope_returned'
      - $ref: '#/components/schemas/letter_generated_base'
    editable:
      type: object
      properties:
        description:
          $ref: '#/components/schemas/resource_description'
        metadata:
          $ref: '#/components/schemas/metadata'
        mail_type:
          $ref: '#/components/schemas/mail_type'
        merge_variables:
          $ref: '#/components/schemas/merge_variables'
        send_date:
          $ref: '#/components/schemas/send_date'
    double_sided:
      type: boolean
      description: Set this attribute to `true` for double sided printing, or `false` for for single sided printing. Defaults to `true`.
      default: true
    html_string:
      type: string
      description: An HTML string of under 10,000 characters.
      maxLength: 10000
      pattern: <
    inline_address_intl:
      allOf:
      - $ref: '#/components/schemas/address_editable_intl'
      - type: object
        required:
        - address_line1
        - address_country
      - type: object
        oneOf:
        - required:
          - address_city
          - address_state
        - required:
          - address_zip
    address_fields_intl:
      type: object
      required:
      - address_line1
      - address_country
      properties:
        address_line1:
          type: string
          description: The primary number, street name, and directional information.
          maxLength: 200
        address_line2:
          type: string
          description: An optional field containing any information which can't fit into line 1.
          maxLength: 200
          nullable: true
        address_city:
          type: string
          maxLength: 200
          nullable: true
        address_state:
          type: string
          maxLength: 200
          nullable: true
        address_zip:
          type: string
          description: Optional postal code.
          maxLength: 40
          nullable: true
    lob_base:
      type: object
      required:
      - date_created
      - date_modified
      - object
      properties:
        date_created:
          $ref: '#/components/schemas/date_created'
        date_modified:
          $ref: '#/components/schemas/date_modified'
        deleted:
          $ref: '#/components/schemas/deleted'
        object:
          $ref: '#/components/schemas/object'
    merge_variables:
      type: object
      description: 'You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `''`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `|`, `}`, `~`. More instructions can be found in <a href="https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10" target="_blank">our guide to using html and merge variables</a>. Depending on your <a href="https://dashboard.lob.com/#/settings/account" target="_blank">Merge Variable strictness</a> setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs.'
      maxLength: 25000
      nullable: true
    expected_delivery_date:
      type: string
      description: A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`.
      format: date
    return_address:
      description: Specifies the address the return envelope will be sent back to. This is an optional argument that is available if an account is signed up for the return envelope tracking beta, and has `return_envelope`, and `perforated_page` fields populated in the API request.
      oneOf:
      - $ref: '#/components/schemas/adr_id'
      - $ref: '#/components/schemas/inline_address'
    inline_address:
      oneOf:
      - $ref: '#/components/schemas/inline_address_us'
      - $ref: '#/components/schemas/inline_address_intl'
  parameters:
    metadata:
      in: query
      name: metadata
      description: Filter by metadata key-value pair`.
      schema:
        $ref: '#/components/schemas/metadata'
      style: deepObject
      explode: true
    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 e, and `lte` is d.'
      schema:
        $ref: '#/components/schemas/date_filter'
      style: deepObject
      explode: true
    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 e, and `lte` is d.

        '
      schema:
        $ref: '#/components/schemas/send_date'
    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}$
    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
    sort_by:
      in: query
      name: sort_by
      description: 'Sorts items by ascending or descending dates. Use either `date_created` or `send_date`, not both.

        '
      schema:
        allOf:
        - type: object
          properties:
            date_created:
              type: string
              enum:
              - asc
              - desc
            send_date:
              type: string
              enum:
              - asc
              - desc
        - oneOf:
          - required:
            - date_created
          - required:
            - send_date
    before_after:
      in: query
      name: before/after
      required: false
      description: '`before` and `after` are both optional but only one of them can be in the query at a time.

        '
      schema:
        allOf:
        - type: object
          properties:
            before:
              type: string
              description: 'A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the `previous_url` field in the return response.

                '
            after:
              type: string
              description: 'A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the `next_url` field in the return response.

                '
        - oneOf:
          - required:
            - before
          - required:
            - after
    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
    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
    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`

        '
      schema:
        type: boolean
    limit:
      in: query
      name: limit
      required: false
      description: How many results to return.
      schema:
        type: integer
        minimum: 1
        default: 10
        maximum: 100
        example: 10
    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'
    mail_type:
      in: query
      name: mail_type
      description: 'A string designating the mail postage type: * `usps_first_class` - (default) * `usps_standard` - a <a href="https://lob.com/pricing/print-mail#compare" target="_blank">cheaper option</a> which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States.

        '
      schema:
        $ref: '#/components/schemas/mail_type'
    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'
  responses:
    all_letters:
      description: A dictionary with a data property that contains an array of up to `limit` letters. Each entry in the array is a separate letter. The previous and next page of letters can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively. If no more letters are available beyond the current set of returned results, the `next_url` field will be empty.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/list'
            - type: object
              properties:
                data:
                  type: array
                  description: list of letters
                  items:
                    $ref: '#/components/schemas/letter'
          example:
            data:
            - id: ltr_5ba44b462c79f07c
              description: Demo Letter
              metadata: {}
              to:
                id: adr_asdi2y3riuasasoi
                description: Harry - Office
                name: Harry Zhang
                company: Lob
                phone: '5555555555'
                email: harry@lob.com
                metadata: {}
                address_line1: 370 WATER ST
                address_line2: ''
                address_city: SUMMERSIDE
                address_state: PRINCE EDWARD ISLAND
                address_zip: C1N 1C4
                address_country: CANADA
                recipient_moved: false
                date_created: '2019-09-20T00:14:00.361Z'
                date_modified: '2019-09-20T00:14:00.361Z'
                object: address
              from:
                id: adr_210a8d4b0b76d77b
                description: null
                name: LEORE AVIDAR
                company: null
                phone: null
                email: null
                address_line1: 210 KING ST STE 6100
                address_line2: null
                address_city: SAN FRANCISCO
                address_state: CA
                address_zip: 94107-1741
                address_country: UNITED STATES
                metadata: {}
                date_created: '2018-12-08T03:01:07.651Z'
                date_modified: '2018-12-08T03:01:07.651Z'
                object: address
              color: true
              double_sided: false
              address_placement: top_first_page
              return_envelope: false
              perforated_page: null
              extra_service: certified
              custom_envelope: null
              template_id: tmpl_a
              template_version_id: vrsn_a
              mail_type: usps_first_class
              url: https://lob-assets.com/letters/ltr_5ba44b462c79f07c.pdf?version=v1&expires=1568239830&signature=Ob-DUPLJLM4scWQeCDNadPJ4j33MZw16pykOxwv2us-bA7utTYi6oZ8WrEtBYDBBo09XkapR3gdJf0NEr90xAA
              merge_variables: null
              carrier: USPS
              tracking_number: '92071902358909000011275538'
              tracking_events:
              - id: evnt_9e84094c9368cfb
                type: certified
                name: Delivered
                details:
                  event: delivered
                  description: Package has been delivered.
                  notes: Delivered, Front Desk/Reception/Mail Room
                  action_required: false
                location: '33408'
                time: '2019-10-08T19:41:00Z'
                date_created: '2019-10-08T19:41:00Z'
                date_modified: '2019-10-08T19:41:00Z'
                object: tracking_event
              thumbnails:
              - small: https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_small_1.png?version=v1&expires=1568239830&signature=xZUmE8rq8wSECHPEb9c37cUDZBzGUO3XK5LsIPZhI6dOXgm6zJEn8_7tKuZ3JWBmvNJNXdTl_ufkNu4avjQUDw
                medium: https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_medium_1.png?version=v1&expires=1568239830&signature=H7354Qpcm9S4aXbrMsBe6QJ6lSNi9IWPgMJtLWLi4Kyx9tHF8Mp9YEc_IL9x89Jfw4-yRzKDXA410X4W0PssBQ
                large: https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_large_1.png?version=v1&expires=1568239830&signature=54LUIDKZyItA9pnC87d1pJVAuw8bhKLCsMpNWkB3LgdVWxPxxb_c1IyIWAbSR-dyOYEOlDBCc40J4Kns-O_mAg
              expected_delivery_date: '2019-08-16'
              date_created: '2019-08-08T17:09:14.514Z'
              date_modified: '2019-08-08T17:09:16.850Z'
              send_date: '2019-08-08'
              use_type: marketing
              fsc: false
              object: letter
            - id: ltr_da8267c6a6545cd6
              description: Demo Letter
              metadata: {}
              to:
                id: adr_210a8d4b0b76d77b
                description: null
                name: LEORE AVIDAR
                company: null
                phone: null
                email: null
                address_line1: 210 KING ST STE 6100
                address_line2: null
                address_city: SAN FRANCISCO
                address_state: CA
                address_zip: 94107-1741
                address_country: UNITED STATES
                metadata: {}
                date_created: '2018-12-08T03:01:07.651Z'
                date_modified: '2018-12-08T03:01:07.651Z'
                object: address
              from:
                id: adr_210a8d4b0b76d77b
                description: null
                name: LEORE AVIDAR
                company: null
                phone: null
                email: null
                address_line1: 210 KING ST STE 6100
                address_line2: null
                address_city: SAN FRANCISCO
                address_state: CA
                address_zip: 94107-1741
                address_country: UNITED STATES
                metadata: {}
                date_created: '2018-12-08T03:01:07.651Z'
                date_modified: '2018-12-08T03:01:07.651Z'
                object: address
              color: true
              double_sided: false
              address_placement: top_first_page
              return_envelope: false
              perforated_page: null
              extra_service: null
              custom_envelope: null
              mail_type: usps_first_class
              url: https://lob-assets.com/letters/ltr_da8267c6a6545cd6.pdf?version=v1&expires=1568239830&signature=HH-5RnbD4x0eJcnEC9HhqKSvQGsbkjovzvqSKgBijUHKIXwEKQJ4CbYhKs_U2q2A1k20Xefcaw7bfdPKozuqCQ
              merge_variables: null
              carrier: USPS
              tracking_number: null
              tracking_events: []
              thumbnails:
              - small: https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_small_1.png?version=v1&expires=1568239830&signature=C1Rs83187HpWGhsg_pJIOhDIKlDtC_IgBBxHiocCEzJ8CncJwqrq5yHke-p97Dv7o81G_pfhFmirai589O6DCw
                medium: https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_medium_1.png?version=v1&expires=1568239830&signature=gz63l0yi3sK_sXjYfIVdLSvkknJFr_O5TWRulo_iKIgS-PosIl6J0tDR6bx_Tv5Ab_w7DABg3qdKZ846MZ7TCw
                large: https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_large_1.png?version=v1&expires=1568239830&signature=4Y1OIymaWkSO3aBIHCeshFAVnF-pDcF2FFqkx_jovaUFuk4FT1SI24L7_POwTRXQHlETMGlzkP_CGgqselRUAA
              expected_delivery_date: '2019-08-16'
              date_created: '2019-08-08T17:08:12.224Z'
              date_modified: '2019-08-08T17:08:13.990Z'
              send_date: '2019-08-08T17:08:12.224Z'
              cards: null
              use_type: marketing
              fsc: true
              object: letter
            object: list
            next_url: https://api.lob.com/v1/letters?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wOFQxNzowODoxMi4yMjRaIiwiaWRPZmZzZXQiOiJsdHJfZGE4MjY3YzZhNjU0NWNkNiJ9
            previous_url: null
            count: 2
    mailpiece_error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            error:
              code: not_found
              message: to address not found
              status_code: 404
    post_letter:
      description: Returns a letter object
      headers:
        ratelimit-limit:
          $ref: '#/components/headers/ratelimit-limit'
        ratelimit-remaining:
          $ref: '#/components/headers/ratelimit-remaining'
        ratelimit-reset:
          $ref: '#/components/headers/ratelimit-reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/letter'
          example:
            id: ltr_4868c3b754655f90
            description: Demo Letter
            metadata: {}
            to:
              id: adr_d3489cd64c791ab5
              description: null
              name: HARRY ZHANG
              company: null
              phone: null
              email: null
              address_line1: 210 KING ST STE 6100
              address_line2: null
              address_city: SAN FRANCISCO
              address_state: CA
              address_zip: 94107-1741
              address_country: UNITED STATES
              metadata: {}
              date_created: '2017-09-05T15:54:53.264Z'
              date_modified: '2017-09-05T15:54:53.264Z'
              deleted: true
              object: address
            from:
              id: adr_b8fb5acf3a2b55db
              description: null
              name: LEORE AVIDAR
              company: null
              phone: null
              email: null
              address_line1: 210 KING ST STE 6100
              address_line2: null
              address_city: SAN FRANCISCO
              address_state: CA
              address_zip: 94107-1741
              address_country: UNITED STATES
              metadata: {}
              date_created: '2017-09-05T15:54:53.264Z'
              date_modified: '2017-09-05T15:54:53.264Z'
              deleted: true
              object: address
            color: true
            double_sided: true
            address_placement: top_first_page
            return_envelope: false
            perforated_page: null
            custom_envelope: null
            extra_service: null
            mail_type: usps_first_class
            url: https://lob-assets.com/letters/ltr_4868c3b754655f90.pdf?expires=1540372221&signature=8r94fse8uam7wGWmW5baxXulU88X2CA
            carrier: USPS
            tracking_number: null
            tracking_events: []
            thumbnails:
            - small: https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=a5fRBJ22ZA78Vgpg34M9UfmHWTS3eha
              medium: https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=bAzL8sv935PY09FWSkpDpWKkyvGSWYF
              large: https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=gsKvxXgrm4v4iZD3bOibK7jApNkEMdW
            merge_variables:
              name: Harry
            expected_delivery_date: '2017-09-12'
            date_created: '2017-09-05T15:54:53.346Z'
            date_modified: '2017-09-05T15:54:53.346Z'
            send_date: '2017-09-05T15:54:53.346Z'
            cards:
            - id: card_c51ae96f5cebf3e
              account_id: fa9ea650fc7b31a89f92
              description: null
              url: https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA
              size: 2.125x3.375
              auto_reorder: false
              reorder_quantity: null
              raw_url: https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw
              front_original_url: https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw
              back_original_url: https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw
              thumbnails:
              - small: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg
                medium: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA
                large: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw
              - small: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg
                medium: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag
                large: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw
              available_quantity: 10000
              pending_quantity: 0
              countries: null
              status: rendered
              mode: test
              orientation: horizontal
              threshold_amount: 0
              date_created: '2017-08-05T15:54:53.346Z'
              date_modified: '2017-08-05T15:54:53.346Z'
              object: card
            use_type: marketing
            fsc: false
            object: letter
  headers:
    ratelimit-limit:
      description: The rate limit for a given endpoint.
      schema:
        type: integer
        example: 150
    ratelimit-reset:
      description: 'The time at which the rate limit window resets in  <a href="https://en.wikipedia.org/wiki/Unix_time" target="_blank">UTC epoch seconds</a>

        '
      schema:
        type: integer
        example: 1528749846
    ratelimit-remaining:
      description: The number of requests remaining in the current window.
      schema:
        type: integer
        example: 100
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-webhooks:
  events:
    post:
      summary: Events
      description: Information about an event
      operationId: event
      tags:
      - Events
      responses:
        '200':
          $ref: '#/components/responses/events'
  tracking_events:
    post:
      summary: Tracking Events
      description: Information about tracking events
      operationId: tracking_event
      tags:
      - Tracking Events
      responses:
        '200':
          $ref: '#/components/responses/tracking_events'
x-tagGroups:
- name: Overview
  tags:
  - Introduction
  - Authentication
  - Getting Started
  - SDKs and Tools
- name: Address Book
  tags:
  - Addresses
  - National Change of Address
- name: Print and Mail API
  tags:
  - Postcards
  - Self Mailers
  - Letters
  - Checks
  - Snap Packs
  - Booklets
  - Bank Accounts
  - Templates
  - Template Versions
  - Template Design
  - Manage Mail
- name: Campaigns API (BETA)
  tags:
  - Campaigns
  - Creatives
  - Uploads
- name: Informed Delivery Campaign API
  tags:
  - Informed Delivery Campaign
- name: Address Verification API
  tags:
  - US Verifications
  - US Verification Types
  - US Autocompletions
  - Reverse Geocode Lookups
  - Zip Lookups
  - Identity Validation
  - Intl Verifications
- name: Webhooks
  tags:
  - Webhooks
  - Events
  - Tracking Events
- name: Special Features
  tags:
  - Billing Groups
  - Buckslips
  - Buckslip Orders
  - Cards
  - Card Orders
  - QR Codes
  - URL Shortener
- name: Appendix
  tags:
  - Beta Program
  - Errors
  - Rate Limiting
  - Requests and Responses
  - Test and Live Environments
  - Versioning and Changelog