Lob Letters API

openapi: 3.2.0
info:
  title: Lob Letters API
  version: 1.20.2
  description: Experience direct mail like never before, with unmatched personalization and scalability  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:
    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}$
    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
            - 'null'
          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
    user_provided:
      type:
      - string
      - 'null'
      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.
      pattern: ^env_[a-zA-Z0-9]+$
    evnt_id:
      type: string
      description: Unique identifier prefixed with `evnt_`.
      pattern: ^evnt_[a-zA-Z0-9]+$
    error:
      type: object
      description: Lob uses RESTful HTTP response codes to indicate success or failure of an API request. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - status_code
          - code
          properties:
            message:
              type: string
              description: A human-readable message with more details about the error
              example: Rate limit exceeded. Please wait 5 seconds and try your request again.
            status_code:
              $ref: '#/components/schemas/failure_status_code'
            code:
              type: string
              enum:
              - bad_request
              - conflict
              - feature_limit_reached
              - internal_server_error
              - invalid
              - not_deletable
              - not_found
              - request_timeout
              - service_unavailable
              - unrecognized_endpoint
              - unsupported_lob_version
              - address_length_exceeds_limit
              - bank_account_already_verified
              - bank_error
              - billing_address_required
              - custom_envelope_inventory_depleted
              - deleted_bank_account
              - failed_deliverability_strictness
              - file_pages_below_min
              - file_pages_exceed_max
              - file_size_exceeds_limit
              - foreign_return_address
              - inconsistent_page_dimensions
              - invalid_bank_account
              - invalid_bank_account_verification
              - invalid_check_international
              - invalid_country_covid
              - invalid_file
              - invalid_file_dimensions
              - invalid_file_download_time
              - invalid_file_url
              - invalid_image_dpi
              - invalid_international_feature
              - invalid_perforation_return_envelope
              - invalid_template_html
              - mail_use_type_can_not_be_null
              - merge_

# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lob/refs/heads/main/openapi/lob-letters-api-openapi.yml