API Docs Template Gallery Product Updates
Contact Us

Adding QR codes

Overview

Lob’s platform allows you to generate a QR code for each individual mailpiece you send. This feature is available via

Personalized response tracking is a standard feature of digital marketing channels, but has traditionally been difficult to replicate in Direct Mail. However, with Lob’s QR code offering, personalized tracking can now be easily incorporated into your Direct Mail campaigns.

We offer engagement analytics to measure the impact of every mailpiece you send. This gives you the ability to track Direct Mail response data in real-time, long before any conversion event ultimately takes place.

Lob QR codes via the Campaigns tool

Standard QR codes

  • All users can generate a single black and white QR code via the Campaigns tool in the dashboard for postcards, all letters, self-mailers, and snap packs.

  • This QR code will be static, that is, a single URL will be applied across all recipients in a campaign.

  • The QR code appears in the same location on each mail piece.

In Step 3 of Campaigns generation, after you’ve uploaded your creative (PDF or HTML), select "Add QR code" and a module will pop up.

In the top left-hand side of the QR code builder, under URL click the “Create QR Code URL” button to open an additional window. Enter the landing page URL; this will be used for all mailpieces (and all recipients) in a campaign. When you have input your URL, Save & Close to continue the QR code build.

Next, select “Generate QR code.” A QR code will appear on your mailpiece and you can adjust the size and the placement of the QR code. We recommend sizing no smaller than one inch for optimal readability, and your code should be placed inside the bleed lines, which you can toggle on and off.

When you are happy with your design, Save & Close.

Custom QR codes

These features are available for Enterprise users. Upgrade your Print & Mail edition to gain access to this feature, or reach out to our sales team to learn more.

Custom QR code features are available for postcards, (standard) letters, and self-mailers only.

With custom QR codes, you can customize the foreground and background color of the QR code, add a logo into the center of the QR code, and create personalized URLs with dynamic merge tags that are unique to each recipient.

Custom QR codes: Color

Match your design elements and branding by customizing the color of your QR codes.

In Step 3 of the Campaigns workflow, after you’ve uploaded your creative (PDF or HTML), open the QR code module by clicking the “Add a QR Code” button.

Within the customize section of the QR code builder, you will see an option to customize the Background color and Foreground color. The default color option is set to white and black respectively.

When selecting a color, you can pick from the color gradient selection, or if you have a specific hex color that your brand uses, you can type in or paste the hex value into the color picker to apply your changes. You can choose colors that align with your brand or design for your QR code, but ensure it remains scannable on mobile devices. We recommend using contrasting colors to maintain readability (for example, dark red on light grey has a better contrast than light grey on light blue).

When you are happy with your design, Save & Close.

Further your brand by adding your company logo inside the QR code.

In Step 3 of the Campaigns workflow, after you’ve uploaded your creative (PDF or HTML), open the QR code module by clicking the “Add a QR Code” button.

Within the QR code builder, click the “Upload” button under Brand logo.

  • Acceptable image types to upload and attach to your QR code are JPG and PNG and file size cannot exceed 1MB.

  • When uploading a logo to your QR code, Lob will automatically resize the logo to fit the dimensions required for the QR code to properly display.

  • For transparent images like PNG and SVG, Lob will automatically apply a background color behind the logo so that it’s readable. By default the background color is set to black. If you need a white background to show instead, reverse the colors in the QR code builder so that the background color is white and the foreground color is black as shown below.

When you are happy with your design, Save & Close.

We recommend you verify the QR code looks exactly like you want it to and scans correctly; you can view the Creative Proof to view a sample of a rendered mailpiece.

Custom QR codes: Personalized URLs

Build fully customizable and dynamic QR code URLs for a 1-1 recipient matching.

In Step 3 of the Campaigns workflow, after you’ve uploaded your creative (PDF or HTML),open the QR code module by clicking the “Add a QR Code” button.

In the top left-hand side of the QR code builder, under URL click the “Create QR Code URL” button to open an additional window to build out your customized URL. To add personalized merge tags into the URL for each recipient, click “Add merge tag” which displays fields for you to pull variables into your URL.

  • For One-time campaigns, the merge tags will pull in the columns within the audience file added in Step 2 of the campaign builder.

  • For Automated campaigns, the merge tags will pull fields from the integration and trigger components you’ve previously set up.

  • When adding a merge tag into the URL, you can add a dynamic value as a key path in the URL e.g., lob.com/{{state}} if certain recipients will receive a specific landing page for each state they reside in.

  • If you want to add optional parameters to your URL, add a question mark “?” to the URL followed by the merge tag. Example: lob.com/{{state}}/?{{discount_value}} would output as lob.com/california/?20 to the end recipient.

  • If you have a use case where you need the entire URL to pull from a row in your audience file that you have already created and included, you can simply add that URL as a merge tag, and only use that merge tag for the QR code URL: {{landing_page_URL}}

Ensure you use unique variable names in both HTML templates and QR codes. If you use the same variable names in both places, the previous mapping will be overridden, and your mailpiece will not generate correctly.

A merge tag can only be used once in a QR code URL. If you have already added a {{state}} merge tag to the URL, you cannot add it again.

What if some recipients have an empty cell/value?

If some recipients have empty merge tags, you can add an optional fallback for each merge tag. This fallback will only be used if the merge tag is empty. Adding a fallback is not required for the QR code to work properly.

For example, if a recipient’s {{state}} merge tag is empty, you can set a fallback to "California," and they will see "California" in the URL and still be directed to the correct page.

When you have input your URL, Save & Close to continue the QR code build.

Lob QR codes via Print & Mail API and Campaigns API

Standard QR codes

All users can generate standard QR Codes for postcards, all letters, self-mailers, and snap packs via API.

QR Codes are generated within the API call to create a Lob mailpiece. In addition to passing Lob the name, address, and creative you would like to send the recipient, you will also pass the required parameters to create a QR code: size, positioning, and the URL where you want to send the user upon a scan. Then, when Lob generates the mailpiece, Lob will also dynamically generate the unique QR code and incorporate it into your design.

Lob QR codes can be generated by including the qr_code object in the transactional API request body while creating Letters, Postcards, or Self-mailers. In the Campaigns API (beta), this object can be found in the Creatives (Create) call. 

 "qr_code": {
    "position": "relative",
    "redirect_url": "https://www.lob.com/?customer_id12345",
    "width": "2",
    "top": "2.25",
    "left": "3.125",
    "pages": "back"
},

Custom QR codes

These features are available for Enterprise users. Upgrade your Print & Mail edition to gain access to this feature, or reach out to our sales team to learn more.

Custom QR code features are available for postcards, (standard) letters, and self-mailers only.

  • To add a logo to the center of the QR code include the logo key.

  • To customize the colors: An optional style object can be set on the qr_code request to customize the colors for the QR code. This enables users to fully select the colors that will be applied on the QR codes. The style object takes a foreground_color and a background_color option where you can provide the Hex code for the color you wish to apply to the QR codes.

  • See below section on URL redirects for how to personalize URLs.

// S"qr_code": {
  "position": "relative",
  "redirect_url": "https://www.lob.com/?customer_id12345",
  "width": "2",
  "top": "2.25",
  "left": "3.125",
  "style": {
    "foreground_color": "#000000",
    "background_color":"#ffffff",
  },
  "logo":{"url": "https://lob-assets.com/logos/lob_logo.png"},

Positioning

Indicate the position of your QR code in your mailpiece by setting the required Position parameter to relative, then set the distance from a reference position of the “Bottom/Top” and “Right/Left” of your design, in inches. There are a total of 4 anchor combinations available for potential use: top-left, top-right, bottom-left, or bottom-right. Lob recommends using 'bottom-right' as your placement anchor.

  • Use bottom for your vertical parameter: The field takes in a value between 0 to max length of the creative

  • Use right for your horizontal parameter: The field takes in a value between 0 to max width of a creative

Pagination

An optional Pages parameter can be used to specify the pages, in a ‘comma separated’ format, where the QR code should appear. If not included, the default is page 1 for letters, or front for postcards.

  • For Postcards, the values should be either front, back, or front,back.

  • For Letters, the values can be specific page numbers or page number ranges (ex: 2,5 or 1-3)

  • For Self-mailers & Snap packs, the values should be inside, outside,or inside,outside.

  • Currently, you cannot generate QR codes with different locations on different pages.

  • Via API, users can add more than one QR code to a campaign mail piece (ex: front and back of a postcard, or front and back of a letter) as long as it is placed in the exact location on each side.

Destination URL & redirects

Finally, you will set the Destination URL that the QR code resolves to by passing it into the Redirect_URL parameter. Since Lob QR codes are dynamic, you can pass a unique URL for every single mailpiece you create, such as to direct every mail recipient to a unique landing page, or to capture data using unique UTM parameters.

In the sample API request body above ("redirect_url": "https://www.lob.com/?customer_id12345") we are capturing the specific user ID of the intended recipient of the mailpiece in Lob’s website analytics when the QR code is scanned.

Every QR code generated will have a short Redirect URL assigned to it, which will resolve through to the Destination URL passed in the API call. This means you have the flexibility to change the Destination URL after the QR code has been generated, even if the mail has already been sent, as the initial Redirect URL will remain the same. Once a QR code is scanned, the user will see a redirect screen (as shown on the right).

All URLs passed in the Redirect_URL parameter should begin with “http://” or “https://”

Customize Redirect URLs for Postcard, Letters, Checks, Self mailer API endpoints:

To customize the redirect_url for each recipient, you will use merge_variables. In your redirect_url provide a template url, for eg: https://www.google.com?q={{name}}, where the value for the {{name}} variable would come from the merge_variables section of the payload.

{
   “description”: “postcard with sample merge variables”,
   "qr_code": {
     "position": "relative",
     "redirect_url": "https://www.lob.com/?{{customer_id}}",
     "width": "2",
     "top": "2.25",
     "left": "3.125",
    },
    “merge_variables”: {
	“customer_id”: “lob_12”
   }
}

Customize Redirect URLs in Campaigns API:

With the Campaigns API (beta), you have the option to set a single redirect for all recipients in your campaign or unique redirect URLs for each recipient.

To set a single URL redirect for the entire campaign, set the `redirect_url` in the details section of the Creatives (Create) request to your desired URL to this field.

Enterprise users can customize redirect URLs for each campaign recipient by providing a URL template and a data mapping from the Audience file, enabling Lob to generate unique QR code destinations for each mailpiece.

  • An example of a URL template for the redirect_url, is www.google.com?q={{name}}, you can add one or more variables in the template and submit the creative request.

  • The next step is to let us know where this value comes from, and to do so we allow users to map name to any column from the Audience file. You can provide this mapping by sending a POST or a PATCH request to the /uploads endpoint for the campaigns.

  • The mergeVariableColumnMapping holds the mapping for the name variable created in the URL template.

{
   "campaignId": "cmp_sample_id",
   "requiredAddressColumnMapping": {
       "name": "recipient_name",
       "address_line1": "primary_line",
       "address_city": "city",
       "address_state": "state",
       "address_zip": "zip_code"
   },
   "optionalAddressColumnMapping": {
       "address_line2": "secondary_line",
       "company": "company",
       "address_country": "country,"
   },
   "mergeVariableColumnMapping": {
       "name": "recipient_name"
   }
}

Errors

Lob API errors contain human-readable explanations in the message parameter.

For example, you may receive a 422 error containing the message “qr_code.position is required”. This indicates that no value was passed to the API in the position parameter.

QR code best practices

Remember to test! We recommend you verify the QR code looks exactly like you want it to and scans correctly.

  • In the Campaigns tool you can view the Creative Proof to view a sample of a rendered mailpiece.

  • If generating via API, use your Test API Key to preview your creative in Lob and verify that everything looks as intended.

  • Sizing: All QR codes are square; the minimum width should be at least 1” so that the code can be easily scanned. In the API, set the size of your QR Code by passing through the Width parameter of your QR code in inches.

  • Mailpiece placement: Lob QR codes will be pasted over your design like how Lob places the ‘Address Block’, so make sure to designate the size and positioning of your QR code away from any critical designs.

    • Do not place your QR code over the area in which the mailing address will be printed. Reference the Ink-Free areas for each template here.

    • Make sure to leave 0.25” of space between your QR code position and any content of your mailpiece that you don’t want to be covered.

    • When positioning your QR code, make sure to take into account the bleed edge added to the artboard dimensions of the mailpiece. For example, the dimensions of a 4x6” Postcard in Lob are 4.25” x 6.25”.

    • Lob QR Codes do not expire. If your destination URL expires, you may want to update live QR codes to redirect to an active landing page.

Engagement analytics for Lob QR Codes

You can capture impact and engagement metrics from your mail sends with Lob QR codes in a few ways.

Engagement analytics in the Lob dashboard

The Mail Analytics tab will display metrics for all mail you have sent with Lob across any number of campaigns within a time period. QR code scan data can be found under the Engagement tab.

From the Campaigns dashboard, when you drill down to the detail/status page for any individual campaign you can view campaign-specific analytics. QR code scan data can be found under the Analytics tab > QR Code Engagement.

QR Code Analytics endpoint

Retrieve analytics for Lob-native QR codes from Lob’s qr-code-service.lob.com API endpoint. For detailed data, see the QR Code section in our API documentation.

QR Code scan data is deleted after 90 days.

Real-time notifications via webhooks

Whenever a QR code is scanned from a mailpiece, there will be an event generated, such as postcard.viewed or letter.viewed. You can enable notifications on these events by setting up webhooks that will alert you when the scans occur.

This can be incorporated into your omnichannel marketing campaign to subsequently trigger an email, mailpiece, or other action when a mailpiece is viewed.

See the webhooks section in our API documentation, or learn more about using webhooks here in the help center.

UTM parameters

UTM parameters are short text codes that you add to URLs (or links) that help track performance. Because QR codes can be generated dynamically at the time of their creation, we can generate QR codes with UTM parameters that correlate to the recipient.

For instance, if we are sending a mailpiece to a recognized user we’ve assigned a Customer ID of “12345”, we can append that ID to their Destination Page URL, so that the user can be recognized by our web analytics once they reach the page: www.lob-example.com/login?customer_id=12345. This enables you to more easily attribute customer activity back to this mailpiece.

UTM parameters can also be used to track Campaign responses, A/B test variants, and other key data points that inform your understanding of the response to your campaign.

Utilizing QR codes created outside of Lob

Static

If you plan on submitting a static (non-personalized) creative via PDF, simply include the QR code image anywhere on the PDF in a way that is compliant with our PDF guidelines.

Dynamic QR Code via 3rd-Party API

Dynamic QR codes generated by third-party APIs can be added to your HTML templates. For example, a common tool for this is Quickchart.io. To leverage this, simply use the API endpoint URL as the source of an image within your HTML.

The example below generates a QR code that resolves to lob.com, which you can change simply by changing the URL after text=

https://quickchart.io/qr?text=https://www.lob.com

So, in a Lob template, it might look something like this:

<img src="
https://quickchart.io/qr?text=https://www.google.com
">

You can incorporate merge variables to make it dynamic, for example using {{qr_url}} as a merge variable that you can use to pass in a unique URL.

<img src="{{qr_url}}">

Or the variable can be incorporated into the URL, such as:

<img src="
https://quickchart.io/qr?text=https://www.google.com&customid={{cid}
}">

Just note that if you are doing this at scale, you will want to subscribe to Quickchart.io, and incorporate your Quickchart.io API Key into the URL so that you don’t encounter rate-limiting errors with Quickchart.

Dynamic QR Code via JavaScript:

You can also incorporate Javascript into your template, and leverage this qrcode.js script for dynamically creating a QR code.

Below is an example of how to reference the qrcode.js file (in this case, hosted in an external location for the sake of brevity, but it actually works best when the entire script is incorporated directly into a <script> tag in the HTML template).

You can see that this is generating a QR code that resolves to the following URL containing merge variables that you can inform dynamically: 

https://www.url.com/?utm_source={{Campaign_Name}}&utm_customer={{Customer_ID}}&utm_name={{Recipient_Name}}

Example Script tag:

<div id="qrcode"></div>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/qrcodejs/1.0.0/qrcode.min.js"></script>
<script type="text/javascript">
   var qrcode = new QRCode(document.getElementById("qrcode"), {
   text: "https://www.url.com/?utm_source={{Campaign_Name}}&utm_customer={{Customer_ID}}&utm_name={{Recipient_Name}}",
   width: 100,
   height: 100,
   });
</script>
PreviousDynamic table tutorialNextBuilding a mail strategy

Last updated