API Docs Postman Template Gallery
Contact Us

Adding QR codes

Overview

Lob’s QR code services allow you to generate a QR code for each individual mailpiece you send. This feature is available via our Campaigns UI, our APIs (Print & Mail and Campaigns API), and we also support the use of 3rd-party APIs or Javascript to generate QR codes.

We also offer attribution analytics to measure the impact of every mailpiece you send. 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 service, personalized tracking can now be easily incorporated into your Direct Mail campaigns. This gives you the ability to track individual user responses, personalize landing page experiences, and capture Direct Mail response data in real-time, long before any conversion event ultimately takes place.

Lob QR codes via the Campaigns tool

This feature is available for all monthly subscription editions. Upgrade your Print & Mail edition to gain access to this feature, or reach out to our sales team to learn more.

QR codes can be generated via the Campaigns tool in the dashboard for postcards, letters, and self-mailers.

In Step 3 of Campaigns generation, a user can add one black and white QR code to their mail pieces. Once "Add QR code" is selected, you will be prompted to enter the landing page URL, and then adjust the size and the placement of the QR code.

In the Campaigns UI, users can add a single QR code to their mail pieces; the QR code appears in the same location on each mail piece.

Lob QR codes via Print & Mail and Campaigns API

This feature is available for all monthly subscription editions. Upgrade your Print & Mail edition to gain access to this feature, or reach out to our sales team to learn more.

QR Codes can be generated for Postcards, Letters, and Self-mailers 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 API request body while creating Letters, Postcards, or Self-mailers. In the Campaigns API, this object can be found in the Creatives (Create) call. (Note, Campaigns API is still in beta.)

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

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 in the same exact location on each side.

Mailpiece placement considerations

Lob QR codes will be printed in black, on a white background. They will be pasted over your design in a manner similar to how Lob places the ‘Address Block’, so make sure to designate the size and positioning of your QR code away from any critical designs when making the API request.

  • 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 actually 4.25” x 6.25”.

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

See also the API documentation for qr_code object positioning.

Sizing

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

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, the values should be inside, outside,or inside,outside.

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

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.

For example, in the sample API request body above, 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://”

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.

Best practices

  • 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.

  • Remember to test! To ensure your QR code is placed correctly over your design, use your Test API Key to preview your creative in Lob and verify that everything looks as intended.

Activity and attribution for Lob QR Codes

As part of Lob’s suite of Mail measurement and tracking features, you can capture impact and engagement metrics from your mail sends with QR codes. Below are the options for retrieving Lob QR code tracking data for each scanned mailpiece.

Attribution Analytics in the Dashboard

Access to our Mail Analytics feature is exclusive to Enterprise Edition customers.

In the Mail Analytics in your Dashboard, navigate to the Attribution Analytics tab to see data on the number of mailpieces sent with QR codes, and the number of scans those QR codes received.

QR Code Analytics endpoint

Analytics for Lob-native QR codes can be retrieved from Lob’s qr-code-service.lob.com API endpoint. More specific data can be retrieved from the API (see the QR Code section in our API documentation). Every QR code generated in Lob will return a QR Code ID, which can be used to retrieve activity data for that specific QR code. You can pass a date range or list of resources to retrieve the total number of QR Code scans, as well as detailed information on each scan including IP address, the date of scan, and the number of times the QR code was scanned.

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 for more information.

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.

Using QR Codes generated 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