Lob Postcards API

openapi: 3.2.0
info:
  title: Lob Postcards 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: Postcards
  description: 'The postcards endpoint allows you to easily print and mail postcards. The API provides endpoints for creating postcards,

    retrieving individual postcards, canceling postcards, and retrieving a list of postcards.

    <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>

    '
paths:
  /postcards:
    get:
      operationId: postcards_list
      summary: List
      description: Returns a list of your postcards. The addresses are returned sorted by creation date, with the most recently created addresses appearing first.
      tags:
      - Postcards
      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: size
        description: Specifies the size of the postcard. Only `4x6` postcards can be sent to international destinations.
        schema:
          type: array
          items:
            $ref: '#/components/schemas/postcard_size'
      - $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_postcards'
        default:
          $ref: '#/components/responses/mailpiece_error'
      x-codeSamples:
      - lang: Shell
        source: "curl -X GET \"https://api.lob.com/v1/postcards?limit=2\" \\\n  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:\n"
        label: CURL
      - lang: typescript
        source: "try {\n  const postcards = await new PostcardsApi(config).list(2);\n} catch (err: any) {\n  console.error(err);\n}\n"
        label: TYPESCRIPT
      - lang: Javascript
        source: "Lob.postcards.list({limit: 2}, function (err, res) {\n  console.log(err, res);\n});\n"
        label: NODE
      - lang: Ruby
        source: "postcardsApi = PostcardsApi.new(config)\n\nbegin\n  postcards = postcardsApi.list({ limit: 2 })\nrescue => err\n  p err.message\nend\n"
        label: RUBY
      - lang: Python
        source: "with ApiClient(configuration) as api_client:\n  api = PostcardsApi(api_client)\n\ntry:\n  postcards = api.list(limit=2)\nexcept ApiException as e:\n  print(e)\n"
        label: PYTHON
      - lang: PHP
        source: "$apiInstance = new OpenAPI\\Client\\Api\\PostcardsApi($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: "PostcardsApi apiInstance = new PostcardsApi(config);\n\ntry {\n  PostcardList response = apiInstance.list(\n    2, // limit\n    null, // before\n    null, // after\n    null, // include\n    null, // dateCreated\n    null, // metadata\n    null, // size\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.Postcard.list(%{limit: 2})

          '
        label: ELIXIR
      - lang: CSharp
        source: "PostcardsApi api = new PostcardsApi(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);\nList<PostcardSize> sizeArray = new List<PostcardSize>();\nsizeArray.Add(PostcardSize._4x6);\n\ntry {\n  PostcardList response = api.list(\n    2, // limit\n    null, // before\n    null, // after\n    includeList, // include\n    dateCreated, // dateCreated\n    metadata, // metadata\n    sizeArray, // size\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)\nPostcardList = apiClient.PostcardsApi.List(context).Execute()\nif err != nil {\n    return err\n}\n"
        label: GO
    post:
      operationId: postcard_create
      summary: Create
      description: Creates a new postcard given information
      tags:
      - Postcards
      parameters:
      - $ref: '#/components/parameters/idem-header'
      - $ref: '#/components/parameters/idem-query'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postcard_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:
                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
              front: tmpl_a1234dddg
              back: tmpl_a1234dddg
              size: 6x9
              mail_type: usps_first_class
              merge_variables:
                name: Harry
              metadata:
                spiffy: 'true'
              send_date: '2017-11-01T00:00:00.000Z'
              use_type: marketing
              qr_code:
                position: relative
                redirect_url: https://www.lob.com
                width: '2.5'
                top: '2.5'
                right: '2.5'
                pages: front,back
              fsc: true
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/postcard_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:
                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
              front: tmpl_c94e83ca2cd5121
              back: tmpl_c94e83ca2cd5121
              size: 6x9
              mail_type: usps_first_class
              merge_variables:
                name: Harry
              metadata:
                spiffy: 'true'
              send_date: '2017-11-01T00:00:00.000Z'
              use_type: marketing
              qr_code:
                position: relative
                redirect_url: https://www.lob.com
                width: '2.5'
                bottom: '2.5'
                right: '2.5'
                pages: back
              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/postcard_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:
                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
              front: tmpl_a1234dddg
              back: tmpl_a1234dddg
              size: 6x9
              mail_type: usps_first_class
              merge_variables:
                name: Harry
              metadata:
                spiffy: 'true'
              send_date: '2017-11-01T00:00:00.000Z'
              use_type: marketing
              qr_code:
                position: relative
                redirect_url: https://www.lob.com
                width: '2.5'
                bottom: '2.5'
                left: '2.5'
                pages: front
              fsc: true
      responses:
        '200':
          $ref: '#/components/responses/post_postcard'
        default:
          $ref: '#/components/responses/mailpiece_error'
      x-codeSamples:
      - lang: Shell
        source: "curl https://api.lob.com/v1/postcards \\\n  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \\\n  -d 'description=Demo Postcard job' \\\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 'front=<html style=\"padding: 1in; font-size: 50;\">Front HTML for {{name}}</html>' \\\n  --data-urlencode 'back=<html style=\"padding: 1in; font-size: 20;\">Back HTML for {{name}}</html>' \\\n  -d 'merge_variables[name]=Harry' \\\n  -d 'use_type=marketing' \\\n  -d 'qr_code[position]=relative' \\\n  -d 'qr_code[redirect_url]=https://www.lob.com' \\\n  -d 'qr_code[width]=2.5' \\\n  -d 'qr_code[bottom]=2.5' \\\n  -d 'qr_code[left]=2.5' \\\n  -d 'qr_code[pages]=front,back' \\\n  -d 'fsc=true'\n"
        label: CURL
      - lang: Typescript
        source: "const postcardCreate = new PostcardEditable({\nto: new 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}),\nfrom: 'adr_xxxx',\nfront:\n'https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf',\nback: 'https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf',\nuse_type: 'marketing',\nqr_code : {\n  position: 'relative',\n  redirect_url: 'https://www.lob.com',\n  width: '2.5',\n  bottom: '2.5',\n  left: '2.5',\n  pages: 'front'\n},\nfsc: true\n});\n\ntry {\n  const myPostcard = await new PostcardsApi(config).create(postcardCreate);\n} catch (err: any) {\n  console.error(err);\n}\n"
        label: TYPESCRIPT
      - lang: Javascript
        source: "Lob.postcards.create({\n  description: 'Demo Postcard job',\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  front: '<html style=\"padding: 1in; font-size: 50;\">Front HTML for {{name}}</html>',\n  back: '<html style=\"padding: 1in; font-size: 20;\">Back HTML for {{name}}</html>',\n  merge_variables: {\n    name: 'Harry'\n  },\n  use_type: 'marketing'\n  qr_code : {\n    position: 'relative',\n    redirect_url: 'https://www.lob.com',\n    width: '2.5',\n    bottom: '2.5',\n    left: '2.5',\n    pages: 'back'\n  },\n  fsc: true\n}, function (err, res) {\n  console.log(err, res);\n});\n"
        label: NODE
      - lang: Ruby
        source: "postcardCreate = PostcardEditable.new({\n  description: \"Demo Postcard job\",\n  from: \"adr_210a8d4b0b76d77b\",\n  front: \"<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>\",\n  back: \"<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>\",\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  fsc: true\n});\n\npostcardApi = PostcardsApi.new(config)\n\nbegin\n  createdPostcard = postcardApi.create(postcardCreate)\nrescue => err\n  p err.message\nend\n"
        label: RUBY
      - lang: Python
        source: "postcard_editable = PostcardEditable(\n  description = \"Demo Postcard job\",\n  _from = \"adr_210a8d4b0b76d77b\",\n  front = \"<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>\",\n  back = \"<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>\",\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  use_type = \"marketing\",\n  qr_code = {\n    \"position\" : \"relative\",\n    \"redirect_url\" : \"https://www.lob.com\",\n    \"width\" : \"2.5\",\n    \"bottom\" : \"2.5\",\n    \"left\" : \"2.5\",\n    \"pages\" : \"front\"\n  },\n  fsc = true\n)\n\nwith ApiClient(configuration) as api_client:\n  api = PostcardsApi(api_client)\n\ntry:\n  created_postcard = api.create(postcard_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$merge_variables = new stdClass;\n$merge_variables->name = \"Harry\";\n$use_type = \"marketing\";\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\" => \"front,back\"\n  )\n);\n\n$fsc = true;\n\n$apiInstance = new OpenAPI\\Client\\Api\\PostcardsApi($config, new GuzzleHttp\\Client());\n$postcard_editable = new OpenAPI\\Client\\Model\\PostcardEditable(\n  array(\n    \"description\"     => \"Demo Postcard job\",\n    \"from\"     => \"adr_210a8d4b0b76d77b\",\n    \"front\"     => \"<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>\",\n    \"back\"     => \"<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>\",\n    \"to\"     => $to,\n    \"merge_variables\"   => $merge_variables,\n    \"use_type\" => $use_type,\n    \"qr_code\"   => $qr_code,\n    \"fsc\" => $fsc\n  )\n);\n\ntry {\n    $result = $apiInstance->create($postcard_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\nPostcardsApi apiInstance = new PostcardsApi(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(\"back\");\n\ntry {\n  PostcardEditable postcardEditable = new PostcardEditable();\n  postcardEditable.setDescription(\"Demo Postcard job\");\n  postcardEditable.setFrom(\"adr_210a8d4b0b76d77b\");\n  postcardEditable.setFront(\"<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>\");\n  postcardEditable.setBack(\"<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>\");\n  postcardEditable.setTo(to);\n  postcardEditable.setMergeVariables(merge_variables);\n  postcardEditable.setUseType(\"operational\");\n  postcardEditable.setQRCode(qrCode);\n  postcardEditable.setFsc(true);\n\n  Postcard result = apiInstance.create(postcardEditable, null);\n} catch (ApiException e) {\n  e.printStackTrace();\n}\n"
        label: JAVA
      - lang: Elixir
        source: "Lob.Postcard.create(%{\n  description: 'Demo Postcard job',\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  front: '<html style=\"padding: 1in; font-size: 50;\">Front HTML for {{name}}</html>',\n  back: '<html style=\"padding: 1in; font-size: 20;\">Back HTML for {{name}}</html>',\n  merge_variables: %{\n    name: 'Harry'\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: 'front,back'\n  },\n  fsc: true\n})\n"
        label: ELIXIR
      - lang: CSharp
        source: "Dictionary<string, string> mergeVariables = new Dictionary<string, string>();\nmergeVariables.Add(\"name\", \"Harry\");\n\nPostcardsApi api = new PostcardsApi(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  CountryExtended.US,  // 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  \"front\", //pages\n);\n\nFsc fsc = new Fsc(true);\n\nPostcardEditable postcardEditable = new PostcardEditable(\n  to.ToJson(),  // to\n  \"adr_249af768103d2810\",  // from\n  default(PostcardSize),  // size\n  \"Demo Postcard Job\",  // description\n  null,  // metadata\n  default(MailType),  // mailType\n  mergeVariables,  // mergeVariables\n  default(DateTime),  // sendDate\n  \"<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>\",  // front\n  \"<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>\", // back\n  usetype,\n  qrCode,\n  fsc\n);\n\ntry {\n  Postcard result = api.create(postcardEditable, 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 postcardCreate = *lob.NewPostcardEditable()\npostcardCreate.SetDescription(\"Demo Postcard job\")\npostcardCreate.SetFrom(\"adr_210a8d4b0b76d77b\")\npostcardCreate.SetFront(\"<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>\")\npostcardCreate.SetBack(\"<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>\")\npostcardCreate.SetTo(to)\npostcardCreate.SetFsc(true)\n\n\ncreatedpostcard, _, err := apiClient.PostcardsApi.Create(context).PostcardEditable(postcardCreate).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}$
    postcard_size:
      type: string
      enum:
      - 4x6
      - 6x9
      - 6x11
      description: 'Specifies the size of the postcard. Only `4x6` postcards can be sent to international destinations.

        '
      default: 4x6
    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
            - 'null'
            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
          company:
            $ref: '#/components/schemas/company'
          phone:
            type:
            - string
            - 'null'
            description: Must be no longer than 40 characters.
            maxLength: 40
          email:
            type:
            - string
            - 'null'
            description: Must be no longer than 100 characters.
            maxLength: 100
          address_country:
            type: string
            enum:
            - US
            default: US
          metadata:
            $ref: '#/components/schemas/metadata'
    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'
    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
    count:
      type: integer
      description: number of resources in a set
    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)$
    psc_back:
      description: "The artwork to use as the back of your postcard.\n\nNotes:\n- HTML merge variables should not include delimiting whitespace.\n- PDF, PNG, and JPGs must be sized at 4.25\"x6.25\", 6.25\"x9.25\", or 6.25\"x11.25\" at 300 DPI, while supplied HTML will be rendered to the specified `size`.\n- Be sure to leave room for address and postage information by following the templates provided here:\n  - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/4x6_postcard.pdf\" target=\"_blank\">4x6 template</a>\n  - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/6x9_postcard.pdf\" target=\"_blank\">6x9 template</a>\n  - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/6x11_postcard.pdf\" target=\"_blank\">6x11 template</a>\n\n\nSee [here](#section/HTML-Examples) for HTML examples.\n"
      oneOf:
      - $ref: '#/components/schemas/html_string'
      - $ref: '#/components/schemas/tmpl_id'
      - $ref: '#/components/schemas/remote_file_url'
      - $ref: '#/components/schemas/local_file_path'
    psc_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
      - 'null'
      enum:
      - marketing
      - operational
      - null
    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-_]+
    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"
    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.'
    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

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