Adding QR codes

This feature is available to users of all plans, and is currently in public beta.
Reach out to your Account Manager or to [email protected] if you would like to have this enabled for your account.


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 free native QR code service, personalized tracking can now be easily incorporated into your Direct Mail campaigns. This gives you a chance to capture Direct Mail response data in real time, long before any conversion event ultimately takes place.
Lob’s QR code service is a free tool that allows you to dynamically generate unique QR codes for each individual mailpiece you send. This gives you the ability to track individual user responses, personalize landing page experiences, and ultimately measure the impact of every mailpiece you send.
Finally, if you already are using a 3rd-party API or Javascript to generate unique QR codes, you can easily incorporate those into your Lob creative as well.

Lob native QR codes

QR Codes can be generated for Postcards and Letters today via the API, with support for additional channels and mail formats coming soon.
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 that you want to send the user to upon a scan. Then, when Lob generates the mailpiece, Lob will also dynamically generate the unique QR code and incorporate it into your design.

How to create Lob QR Codes

Mailpiece placement

Lob QR codes can be generated by including the qr_code object in the API request body while creating Letters or Postcards. This is only available via the single-endpoint APIs today.
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.


Next, indicate the position of your QR code in your mailpiece by setting the required Position parameter to relative, then setting the distance from a reference position of the “Bottom/Top” and “Right/Left” of your design, in inches.
Here, you will set your vertical and horizontal parameters:
  • 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
Lob recommends using 'bottom-right' as your placement anchor; however, there are a total of 4 anchor combinations available for potential use: top-left, top-right, bottom-left, or bottom-right.
Other considerations:
  • 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 in postcards, make sure to take into account the 0.25” bleed edge added to the artboard dimensions of the mailpiece if it is a postcard or self-mailer. For example, the dimensions of a 4x6” Postcard in Lob are actually 4.25” x 6.25”.
  • 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.


Then, set the size of your QR Code by passing through the Width parameter of your QR code in inches. The minimum Width is at least 1” in size, so that the code can be easily scanned.


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)
Currently, you cannot generate QR codes with different locations on different pages. You can also currently only generate 1 QR code per mailpiece.

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://”


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.

How to capture 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.

QR Code Analytics endpoint

Analytics for Lob-native QR codes are available both in Lob's Analytics Dashboard and to be retrieved from Lob’s API endpoint.
In the Analytics Dashboard, navigate to Attribution Analytics tab to see data on the number of mailpieces sent with QR codes, and the number of scans those QR codes received.
More specific data can be retrieved from the API. 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.
For more information, see the QR Code Analytics section in our API documentation.

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 that 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: 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 non Lob-generated QR Codes


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 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, which you can change simply by changing the URL after text=
So, in a Lob template it might look something like:
<img src="
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="{{cid}
Just note that if you are doing this at scale, you will want to subscribe to, and incorporate your 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:{{Campaign_Name}}&utm_customer={{Customer_ID}}&utm_name={{Recipient_Name}}
Example Script tag:
<script type="text/javascript" src="https://[hosting-location]/qrcode.js"></script>
<script type="text/javascript">
var qrcode = new QRCode(document.getElementById("qrcode"), {
text: "{{Campaign_Name}}&utm_customer={{Customer_ID}}&utm_name={{Recipient_Name}}",
width: 100,
height: 100,