Only this pageAll pages
Powered by GitBook
Couldn't generate the PDF for 139 pages, generation stopped at 100.
Extend with 50 more pages.
1 of 100

Lob Help Center

Print & Mail

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Address Verification

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Ready to get started?

Welcome to Lob! 👋

Lob's mission is to help the world send intelligent mail, one mail piece at a time. By making direct mail sends as easy as email through the use of modern APIs, Lob strives to modernize this often overlooked channel of direct communication.

Lob is a great fit for all users of direct mail from all walks of life:

  • Are you brand new to direct mail as a channel, and looking for ideas and best practices on getting started?

  • Are you looking to infuse direct mail automation into your existing business workflows and seeking for ways to modernize your enterprise solutions and tools?

  • Or are you building a highly sophisticated experimentation program using this rapidly iterative and performative channel?

Start at a pace you're most comfortable with, and Lob can help meet your direct mail needs, one step at a time.

Getting started with Lob

Sending mail in an accurate, reliable, and programmatic way involves the following four steps:

The first step to any successful direct mail program is to put together an audience list for effective targeting.

Whether you are using your own customer data or augmenting with third-party lists, make sure that you create targeted mailing lists with select attributes to maximize your responses and channel ROI.

Easily upload your campaign audience list in Lob Campaigns, or send a recipient address per mail piece in your API calls.

You can also improve the deliverability of your mail pieces by passing your addresses through Lob's National Change of Address functionality to reduce bad addresses, or incorporate Lob's Address Verification product to fully ensure your mail data is as accurate as possible to maximize your intended reach.

Next, our API-first solution provides incredible flexibility in determining how you want to send your mail: send high-volume campaigns quickly and at scale, or build automated mail sends triggered through omnichannel business workflows.

In order to use direct mail with Lob, there are three components that must be thought through to send mail via our platform:

  • Design: generate clear and concise instructions around what you're sending, including creative artwork and copy. Learn about designing creatives in Lob.

  • Data in: pass data that determines how you want to send mail and get it delivered, including address data, merge variables for personalization, postage and delivery strategy. Learn about building your mail strategy in Lob.

  • Data out: pass data that exports mail tracking information to enable downstream workflows or measure attribution for better performance. Learn more about how to calibrate your mail data in Lob.

Based on your API call submission and send settings, a printer from a strategically distributed network of printers managed by Lob will fulfill your orders. Once printed, your mail orders will be handed off to USPS for delivery.

Track your mail order at each stage of production (and delivery) by utilizing our mail tracking, and get near real-time updates via our webhooks.

Once production is fulfilled by our printers, your mail will be on its merry way to be delivered to its final destination! Lob uses USPS for delivery in the US; as such, Lob does not have physical control over your mail once USPS has taken possession.

However, working hand-in-hand with USPS as our partner, Lob is able to provide granular digital tracking details of each individual mail piece as it moves towards its destination. As the mail makes its way through every distribution or sorting facility, or arrives at the area post office, USPS will send mail tracking details to Lob. Lob will then surface this information in near real-time, ensuring your mail pieces were delivered in a timely manner and received by the intended recipient.

Craft the best path forward

Depending on where you are in your quest for intelligent mail, or given your available budget or resources, there are multiple ways to leverage Lob's platform and accelerate your growth. Read on!

Learn about our platform

We're not your average direct mail experience. Explore Lob and see how we can meet your immediate needs for direct mail automation.

  • Dive right in: Send your first campaign via our easy-to-follow dashboard UI to get a feel for intelligent direct mail.

  • Explore our APIs! Check out our API quickstart quide to explore our APIs in your preferred programming language, explore our our Postman collection, and go to GitHub to access our supported SDK libraries.

Experiment with your inputs and outputs

Understand other ways in which you can up-level your direct mail program.

  • Explore how to operationalize dynamic personalizations to create mail pieces that can truly resonate with your audience

  • Experiment with different methods of mail sends and mail delivery strategy to see how to best increase relevance and conversion

  • Ingest mail tracking data, set up notification alerts via webhooks, or add QR codes to improve attribution and reporting

  • Access advanced features and more mail formats to improve audience responses as needed

  • Generate a campaign hypothesis, and build split-test or multivariate test cohorts to see which creative or campaign resonates with your segment

Enrich your data, connections, and processes

Explore our integrations so you can learn how to tap into your existing tech stacks and augment your datasets to expand the possibilities of creating seamless and timely omnichannel experiences with a touch of direct mail.

If you are a world-class technology company interested in partnering with us, learn more here.

Fast Track Guide

Even though the USPS loves working with us, they still have to charge for sending mail. Even if you are on the Developer edition of Lob, before you get started we'll ask you to input your payment information, then add Lob Credits, so you are prepared to send mail!

Step 1: How do you plan to execute your mail?

In the Lob dashboard
  • Send mail via Campaigns, our user-friendly interface built atop our APIs. We support one-time (1:many, targeted outreach), or automated (1:1, based on a trigger) campaigns.

Programmatically
  • API Documentation - Every developer knows that the path to getting a successful integration up and running starts here. You’ll be provided an example of each type of Lob API request and response, so you can build an integration that works for you/your team.

  • Campaigns API - What if you want to send large-scale direct mail campaigns but don’t want to execute them manually via the campaign tool? Well, you’re in luck! Learn how you can achieve the same efficiency but via the Campaigns API so you can automate your sends.

Step 2: Who are you sending to?

Audience
  • For a one-time campaign, you'll need your audience data (.csv); see here for how to format your addresses.

  • To set up and send automated or triggered campaigns, you'll want to connect directly to you customer data. Learn more about our Integrations here.

Step 3: What creative type are you going to be using?

HTML
  • Dynamic Personalization - One of the most powerful tools you have available to you when sending direct mail with Lob is the ability to make every piece unique to each recipient. Here are some tips on how to get the most out of Lob’s HTML capabilities.

  • Design Specifications - Whether you are sending a single postcard or millions of letters, our design guidelines will ensure your direct mail designs are created in the correct layouts and dimensions, so they’ll render exactly as expected when produced.

  • Best Direct Mail Campaigns - Get inspired by campaign examples from some of the best of the best.

  • Template Gallery - Not sure where to start? We’ve got you covered. Hit the ground running with several pre-made examples and even use them as a foundation to build your creatives.

PDF
  • Artboard Layout - Here are some design layout and dimension guides you’ll want to keep in mind.

  • Creative Formatting - Learn more about formatting and ensuring your artwork is print-ready.

  • Template Gallery - Not sure where to start? We’ve got you covered. Here you can take inspiration from several pre-made examples and even use them as a foundation to build your own unique creative

Step 4: How do you plan to measure the success of your mail?

Lob dashboard
  • Tracking - One of the most powerful advantages of using Lob is that you can have visibility of any individual mail piece as it moves across the entire print production and delivery process.

  • Mail Analytics - Every team measures unique insights to ensure you hit your targets. Discover a few views that cover some of the most important metrics you should care about.

  • Metadata - Gain a deeper understanding of your mail data at a mail piece, recipient, batch, or campaign level by adding your own data labels.

Custom analytics
  • Webhooks - Leverage webhook functionality to take asynchronous action and enhance your line of sight for the mail that is requested.

  • Metadata - Gain a deeper understanding of your mail data at a mail piece, recipient, batch, or campaign level by adding your own data labels.

Listrak

Overview

Listrak provides best-in-class email, SMS, behavioral marketing, cross-channel orchestration, predictive analytics, and customer insight solutions. Leverage all your channels – Email, SMS/MMS, social – including direct mail with Lob.

339KB
Lob + Listrak Overview.pdf
pdf

Salesforce Marketing Cloud

For more support related to our SFMC API integration, please contact your Account Manager or [email protected] to discuss your requirements and use case.

(Looking for a no-code integration option? See here.)

Custom mail

As a direct mail automation platform, Lob's focus is to offer set mail formats that can be programmatically sent at scale. These are postcards, self-mailers, snap packs, letters, and checks. However, for customers who need to send greater mail variations beyond these formats, we are open to exploring options with you.

Please reach out to your Account Manager for more information on program eligibility and requirements.

Maximizing engagement

To maximize engagement with your direct mail campaigns, we recommend leveraging dynamic personalization and integrating clear calls to action (CTAs) on each mailpiece. Including a coupon code, phone number, URL, or QR code is a powerful way to bridge the gap between offline and online experiences, driving more interaction with your brand.

Lob also empowers you to enhance your direct mail campaigns by leveraging USPS’s Informed Delivery service to create an additional digital touchpoint, giving your audience another opportunity to engage with your content before they even receive the physical mail.

  • Dynamic personalization

  • Adding QR codes

  • URL shortener

  • Informed Delivery

Send mail via Print & Mail API

See our API quickstart guide here!

Jotform

Overview

JotForm is an easy-to-use online tool for creating forms, surveys, and questionnaires without needing any coding skills. With its drag-and-drop interface, you can quickly design forms that look great and fit your needs. It comes with a ton of templates and integrates smoothly with other apps, making it handy for everything from gathering data to handling payments.

Whether you’re an individual or part of a business, JotForm offers flexibility and features that make form-building easy.

Getting Started

  • Lob Blog: How Jotform and Lob Can Help You Collect Better Data

  • Jotform’s Lob Address Verification widget allows your form respondents to check if they’re entering a correct address in your form’s address field. Check out the widget here.

  • Alternatively, using Zapier, set up the Jotform trigger, and make magic happen automatically in Lob.

USPS Promotions Through Lob

Welcome to Lob's USPS Promotions Help Center!

At Lob, we’re committed to helping you take advantage of every opportunity to save on postage costs. Each year, the USPS offers various promotions that provide discounts on mailing services, and we’re here to support you through the process of applying for and meeting the requirements for these offers. In this section, you’ll find detailed guides that walk you through each USPS promotion, helping you understand how to qualify, how to apply, and how our platform can seamlessly support you in the process. Whether you’re a seasoned mailer or new to USPS promotions, we’ve got you covered with all the information you need to maximize your savings.

Ready to start saving? Explore each promotion's guidebook to get started!

Adobe Marketo Engage

Overview

Marketo is a marketing automation platform that enables businesses to streamline and optimize their marketing processes, including lead management, email marketing, and campaign analytics.

Trigger Lob mailpieces from Marketo with webhooks

Create a Lob webhook within your Marketo instance.

  • See Marketo documentation on how to create a webhook.

  • Keep in mind:

1) The URL you enter for this webhook is going to be Lob's API endpoint for the resource that you're trying to create (e.g., postcard).

2) Choose JSON as the response type for passing Lob parameters and creative data.

  • You can copy and paste the JSON from Lob’s API documentation.

  • In the JSON, pass Lob parameters for the recipient name and address, mapped from Marketo.

  • Include creative data for the content you want to send.

Incorporate Webhhook into a Campaign:

  • Add the webhook to a campaign in Marketo.

  • Define trigger conditions for when the webhook should be activated.

  • Example Campaign: Create a campaign to send a Lob postcard when a specific attribute (e.g., person score) changes. For instance, if a person's score changes to zero, trigger the Lob postcard webhook.

For more detailed assistance, reach out to your Lob connection for personalized guidance on connecting Marketo and Lob.

Reaching your audience

The first step to any successful direct mail program is the ability to piece together an audience list for effective targeting. This is because reaching customers with direct mail that is relevant and contextual to their needs can maximize your responses and lead to high channel ROI.

The days of sending mail indiscriminately to every household within a given area using the "spray and pray" method are long over. However, good audience segmentation and targeting is heavily dependent on having quality data, which can impact how your mail is planned, produced, mailed, and converted.

Lob provides various ways to improve your address data hygiene and deliverability, offers connections to your , and can augment your first-party data with additional datasets to increase reach.

Purchasing Audiences

Viewing a Requested Audience

After an audience is requested, it will live in the Requested tab on the Audience Lists table. All requested lists will be accessible for 14 days, and then they will be permanently deleted if the list is not purchased. When a list has a status of "Processing", this means that we are still working on building the audience for you, and it cannot be purchased yet. Target lists typically take a few hours to process while Lookalike lists can take around 24 hours. When a list has a status of "Ready for Purchase", this means that the the count of records and cost of the list is ready for your review, and it is available for purchase. You will also receive an email when your audience request moves to the "Ready for Purchase" status.

Purchasing an Audience

You can click on any requested audience in the Audience Lists table to go to the detail page for the request. If the list status is "Ready for Purchase", then you'll see a summary of your request on the left and the order summary on your right. If the list status is still "Processing", then the order summary will be hidden.

The order summary will tell you how many records are in the audience list and the cost for the full audience list. You have the option to buy the full audience list or buy a subset of the audience list based on a specific budget. Once you enter your budget, we will automatically calculate how many records you can purchase within that budget. Lookalike Audiences offer one additional capability in the order summary which is the ability to expand or narrow audience reach by changing how related the new audience should be to the original file that was uploaded in the request form. Typically, the more closely related the new audience is, the more narrow the reach will be.

After opting in to Lob's terms and conditions in the Order Summary, you can click "Place Order" to complete the audience list purchase.

Exporting Addresses

After placing your order, your audience list will move to the Purchased tab on the Audience Lists Table. Your payment type and account type will dictate how quickly your audience list will become available for you to export. You will receive an email letting you know that the audience list is available.

  • If you used a credit card to purchase the list, the list will be available for export as soon as payment is received (generally within a few minutes)

  • If you used ACH to purchase the list, the list will be available for export within 3-5 days of ACH pull when payment clears

  • If you used invoice to purchase the list AND you are on an enterprise plan, the list will be available for export within a few minutes

  • If you used invoice to purchase the list but are not on an enterprise plan, the list will be available after the invoice payment is received

As soon as the list is ready for export, you can click on the list from the Purchased tab, and you will see an "Export" button in the top right corner. All audience lists will be available for export in the Lob dashboard for 180 days from the purchase date, and then they will be permanently deleted.

Building a mail strategy

Another crucial pillar of building your direct mail program with Lob is to determine your direct mail strategy.

Just like any other digital channel, using direct mail can help in attracting new customers and expanding your reach to your target audience. However, success is predicated on the careful cultivation and analysis of quality data, iterative testing, and creative content.

As an automation technology platform, Lob places the power of direct mail automation strategy directly in the hands of our customers. As a result, you have access to a broader set of tools at your disposal to better calibrate how you execute your direct mail campaigns, which can be optimized over time to create a highly performative channel.

Stop relying on spray-and-pray strategies that spams every mailbox, and start thinking about the most (cost) effective ways to get in front of the audience that matters the most with content that's actually relevant to them. Lob can be your partner in this journey.

Read the articles in this section to see what areas you can optimize in your mail sends.

  • One- time campaigns or triggered sends

  • ASAP, scheduled mailings, or target delivery

  • Managing your mail settings (use type, cancellation window, etc.) Sending

  • Sending

  • Sending

Exporting PDFs from InDesign

Best practices when exporting a PDF from InDesign

If you use Adobe InDesign to create PDFs for Lob, you can use this video to do some checks on your creative before it is sent to Lob.

  1. All fonts in your PDF should be embedded. If you are having trouble embedding your fonts, this is most likely because of a licensing issue. The preferred resolution would be to find/renew the font license but if that is not possible, you can always use InDesign to create an outline of the text. Remember that this option is to be used sparingly because it dramatically increases the size of the resulting PDF. (By default InDesign will embed fonts when exporting PDFs.)

  2. Image resolution should be 300 dpi for the best print quality; the video will walk you through adjusting the resolution.

  3. Images must use a CMYK color profile: GRACoL 2006 or GRACoL 2013. This will make sure that colors show up correctly in the final printed product. Setting the correct color profile also goes for any artwork/pictures that you import into InDesign as well.

  4. Flattening the transparencies is VERY IMPORTANT. If you fail to do this, certain artwork/pictures won’t show up in the final printed product. Make sure to set the option to “High Resolution” to cover any edge cases that may show up in your PDF.

  5. Keep your file size under 5MB. Tips on saving space include using text outline sparingly, not using a giant picture as the background, and making pictures/artwork the same size as will be used in the design.

  6. Run a diagnostic on the generated PDF. If you have Adobe Acrobat Pro, you can use the Preflight function under the Edit menu to run a report on your PDF. This will alert you to any issues. Set the profile to the “PDF-X/1a (GRACoL 2006)” and select “Analyze and Fix”.

Creative conversion tools

Import creatives for easy HTML templating

Struggling with HTML templates to leverage Lob's personalization feature? Can't find dedicated designers and engineers to convert your designs to HTML with each iteration? Fear no more!

You can now easily import your creative designs from popular design programs and quickly spin up merge variables. Take advantage of our full breadth of capabilities for hyper-personalization and leverage intelligent mail.

Our creative conversion tools are in beta and subject to change we ask that you reach out to your Account Manager or for access and support.

Ready to start AV?

If you've spent long hours preparing an audience list by appending data, you also know that your direct mail campaign can only be successful if your mail actually makes it to the recipient in the first place.

Similar to digital campaigns, physical mail campaigns need postal address verification so that physical mailers can check the accuracy of the addresses on their list, fix mistakes, and avoid undeliverable mail. Lob's Address Verification solution suite can ensure that submitted addresses are accurate and ready to be mailed, and reduce costly mistakes that end up undelivered and returned or thrown away.

Additionally, if your business is operating in a growing web of complex regulatory requirements, maintaining good address hygiene can play a critical role in meeting compliance and reducing friction in your customer experiences.

Here at Lob, our suite of products can help improve your business in the following ways:

  • Improve deliverability by ensuring the physical address in question is deliverable

  • Mitigate erroneous data inputs or fraudulent transactions through cleansing and verification

  • Validate recipient identity by ensuring individuals and businesses reside at their stated address

Read on for further information on our Address Verification suite.

Send mail!

This Help Center is a fantastic resource for learning all things Lob, and we recommend doing your homework. But once you feel ready...get set, and send!

Lob Audience

Lob Audience is the ultimate audience targeting tool for direct mail, enabling you to buy customized audience lists through a streamlined self-serve experience.

Navigating to Lob Audience

In the Lob dashboard, click on the “Audience” navigation and then on the “Audience Lists” sub-nav. From here, you can view all your purchased audiences, requested audiences, or create a new audience.

Creating an Audience

To create a new audience, click the “Create Audience” button at the top right of the Audience Lists page. From here, you’ll be asked what type of audience you want to create. We currently offer Target and Lookalike Audiences, and Pixel and Data Append Audiences will be coming soon.

Target Audiences

Utilize Lob’s Target Audience product to build audience lists targeted to specific geographic locations and customer traits. A name is the only required field for your audience, but we recommend utilizing our targeting capabilities for the best results.

Targeting by locations and traits

You can search a location by address, city, state, zip, or landmark. The search box will return a list of locations that match your search, and you can click the result that you would like to move forward with. Once a location is selected, it will appear under the location search box, and you can edit the name of the location and radius targeting from there. You can also manually pin a location by clicking the pin icon on the map and then clicking where on the map you want to drop the pin. You can search for or pin as many locations as you need to target, and if no location is added to your audience request, the entire US population will be included. Below locations, you'll find all the traits that we offer. You can target as many as you need for your audience.

Exclusion lists

Exclusion lists are an enterprise-only feature that allow you to avoid purchasing addresses for customers you already have access to. This feature is as simple as uploading a csv of the customers you would like us to exclude from the audience we build for you. The csv can have postal addresses, email addresses, or phone numbers. The more information that is included in the file, the higher likelihood that we can successfully find and exclude the customers.

After your exclusion list is successfully uploaded, we ask you what information is in the file, and then we ask you to tell us which columns in your uploaded file map to our required fields.

Submitting your audience request

After your desired filters are selected, click “Submit Audience Request” to actually submit your request. There is no cost to submitting a Target Audience request. You will be notified by email when your list is ready, and at that point, you can choose to proceed with purchase or not.

Agile CRM

Coming soon!

This platform is in closed beta. reach out to your Account Manager to enable or

is an all-in-one customer relationship management platform that helps businesses streamline their sales, marketing, and service processes.

By integrating direct mail into Agile CRM, you can enhance your multi-channel marketing strategy, reaching customers in a more personalized and impactful way. This combination allows you to engage with your audience both online and offline, driving higher response rates and improving overall campaign effectiveness.

No-code integrations are exclusive to our users on paid plans. Upgrade your to gain access, or contact our to learn more.

Choosing a SEND strategy:
Choosing a DELIVERY strategy:
Mailing class and postage
Certified or Registered Mail
International Mail
sign up here.
Agile CRM
Print & Mail edition
sales team
existing customer database
Cover

All about Addresses

Cover

Lob Audience

Cover

Campaign audience guide

Cover

Address Verification API

Cover

CRM Integrations

Cover

Additional Lob NCOA functionality

Cover

US Address Verification product suite

Cover

International Address Verification suite

API integrations

Leverage Lob functionality within your tech stack

If your team already uses any CDP, CRM, or marketing automation tool, consider adding a direct mail touch to your customer outreach sequences by integrating Lob into the following platforms. Use any of our external API integrations to easily leverage one of the most performative channels in marketing as part of your digital campaigns.

  • Adobe Marketo Engage

  • ActionIQ

  • Braze

  • Blueshift

  • Citrix Podio

  • Customer.io

  • Formstack

  • Hubspot

  • Iterable

  • Jotform

  • Klayvio

  • Listrak

  • Make

  • Optimove

  • Ortto (formally Autopilot)

  • Salesforce

  • Salesforce Marketing Cloud

  • Segment

  • SimonData

  • Tray.io

  • Zapier

Looking to connect to other automation tools you already use? Let us know here.

Action IQ

Overview

Grow faster with a new kind of Customer Data Platform (CDP). ActionIQ’s unique composable architecture gives marketers easy and secure ways to activate data anywhere in the customer experience.

ActionIQ + Lob = Integrate Offline and Online Customer Experience

The ActionIQ CX Hub empowers everyone to be a CX champion by giving business teams the freedom to explore and action on customer data while helping technical teams extend and enhance existing technology investments to manage data governance, costs and performance. AIQ CX Hub gives all teams direct but controlled self-service access to customer data to discover audiences and orchestrate experiences at scale.

Direct mail from Lob enables you to fully realize the CX potential of the AIQ CX Hub at the mailbox, providing flexible, automated direct mail production, delivery, and analytics, fully integrated with your CX stack.

Eliminate the Last Obstacle to Omnichannel Automation

The AIQ CX Hub orchestrates customer journeys across all channels and touchpoints, automated across hundreds of out-of-the-box integrations. However, due to limitations of legacy direct mail tools and lack of automation offline, omnichannel orchestration fails to reach its full potential, resulting in time-consuming execution, static content disallowing personalization seen in digital channels.

Lob automates direct mail production, enabling AIQ users to send direct mail when they need it, without downstream hassles or delays. That means you can orchestrate campaigns across all channels, with precise timing, personalization, and visibility.

Trigger Direct Mail Customer Experience in Real Time

The ActionIQ CX Hub provides robust trigger creation and activation capabilities, enabling you to deliver real-time outbound experiences across any channel based on any signal you chose, from streaming data like abandoned carts, to historical customer profiles like total spend.

Lob brings this capability to the mailbox, with unlimited customizability, quick processing and delivery, and tracking across the entire customer journey. Giving users the ability to trigger any message, design, or form factor based on any customer signal.

Orchestrate and optimize your campaigns

The AIQ CX Hub is a powerful tool for orchestration and optimization, enabling users to rapidly design, execute, test, and iterate on marketing and sales campaigns across multiple channels. However, legacy workflows and low visibility can cut direct mail out of the loop, forcing users to silo direct mail, and limit your ability to track results, improve campaign performance, and fully integrate mail into your multichannel or omnichannel workflow.

Lob’s API solves this problem, integrating fully with the AIQ CX Hub, enabling users to treat direct mail just like your digital channels. That means you can structure the customer journey, track ROI, test new strategies, and iterate your campaigns across all channels, without the need for a siloed direct mail track.

Keep Branding, Voice and Personalization Consistent, Online and Offline

The AIQ CX Hub provides powerful tools to shape and adapt your brand voice, while personalizing down to the microsegment. This gives you the ability to make the most of each touchpoint, while maintaining a single voice across all channels. Lob is able to then utilize all of the AIQ CX Hub intelligence to programmatically send personalized, timely, and quality mail pieces to your customers.

Is ActionIQ + LOB Right for You?

The AIQ CX Hub is designed for B2B and B2C companies with large customer bases and complex data needs across a wide range of industries, including financial services, retail, consumer packaged goods, grocery, travel & hospitality, healthcare, and B2B tech.

Lob caters to a wide range of both marketing and transactional use cases, from small businesses to multinational enterprises. For Lob users, whether or not you adopt a CX Hub depends on the factors above, as well as your use case.

Use Cases:

Marketing direct mail: If you need the ability to conduct multivariate testing, featuring 1-1 personalization and quick iteration capabilities, you’re more likely to benefit from a CX Hub. Typically, acquisition-focused marketing campaigns in particular can benefit from these capabilities.

Transactional or operational mail: Industries with heavily regulated customer communications will benefit from a CX Hub. For example, if you send financial statements, policy change notices, explanations of benefits, or bills through direct mail, a CX Hub can help ensure you’re meeting the legal requirements of each state, country, and region. Companies operating in multiple industries also tend to have complex regulatory obligations, which can benefit from the AIQ CX Hub.

Want to learn more? Please reach out to [email protected]

Blueshift

Overview

Blueshift has built a direct integration to Lob from within their platform. This empowers marketers to automatically send personalized behavior-triggered mail to every user, on demand.

  • Read more about the integration in the Lob + Blueshift integration factsheet.

  • Instructions on how to connect Blueshift and Lob can be found in Blueshift's documentation here.

USPS Secure Destruction

Secure Destruction is a free service provided by the United States Postal Service (USPS) that offers a secure method for handling undeliverable First-Class mail. This service is especially beneficial for customers managing sensitive documents, such as those containing Personal Identifiable Information (PII), financial data, or medical information, while also helping reduce costs and environmental impact.

What is Secure Destruction?

Secure Destruction ensures that any undeliverable First-Class mail is securely destroyed at USPS facilities. Rather than being returned to the sender, mail is processed and eliminated under strict security protocols, preventing any potential unauthorized access.

Lob provides this service at no cost to customers who send First-Class mail, and it can be easily integrated into existing workflows for organizations that regularly deal with undeliverable mail.

Why Use Secure Destruction?

  1. Enhanced Customer Security Secure Destruction offers a significant value-add for organizations that handle sensitive customer data, such as PII, financial records, or medical information. By ensuring that undeliverable mail is destroyed securely, companies can maintain compliance with data protection regulations, reduce the risk of breaches, and improve customer trust.

  2. Cost Savings Secure Destruction helps customers avoid the financial burden of handling undeliverable mail. For example, companies that do not use this service may need to contract with third-party vendors or allocate in-house resources to manage the destruction of returned mail.

  3. Reduce Environmental Footprint Secure Destruction also offers environmental benefits by eliminating the reverse logistics of returning mailpieces to senders. By preventing the need for transportation and manual disposal, carbon emissions are reduced. This aligns with Lob's sustainability mission to minimize the environmental impact of mail processing.

How Secure Destruction Works

Secure Destruction is available exclusively for First-Class letters and snap packs. If your organization sends these types of mail, you can easily enable Secure Destruction through your account page. Once activated, any undeliverable First-Class mail will be securely destroyed at USPS facilities, ensuring your sensitive documents are handled with the highest level of security.

Who Benefits from Secure Destruction?

Secure Destruction is ideal for First-Class mailers, particularly those who manage sensitive information or face significant logistical challenges in processing undeliverable mail. This includes:

  • Financial institutions

  • Health care providers

  • Insurance providers

  • Public and private education institutions

  • Government agencies

  • Utility companies

  • Mail service providers

  • Legal service providers

Once your organization opts into Secure Destruction, Lob will track your undeliverable mailpieces via USPS scanning events. You will be able to confirm that the mail has been destroyed through these tracking events, offering you peace of mind that your sensitive documents have been successfully processed by USPS.

AV integrations & libraries

AV integrations

  1. AV Elements

  2. Shopify app: Address Cleanser

  3. Airtable app: Address Cleanser

  4. Zapier

  5. JotForm (from our blog)

SDKs & libraries

  1. Libraries: Ruby, Node.js, PHP, Python

  2. Postman collection

Zoho

Coming soon!

This platform is in closed beta. reach out to your Account Manager to enable or sign up here.

Zoho is a versatile CRM platform that helps businesses manage their sales, marketing, and customer support with ease.

By adding direct mail to your customer journey in Zoho, you can enhance your outreach strategy with a personal, tangible touch, making your customer interactions more memorable and impactful. This integration bridges the gap between online and offline communication, driving stronger engagement and deeper customer connections.

No-code integrations are exclusive to our users on paid plans. Upgrade your Print & Mail edition to gain access, or contact our sales team to learn more.

Freshsales Suite

Coming soon!

This platform is in closed beta. reach out to your Account Manager to enable or sign up here.

Freshsales Suite is an intuitive CRM platform that helps businesses manage their sales, marketing, and customer relationships in one place. By adding direct mail into your customer journeys you can create a more personalized and engaging customer experience, complementing your digital outreach with impactful offline interactions. This integration allows you to reach your audience in multiple ways, driving stronger connections and better results.

No-code integrations are exclusive to our users on paid plans. Upgrade your Print & Mail edition to gain access, or contact our sales team to learn more.

Pipedrive

Coming soon!

This platform is in closed beta. reach out to your Account Manager to enable or sign up here.

Pipedrive is a user-friendly CRM designed to help businesses manage and streamline their sales processes. By integrating direct mail into your customer journey with Pipedrive, you can add a personal touch that complements your digital efforts, making your outreach more engaging and effective. This combination ensures you’re reaching your customers in multiple ways, helping to close deals and strengthen relationships.

No-code integrations are exclusive to our users on paid plans. Upgrade your Print & Mail edition to gain access, or contact our sales team to learn more.

Simon Data

Overview

Simon Data is a customer data platform (CDP) that enables businesses to leverage their data to create personalized marketing campaigns and drive customer engagement.

Lob + Simon Data: Drive growth everywhere

Simon Data brings a simple, highly effective workflow to multi-channel marketing. Through its powerful CDP, Simon allows marketers to integrate data from any source, unify customer profiles, segment in real time, and orchestrate customer journeys across all marketing touchpoints. Lob empowers Simon users to coordinate direct mail with their online channels, using consistent and personalized messaging to drive customer loyalty and engagement across email, SMS, push, and other digital channels.

Turn first-time customers into life-long brand advocates

Simon Data’s powerful B2C marketing orchestration capabilities empower your marketing team to provide consistent, relevant messaging throughout the customer lifecycle. Simon combines powerful, predictive modeling with sophisticated testing and experimentation. The result is a system that enables you to maximize engagement, fine-tuning each customer journey with the right messaging, touchpoints, and product recommendations. Lob enables you to fully harness Simon’s capabilities offline, bringing automated direct mail production, personalization, and analytics to your multi-channel stack. That means you can truly engage with customers, build loyalty, and drive CLTV across all channels, all from a single hub.

Do away with silos, disconnects, and workarounds

40% of marketers rate their “inability to link different technologies” as a top technological challenge. Siloed data, disconnected channels, incompatible schemas, and the sheer complexity of your marketing stack can hamstring your marketing team. You can’t engage customers in real-time if you’re forced to wait on manual data pulls, or slog through elaborate workarounds. Legacy direct mail in particular is a major pain point, because it is almost completely siloed. The slow cadence and separate, manual workflow of legacy DM prevent marketers from fully integrating it with digital channels into a coherent customer journey.

Simon’s CDP provides a unified customer view to your marketing workflows, coordinating all your tools and data sources into a seamless whole. Targeted communications are infused with historical and real-time data, supported by robust segmentation and personalization capabilities. Lob integrates fully automated direct mail into Simon, enabling you to plan, execute, and track your omnichannel campaigns with a single workflow. That means you can focus on getting the right content to the right audience across the right touchpoints.

Turn marketing optimization into a science

Traditionally, direct mail optimization is limited compared to digital channels. Most companies using legacy direct mail have little ability to personalize letters or track results, forcing them to rely on less effective techniques like mass mailers. Lob provides 100% personalization for every mailpiece, and enables you to track deliveries and conversions just like you would with email. Combining Lob’s direct mail automation with Simon’s powerful optimization and orchestration capabilities lets you truly optimize your multi-channel campaign.

Simon’s native integration with Lob supports triggered campaigns for a variety of loyalty and retention use cases. and streamlines workflow for both technical and non-technical stakeholders. Marketers can get hands-on with customer data, experiment and execute campaigns, and analyze results all within the same UI. And your team can conduct the same experiments, tests, and analyses on DM campaigns as they would for any digital channel.

Identify and engage customers on their own terms

Consumers are harder to track than ever before. They research products and engage with brands across multiple channels, devices, and accounts, making it difficult to identify individuals and tie together interactions. At the same time, they expect a highly personalized experience from the brands they interact with. Simon Data solves your identity resolution challenges with Simon Identity. This enables you to merge multiple customer interactions into a single profile, without depending on a single identifier like email address. Lob augments this capability with automated address verification, so you can engage with your customers online and offline.

Are Simon Data + Lob right for you?

Simon Data is a powerful CDP designed around the unique needs of B2C marketing. With powerful native tools and extensive integration, it can serve a range of use cases, including:

  • A centralized hub to unify and consolidate your customer data sources

  • A self-service automation and segmentation tool, enabling marketers to fully utilize their data without depending on the help desk

  • A rapid testing and optimization toolset to fine-tune and personalize customer experience

  • A sophisticated data integration and governance platform, managing your entire customer data ecosystem

Because Simon Data serves so many roles, Lob users in B2C industries should weigh Simon Data’s capabilities against their current pain points and tech stack functionality to identify use cases.

See our full PDF preflight checklist here.
contact us
Cover

Figma-to-Lob

Cover

Indesign-to-Lob

Cover

Templify (PDF-to-HTML)

Cover

Send via the Lob Dashboard

Cover

Cover

Send via Campaigns API

Cover

USPS Secure Destruction

Certified Mail or Registered Mail

Certified Mail

Certified Mail is an add-on service offered by USPS for First Class mail that provides proof of mailing to the sender. With electronic USPS tracking, the sender is notified when the mailing was delivered or that a delivery attempt was made. An electronic return receipt showing the recipient's signature is also available for Certified Mail only. Both the Certified Mail and the electronic return receipt add-ons are only available for First Class mail sent domestically within the US.

You send letters as Certified Mail through the Lob API by passing the value certified in the extra_services parameter of the create letter request. You may similarly opt for an electronic return receipt by passing certified_return_receipt in the extra_services parameter in the API.

Tracking events are viewable directly within the Lob dashboard or via the API, similar to how they are for non-Certified letters, and you can also subscribe to webhook events for Certified letters. When you make a request for Certified Mail you will immediately receive a carrier tracking number (retrievable via your Lob dashboard), which can be used to track the mail via the carrier’s website - or you can choose to track the mail via the scan events within your Lob dashboard. The resulting screen should appear in your dashboard:

Tracking events for Certified Mail are different from tracking events received for regular mail types; see the full list in our API documentation for Certified tracking event details.

Visit the Certified Mail envelopes section for more guidance around sending Certified Mail.

Electronic Return Receipts

An Electronic Return Receipt is available to the sender as a USPS add-on to Certified Mail. This receipt will allow you to download a digital copy of the recipient's signature used to sign for the delivery of the letter. You opt for an Electronic Return Receipt by passing certified_return_receipt in the extra_service parameter of creating a letter.

The return receipt will be accessible via the certified tracking number from the USPS homepage. However, if you would like to receive the signature PDF via email, follow these steps:

  • Visit www.usps.com

  • Enter the Certified tracking number into the Track a Package box

  • Click the "Return Receipt Email" dropdown and fill the required fields in the form

  • The USPS will send you an email with the signature file like the below example

Registered Mail

The USPS Registered Mail add-on is only available for First Class mail and can only be sent (and tracked) domestically.

Registered Mail is an add-on service offered by USPS that provides extra protection for high-value letters and packages. When you send a letter by Registered Mail, the USPS establishes a chain of custody that tracks and secures your shipment throughout the entire transit process—from the moment it is dropped off at the Post Office until the moment it’s delivered.

You can send letters as Registered Mail through the Lob API by passing the value registered in the extra_services parameter of the create letter request.

Letters sent as registered will receive a different set of scan events compared to regular First or Standard Class mail. Registered Mail will instead receive a carrier tracking number and link, which is an add-on that will be available 3 business days following the mailer’s send_date. This tracking number can be used to track the mailer via the carrier’s website.

Integrations

Integrate Lob with your existing tech stack to maximize the effectiveness of your direct mail campaigns

CRM/CDP/MAP integrations

Customer data platforms (CDPs) serve as a source of truth for customer data, while customer relationship management systems (CRMs) manage customer relationships for sales. By using data piped from these systems, marketing automation tools can orchestrate multichannel campaigns based on the customer journey, or sequence business workflows, triggered by user actions, events, milestones, or other logic.

Lob integrations enable automated trigger-based campaigns, so you can incorporate direct mail into your omnichannel marketing campaigns and make operational workflows more efficient.

We offer two types of customer data integrations optimized for your direct mail strategy, technology stack, and available resources.

Design tool integrations

We are continually enhancing our capability to convert creative from popular design tools into HTML, to empower more users to benefit from the personalization that HTML provides.

HubSpot

Overview

HubSpot has a customer relationship management (CRM) tool that helps companies manage their contacts, deals, and tasks.

The HubSpot integration with Lob allows you to automate direct mail campaigns within the Lob dashboard, based on any change within your HubSpot instance.

No-code integrations are exclusive to our users on paid plans. Upgrade your Print & Mail edition to gain access, or contact our sales team to learn more.

How to connect Lob to HubSpot

  1. Within the Lob Dashboard, navigate to the Integrations page and click on the “HubSpot” tile view the HubSpot details page. Click on the “Connect” button to begin.

  2. This will open a modal to create a new HubSpot account or sign in to an existing one. If you’re already logged into HubSpot in another window or tab, it may auto-detect. Enter the credentials for the HubSpot account you want to connect.

  • The account used must have permission to share Contact information to authenticate.

  1. After authentication, Lob will begin the ‘Connect’ phase, reading your HubSpot schema. This async process may take a few minutes, depending on the size of your HubSpot instance. You will receive an email when it’s complete.

  2. Once you have successfully connected your Hubspot account to Lob, the label will show “Connected."

  • After the initial connection, Lob will update to pull the latest schema from your account. Changes to HubSpot objects or columns will be reflected once complete.

  • This can also be completed manually if you need to pull in these changes prior to building a campaign: From the Integrations page, then the HubSpot Integration Details page, click “Refresh Schema."

Once you’ve successfully connected Lob to your Hubspot account, you are ready to begin the Campaigns workflow. See set up an Automated campaign for a general overview, or watch the detailed video tutorial below.

Set up an automated campaign in Hubspot

Additional notes

  • After the initial connection, Lob will update to pull the latest schema from your account. Changes to HubSpot objects or columns will be reflected once complete.

  • This can also be completed manually if you need to pull in these changes prior to building a campaign: From the Integrations page, then the HubSpot Integration Details page, click “Refresh Schema."

Pricing details

Get started with a platform subscription, paired with unit cost for mail pieces. Features vary depending on the pricing Edition.

Monthly subscription

Developer
Startup
Growth
Enterprise

Mail piece unit pricing

Recent USPS postage rate changes have taken effect as of July 13, 2025. These adjustments are part of USPS’s regularly scheduled pricing updates, designed to account for inflation and rising operational costs. Lob doesn’t add fees when USPS rates go up – only the postage rate increases apply. You can find more details outlined in the .

Postcards

Prices are inclusive of print, postage and envelopes (where applicable).

Mail format
Developer
Startup
Growth
Enterprise

Self-Mailers

Prices are inclusive of print, postage, and envelopes (where applicable).

Letters

Prices are inclusive of print, postage and envelopes (where applicable).

Mail format
Developer
Startup
Growth
Enterprise

* Extra postage fees for 8.5x11 letters over 6 sheets (6 pages single-sided, or 12 pages double-sided) and 8X14 letters over 3 sheets (3 pages single-sided, or 6 pages double-sided)

Snap Packs

Prices are inclusive of print, postage, and envelopes (where applicable).

Checks

Prices are inclusive of print, postage, and envelopes (where applicable).

Mail format
Developer
Startup
Growth
Enterprise

Questions about pricing? Reach out to your Account Manager or our .

Designing mail creatives

Making your design mailable

The first pillar of building your direct mail program with Lob is to design your mail creatives.

Creating a well-designed mail piece can elevate your brand amongst other mail pieces in the mail box, communicate your value prop effectively, and actually deliver results. Design applies to imagery as well as text and copy, and a clear, easily identified CTA or promotion can make a material difference in the level of responses you may receive.

When sending programmatic mail through the Lob platform, it is important to make sure that digital designs can effectively translate into physical print with the right set of instructions, whether they are static or dynamic creatives.

Anatomy of a mailpiece

When you send an API request to Lob, you are sending 3 pieces of information:

  1. the "To" address,

  2. the "From" address, and

  3. the content.

This section contains some best practices to follow when designing creative content for Lob. Read on to learn more about each of the design components needed in your mail creatives.

Optimove

Overview

In heavily data-driven industries, the customer journey is the destination. It’s not enough to be able to nurture leads, win conversions, and retain customers — you need to continuously engineer and optimize your customer relationships to keep customers engaged over many, many touchpoints.

It’s these industries where Optimove really shines. Optimove is more than just a CRM — it’s a Cross-Channel Campaign Management platform built to drive your entire marketing process. Combined with Lob, Optimove can drive strong customer relationships online and offline, integrating direct mail and digital marketing into a seamless whole.

Drive sustained engagement across every channel

Sustaining high customer engagement depends on centralized orchestration, backed by data-driven insights. Optimove provides a hub for all of your relationship marketing channels, orchestrating campaigns across all owned channels. Powerful analytics and a cutting edge decisioning engine enable you to react to customer signals in real time, making the most of every interaction.

Lob adds next generation direct mail automation, with the power, convenience, and speed of a digital channel. You can dynamically personalize and trigger mailpieces to drive conversions, nurture relationships, and capitalize on every customer action and interaction.

Optimize effortlessly

Customer demand is always changing. To keep up, high-frequency businesses need to treat each interaction as a chance to collect data, test strategies, and analyze outcomes.

Optimove uses test and control groups to turn every interaction into a learning opportunity. Built-in AI and machine learning constantly crunch the data, providing an endless flow of data-driven optimization insights.

Lob completes the picture, bringing total visibility to your direct mail campaigns. You can track receipts, conversions, and delivery times for every mailpiece just like with digital channels.

Empower non-technical marketers with data-driven insights

You don’t need to be a mechanic to drive a high-performance car, and you shouldn’t need to be a technical savant to use a high-performance CCCM. Optimove consolidates customer data into a custom data model, built for your business, industry, and priorities, driving deep insights for even non-technical users.

Lob replaces complex legacy direct mail workflows with an automated system, using our nationwide network of print partners. That means you don’t need to build your direct mail strategy around the limits of your print partner, or the peculiarities and cadence of your internal workflow.

Together, Lob and Optimove enable non-technical users to see, interact with, and serve customers like never before — without having to dive under the hood or work around archaic workflows. That means less time working around the limits of your tools (and your help desk), and more time growing your business.

Are Optimove + Lob right for you?

Optimove is ideal for data-driven companies, including:

  • High-bandwidth communication: Organizations that need to be able to automate and orchestrate simultaneous messages across many channels, or scale up their communication strategy

  • High Frequency interactions: Companies that have many interactions with customers, such as frequent purchases, media streaming, and gaming

  • Promotion-heavy brands: Organizations that need help gauging the impact of promotions, and optimizing their promotion strategy

  • Replenishable products: Pet food, gaming deposits, subscriptions, and telecommunication services where customers need to frequently replenish the product

Lob is designed for any organization looking to automate direct mail, improve personalization capabilities, or better integrate direct mail with their technology stack. Lob provides unlimited scalability, so you can send as many or as few mailpieces as you need to without having to plan and purchase printing capacity ahead of time. This makes Lob a perfect fit for small startups and nonprofits, massive multinationals, and anything in between.

Want to learn more? Please reach out to

Additional resources

  • Lob & Optimove: blog post

  • Lob & Optimove: , we sat down with Pini Yakuel, Founder and CEO of Optimove, to discuss how marketers can embrace AI to create successful marketing campaigns.

Custom Fonts

When you translate your designs from Figma to Lob, sometimes the fonts you've chosen might not be publicly available. If your brand uses a custom font (ie. fonts not available at ), we need access to the versions of that font you’re using in order to port your dynamic creative to Lob. Don't worry—we've laid out instructions for how to host custom fonts yourself here:

Step 1: Collect Your Font Files

You will need every variation of the custom font used in the file. This means any combination of weight and style.

Let’s say for the purposes of demonstration, we’re using font family Lato with regular, bold, and regular-italic variations.

🍎 On a Mac:

  1. Open Finder.

  2. Press Cmd + Shift + G.

  3. Type or paste the following paths:

    • System Fonts: /System/Library/Fonts

    • User-installed Fonts: ~/Library/Fonts

    • All Users (Shared): /Library/Fonts

Copy your custom font files (.ttf, .woff, .woff2) from these folders.


🪟 On Windows (PC):

  1. Open File Explorer.

  2. Navigate to:

  3. Copy your custom fonts from here.

*OTF files are not supported, translate them to ttf or woff first!

Step 2: Host the Font Files

  • Upload each font variation to an external hosting service

  • Ensure your files are publicly accessible, meaning anyone can access the file from anywhere.

In our example, we would have URLs for lato-regular.woff2, lato-bold.woff2, and lato-regular-italic.woff2

Step 3: Create a Spreadsheet (CSS file)

You'll create a file named after your font family, like lato.css. This file tells Lob how to use your fonts. Key components include:

  • font-family : will always be set to the name of your font

  • src: the URL at which your font is hosted

  • font-weight: the “boldness” of the font variation

  • font-style: either ‘normal’ or ‘italic’

Font weights:

Example content of lato.css:

Step 4: Host Your CSS File

  • Upload your CSS file to the same external hosting site

  • Again, make sure the link to your CSS file is publicly accessible.

Step 5: Include Your CSS File in Your HTML

Back in Figma to Lob, when you export, you will be given a prompt to map the file to the CSS

Getting data & results

The final pillar of building a successful direct mail program is the ability to continuously iterate--to measure your baseline performance, and keep optimizing your direct mail performance with data and results gained from your sends.

Lob offers you ways to gain unprecedented visibility into where every single individual mail piece is moving in the delivery mailstream, and can alert you with notifications at each stage so that you can build sophisticated downstream workflows and processes based on these alerts. You can also define, search, and slice and dice your mailpiece data in any way you see fit, to better understand channel performance and attribution.

Mail piece design specs

Browse our available mail formats and associated design specs:

Snap packs

A snap pack is a pressure-sealed mailer with perforated sides for easy opening. Snap pack mailers are versatile and can be used by a wide range of industries including Financial Services, Education, and Healthcare. The official-looking nature of snap packs demands attention, offers unique tactile engagement, and has one of the highest open rates among mail types.

To get started with snap packs, check out our ,or for inspiration.

Snap packs are exclusive to Enterprise edition customers. Upgrade your to gain access to this mail format, or reach out to our to learn more.

Snap packs currently have a 4-day SLA.

Layout dimensions & specs

Layout dimensions

Lob’s snap pack offering has a flat, final trim size of 8.5x11”, a folded (in half) dimension of 8.5x5.5", and three perforated sides. Snaps packs are printed double-sided in black and white or color.

Reference our design templates on where to place your design elements; carefully note the location of the address block and other ink-free zones.

Snap packs DO NOT need additional trim space added to their dimensions because their production journey does not involve trimming (the way a postcard would). Please set your document sizing to the above dimensions when submitting to Lob.

Make sure all artwork submissions are facing upright for both inside and outside panels. Our printers will invert the inside panel of submitted customer artwork during the production phase.

Paper specs

We use a few pre-approved papers across our commercial printer network. In ensuring uniform quality and consistency across all of our mail pieces, each paper source specification must fall within a small range.

The specification/value range pairs are:

  • 8.5 x 11" B&W & color snap packs

  • Basis Weight: 80# text

  • Bi-fold

Ink-free zone dimensions

8.5x11" snap packs:

  • ½” around the entire flat piece (for perforation)

Snap pack best practices

Ensure your snap pack self-mailers get to their final destination by following these guidelines:

  • The from field is required for all self-mailers, regardless of the destination

  • Snap pack should not contain any PII outside of the

  • Avoid any to ensure your mail does not get rejected by USPS

  • HIPAA-compliant snap packs are offered at this time, so long as all HIPAA related information is on the inside of the snap pack.

  • options may differ based on destination and use type (e.g. promotional vs non-promotional)

  • We do not recommend placing promotional address information in your creative in the bottom 2.375" of a mailpiece opposite the address panel. This will prevent the USPS from accidentally scanning the wrong side of the mailpiece.

International AV suite

Lob's Address Verification API provides a comprehensive solution for businesses looking to optimize their international customer experiences and make more informed decisions about their international address data.

International verifications

Validate, automatically correct, and standardize non-US international addresses. See our for details.

We follow for sending international mail. Therefore, any addresses submitted in a language other than English will see the address returned in English.

Supported international countries

See our most up-to-date list of for our International Address Verification API.

International deliverability insights

Lob's International Deliverability provides greater visibility into an address’s delivery response so customers can make more informed decisions about how they manage international address data. Customers are able to understand when a portion of the address has been corrected and if it has resolved the deliverability issues. To leverage this data, review the complete under Status.

International autocomplete

International address autocompletion for non-US addresses is not currently available. If you believe this feature is integral to your business, please reach out to to see if we can support your needs.

Configurable transliteration

Configurable Transliteration provides Address Verification customers greater flexibility and customization when operating around the world. Lob ensures that addresses are correct and deliverable while providing optionality for the address response to be in the native language. This means a customer is able to provide cart checkout messaging that adapts based on where the end customer is located thus creating a more personalized experience. It also means that when working with foreign languages with non-Latin characters the data is seamlessly transliterated and mapped for normalized data storage.

To customize your language response, review the complete under x-lang-output.

Global AV data coverage

Country Coverage equips Lob customers with the details needed to make an informed decision about a deliverable address and the potential for false positives. The International Address Verification API provides validation to varying degrees of granularity depending on the country the address is in. Country Coverage indicates the level to which an address has been verified. To leverage this information, review the under Coverage.

View our most updated here.

Salesforce

Overview

Salesforce is a customer relationship management (CRM) platform that helps businesses manage customer interactions, track sales, and automate various business processes.

The Salesforce integration with Lob allows you to automate direct mail campaigns within the Lob dashboard, based off any event trigger change that occurred within your Salesforce account.

No-code integrations are exclusive to our users on paid plans. Upgrade your to gain access, or contact our to learn more.

How to connect Lob with Salesforce

  1. Within the Lob Dashboard, navigate to the Integrations page and click on “Salesforce” to view the Salesforce connection page. When on the Salesforce page, click the “Connect” button to begin.

  2. This will launch a modal to sign into your Salesforce account. Any Salesforce accounts you have previously used may be automatically detected. When prompted, enter the credentials to the Salesforce account you wish to connect.

  • Your organization must be on a paid Salesforce plan/tier with API access enabled.

  • The user in the account must have Admin level permissions, with access to the tables needed.

  1. Once the account is authenticated, Lob will start the ‘Connect’ phase, and will read the schema of your Salesforce instance. (This is so you can use the objects and columns later when setting up a campaign.) Depending on your Salesforce instance’s size, this may take a few minutes but runs asynchronously, requiring no active monitoring.You will receive an email when this is complete.

  2. Once you have successfully connected your Salesforce account to Lob, the label will show “Connected”.

Once you’ve successfully connected Lob to your Salesforce account, you can from within the Campaigns flow.

Lookalike Audiences

Utilize Lob’s Lookalike Audience product to build an audience that looks similar to your existing high-converting customers. An audience name and a CSV upload of your existing customers are the only required information for this audience type.

File upload

A lookalike audience is an audience that is modeled off of your first party data, so we require that you upload that data in the request form. Please ensure that you read our file requirements, as any datasets that don't adhere to them will likely result in us not being able to build a Lookalike Audience. The file requirements for your first party data are:

  • Contains at least 2,000 customers

  • Ideally includes name, postal address, phone number, + email. At a minimum includes one of the below combinations:

    • Name + postal address

    • Email

    • Name + phone number

  • Includes customers who have shown intent (ex: recently purchased)

  • Only includes B2C data

  • Data is accurate and complete

After your file is successfully uploaded, we ask you what information is in the file, and then we ask you to tell us which columns in your uploaded file map to our required fields.

Targeting by locations and traits

Location and demographic targeting is optional. The location search box will allow you to search any US state, and you can add as many states as you need. If no state is added, all US states will be included in the Lookalike audience. Below locations, you'll find all the traits that we offer. You can target as many as you need for your audience.

Exclusion lists

Exclusion lists are an enterprise-only feature that allow you to avoid purchasing addresses for customers you already have access to. This feature is as simple as uploading a csv of the customers you would like us to exclude from the audience we build for you. The csv can have postal addresses, email addresses, or phone numbers. The more information that is included in the file, the higher likelihood that we can successfully find and exclude the customers.

After your exclusion list is successfully uploaded, we ask you what information is in the file, and then we ask you to tell us which columns in your uploaded file map to our required fields.

Submitting your audience request

After your file is uploaded and desired filters are selected, click “Submit Audience Request” to actually submit your request. There is no cost to submitting a Lookalike Audience request. You will be notified by email when your list is ready, and at that point, you can choose to proceed with purchase or not.

Learn more here
Contact us
Contact us
Send via Print & Mail API

Monthly

–

$260

$550

Talk to Sales

Annual

–

$225

$480

Talk to Sales

Monthly supported mailings

Up to 500

Up to 3,000

Up to 6,000

Talk to Sales

4x6, First Class

$0.872

$0.612

$0.582

Talk to sales

6x9, First Class

$0.993

$0.673

$0.623

Talk to sales

6x11, First Class

$1.259

$0.919

$0.879

Talk to sales

6x9, Standard Class

$0.966

$0.646

$0.596

Talk to sales

6x11, Standard Class

$1.026

$0.696

$0.646

Talk to sales

5x7, First Class

_

_

_

Talk to sales

5x7, Standard Class

_

_

_

Talk to sales

International 4x6 Postcard Fee

$1.440

$1.379

$1.379

Talk to sales

12x9 Bifold, First Class

_

_

_

Talk to sales

12x9 Bifold, Standard Class

_

_

_

Talk to sales

6x18 Bifold, First Class

_

_

_

Talk to sales

6x18 Bifold, Standard Class

_

_

_

Talk to sales

11x9 Bifold, First Class

_

_

_

Talk to sales

11x9 Bifold, Standard Class

_

_

_

Talk to sales

17.75x9 Trifold, First Class

_

_

_

Talk to sales

17.75x9 Trifold, Standard Class

_

_

_

Talk to sales

Black & White Letter, First Class

$1.029

$0.859

$0.829

Talk to sales

Color Letter, First Class

$1.189

$0.899

$0.859

Talk to sales

Black & White Letter, Standard Class

$0.806

$0.636

$0.606

Talk to sales

Color Letter, Standard Class

$0.966

$0.686

$0.636

Talk to sales

Black & White Additional Page (pdf page)

$0.10

$0.09

$0.08

Talk to sales

Color Additional Page (pdf page)

$0.20

$0.19

$0.16

Talk to sales

Letter over 6 sheet fee

$2.435

$2.435

$2.435

Talk to sales

Perforation

$0.06

$0.02

$0.02

Talk to sales

Return Envelope

$0.04

$0.04

$0.04

Talk to sales

Custom Return Envelope

$0.05

$0.05

$0.05

Talk to sales

Int'l Letter Postage (1st Class Only)

$1.18

$1.18

$1.18

Talk to sales

Certified Mail (1st class only)

-

$6.7

$6.7

Talk to sales

Electronic Return Receipt

-

$2.62

$2.62

Talk to sales

Certified Mail With Electronic Return Receipt

-

$9.52

$9.52

Talk to sales

Registered Mail (1st class only)

-

$23.30

$23.30

Talk to sales

Legal Letters (B/W), First Class

-

-

-

Talk to sales

Legal Letters (B/W), Standard Class

-

-

-

Talk to sales

Legal Letters (Color), First Class

-

-

-

Talk to sales

Legal Letters (Color), Standard Class

-

-

-

Talk to sales

Paper card affix

-

-

-

Talk to sales

Buckslips

-

-

-

Talk to sales

Snappack (B/W), First Class

-

-

-

Talk to sales

Snappack (B/W), Standard Class

-

-

-

Talk to sales

Snappack (Color), First Class

-

-

-

Talk to sales

Snappack (Color), Standard Class

-

-

-

Talk to sales

Checks

$1.159

$1.009

$1.009

Talk to sales

Check Attachment Page

-

$0.220

$0.220

Talk to sales

Check over 6 Sheet Fee

-

$2.435

$2.435

Talk to sales

USPS Press Release
Sales team
[email protected]
Precision and Profit: How Predictive Analytics Supercharges Direct Mail Campaigns
In episode 21 of the Lob Podcast
API documentation
Template Gallery
Print & Mail edition
sales team
8.5x11” snap pack template
no-ink zone
prohibited artwork
Mailing Class
Learn more here.
API reference
USPS standards
global address coverage
API documentation
support
API documentation
API documentation
Global Address Coverage
Print & Mail edition
sales team
set up an Automated campaign
Cover

Artboard layout

Learn the do's & don'ts of your mail creative when building your layout templates

Cover

Creative formatting

Everything you need to know on file, font, & image formats used in Lob's mail pieces

Cover

Mail piece design specs

See the available mail types and relevant specs needed to send programmatic mail

Cover

Dynamic personalization

Say goodbye to static creatives by building dynamic creatives with HTML

C:\\Windows\\Fonts
@font-face {
  font-family: 'Lato';
  src: url('<https://yourwebsite.com/fonts/lato-regular.woff2>') format('woff2');
  font-weight: 400;
  font-style: normal;
}

@font-face {
  font-family: 'Lato';
  src: url('<https://yourwebsite.com/fonts/lato-bold.woff2>') format('woff2');
  font-weight: 700;
  font-style: normal;
}

@font-face {
  font-family: 'Lato';
  src: url('<https://yourwebsite.com/fonts/lato-regular-italic.woff2>') format('woff2');
  font-weight: normal;
  font-style: italic;
}
https://fonts.google.com/
Cover

Tracking your mail

Cover

Getting notifications via webhooks

Cover

Mail analytics and reporting

Cover

Measuring attribution

Cover

Exporting mail data

Cover

Postcards

Cover

Self-Mailers

Cover

Letters

Cover

Letter Envelopes

Cover

Letter Add-ons

Cover

Checks

Cover

Snap Packs

Cover

Booklets

Cover

Custom Mail

API integrations

No-code integrations

Design integrations

Cover
Cover
Cover

Measuring attribution

Marketing attribution is important in measuring performance for any channel, online or offline, because it helps to understand the specific impact of any certain content that is driving lead conversions, and thus driving revenue. In the context of multi-channel campaigns, direct attribution allows you to know for certain whether a direct mail touch was the one that drove a conversion.

Traditional channels are historically challenging to target and measure, with direct mail being an 'Exhibit A' example of this issue. However, as a modern direct mail platform, Lob offers various approaches to measure attribution as best possible and to provide greater visibility in a rather opaque channel.

Embedding customized CTAs

Similar to email, direct mail campaigns can measure direct attribution by creating a customized call-to-action CTA that's unique to the end-recipient of the mail piece. This can be a URL, coupon code, phone number, or QR code. Ideally, each CTA should be as dynamically generated and unique as possible, and can be tracked individually if it is followed. If not down to the individual level, creating unique CTAs for each campaign (or cohorts within it) would allow a better understanding of how specific campaigns or cohorts are driving better conversions.

Triggering downstream workflows with webhooks

Webhooks allow real-time notifications of mail status for individual mail pieces (generated in the form of tracking events) as it progresses through the USPS mailstream. The two most impactful scanned events are the "Processed for Delivery" and "Delivered" events, which means that a USPS courier is about to deliver mail within the next day, or has successfully delivered the mail piece, respectively. If you have a multichannel campaign in progress, you can design for either of these events to trigger an additional sequence of events downstream, such as reinforcement reminders using other digital channels, a limited-time-only action, or some other action or acknowledgment that's unique to your business workflow.

These webhooks and ensuing downstream triggers can indirectly impact your mail piece's broader success or conversion, along with the overall campaign involving the direct mail touch.

Assigning metadata to retrieve data

Metadata can be used to identify, locate, and "tag" mail pieces or particular campaigns. While metadata is not directly responsible for attribution, appropriately tagging mail pieces is a critical step in measuring attribution at a more granular level.

Learn more about metadata and how it can help measure conversion and attribution through various ways of tagging in our Lob systems.

Lob engagement analytics

Engagement metrics provide insights into what content resonates with which audiences; this is essential to optimizing your campaigns (so you can do more of what works!)

Include Lob-generated QR Codes on your mailpieces to view engagement analytics in the following ways:

  • In the Lob dashboard: Under the Mail Analytics section, see the Engagement tab for an aggregate view. Or, view campaign-specific analytics on any individual campaign's detail page, under QR Code Engagement.

  • Via API: Receive detailed analytics via our QR Analytics endpoint.

Figma plugin

A plugin that converts Figma files to Lob-ready HTML templates

Overview

Our Figma plugin enables designers to create dynamic, personalized creative within a familiar design tool environment, and export them to Lob to be used in mail campaigns.

Here’s what you can expect

  • Design it. Build branded templates with proper dimensions, address blocks, and bleed lines.

  • Personalize it. Add dynamic variables, like first name or variable imagery, to tailor each piece.

  • Send it. Your design automatically ports to Lob when you're ready to send.

In order to use the plugin, you can navigate to the Integrations section of your Lob dashboard. The Figma plugin is listed in the Design Tools section of the page. You can also go straight to the Figma to Lob listing to download the plugin.

Enter your Lob login information to the plugin to get started.

Steps to using the plugin

Step 1 - Create a template

Once you have downloaded the plugin, you will want to create a new base file by creating a template.

  1. Create and open a blank design template.

  2. Open the plugin at the top and select the desired mail format. We currently offer templates for Letters: 8.5x11, Postcards 4x6, 6x9, 6x11 , and Self-Mailers 6x18, 12x9, 11x9

  3. Click "Continue"

Step 2 - Design away

Now that you have your template set up, you should go ahead and design as you normally would! To create dynamic personalization in your creative:

  1. Mark dynamic text with double brackets. e.g. {{first_name}}

  2. Name dynamic images with double brackets on the leftside nav

When you send mail with Lob, dynamic text / imagery is populated when columns in your audience file map to merge variables in your creative.

Best practices to keep in mind while designing:

  • Create your design on the template generated and be sure to only use 1 root frame (ensure all design elements, shapes, images, text are all contained within this single frame)

  • Rotating the root frame of your design file will result in an error

  • Be sure your design fits within the bleedlines, and takes the address block into account. We will automatically hide guide layers (bleedlines, address block) when you export - if you change the names of guide layers you will need to hide them on your own.

  • No need to flatten non-variable imagery and text - this will happen automatically on export

  • For letter templates, duplicate the second page until you have the needed page count

Step 3 - Port to Lob

Once your design is ready, it's time to export it to your Lob account. The plugin achieves this by converting your Figma design into HTML.

  1. Open the plugin and click "Export your mail design"

  2. If your design uses Google fonts and static imagery, Lob will auto-host your background imagery. Your creative will appear as an HTML template in your Lob account.

    1. As a default, the plugin sets your template as a Live HTML Template, but you can always choose to set it as a Test Template instead.

    2. Assets will not expire, but we do have a 100 asset cap in place to manage storage per account. Once you hit this cap, reach out to support and we will help you clear room for new images.

  3. If you’re using variable imagery, you can still click "continue" to port your creative to your Lob account. While building your campaign, you'll need to host these images and add hosted image URLs to your audience file in order to map images to recipients.

For those using custom fonts (ie. fonts not available at https://fonts.google.com/), we need access to the versions of that font you’re using in order to port your dynamic creative to Lob. Don't worry—we've laid out instructions for how to host custom fonts yourself here.

If you have any questions on the plugin, contact your CSM or reach out to [email protected]. Happy designing!

One-time campaigns or triggered sends?

One-time campaigns

A common approach to sending direct mail is to send a single, large campaign to a target audience.

At Lob, a "one-time" campaign is a one-to-many method of mail distribution to a broad audience using a single set of mailing instructions.

Popular use cases for one-time campaigns include sending acquisition or cross-sell mailers, retail promotions, annual policy updates, end-of-life notices for a sunsetting product, referral campaigns, etc.

Traditionally, sending a campaign meant negotiating RFPs for every project, long lead times with lots of back-and-forth with the printer, imperfect audience lists, and use of generic creatives that lacked personalization, if any.

With Lob, you can create campaigns using our flexible settings and guidance, choose from various delivery options, and apply dynamic personalization at unprecedented granular levels.

One-time campaign execution is easy in the Lob Dashboard via Campaigns, or programmatically via our Campaigns API.

Campaign FYIs
  • Some advanced campaign features or mail formats are only available to Enterprise-tier customers, and may have mail piece minimums to qualify for a campaign send.

    • Letter add-ons (envelopes, cards, buckslips) must be ordered in advance and be fully stocked in your inventory in order for your campaign to be successfully sent

    • Target Delivery, cards or buckslips have different campaign send minimums

  • Some campaign-specific settings may override your account-level settings, such as merge variable strictness or cancellation windows

  • You can send most domestic mail formats offered by Lob in Campaigns, except checks and extra service mailers (Certified & Registered Mail). No campaigns can be sent abroad.

Automated campaigns (trigger-based)

Another common way to send direct mail is to individually dispatch mail, usually initiated by pre-programmed logic or event within an orchestration workflow.

"Triggered" mail is an automated process that sends mail to a single recipient when they meet a pre-set condition or take a defined set of actions within a certain timeline.

Lob refers to these event- or trigger-based campaigns as automated campaigns.

Popular triggered use cases include post-signup onboarding mail, abandoned cart recovery, order notices or monthly statements, product retargeting, and follow-up confirmations.

Using Lob's single endpoint APIs, you can create a custom trigger automation from scratch, or take advantage of popular pre-built API integrations to connect to a platform you already use for your digital channels. Or for a less technical lift, you can automate your sends directly from the Lob dashboard.

Self-Mailers

Self-mailers can grab attention with their creative design unfolding to tell your brand's story. They offer more room for your messaging but are folded to a compact size. Their all-in-one format eliminates the need for envelopes, encouraging immediate engagement from recipients and facilitating a quicker response.

Self-mailers are exclusive to Enterprise edition customers. Upgrade your to gain access to this mail format, or reach out to our to learn more.

Check out the following resources to get started with self-mailers

  • API documentation: or

  • Lob dashboard: section or for self-mailer campaigns

  • for HTML templates

  • for ready-to-use creatives and design inspiration

Self-mailer formats

Layout dimensions & specs

Layout dimensions

Lob currently supports the following self-mailers:

  • : measures 6x9” when folded in half, no offset of panels, and unfolds horizontally

  • : measures 6x9” when folded in half, no offset of panels, and unfolds vertically

  • : measures 6x9" when folded in half, has a 1" offset between the top and bottom panels when folded, and only unfolds vertically

  • : measures 6”x9" when c-folded inward, has a .25" offset on the bottom panel when folded, and only unfolds vertically.

Follow our design templates carefully to ensure you place your design elements for each permutation, including the location of the adhesive, in the appropriate location. (For example, there are four panels available to customize for all bifolds, wherein one of the outside panels must have an for the address and postage area.)

Make sure all artwork submissions are facing upright for both inside and outside panels. Our printers will invert the inside panel of submitted customer artwork during the production phase.

Paper specs

We use a few pre-approved papers across our commercial printer network. In ensuring uniform quality and consistency across all of our mail pieces, each paper source specification must fall within a small range. The specification/value range pairs are listed below:

  • Basis Weight: 80# Cover with Gloss

  • GSM: 218

  • Full Bleed

  • 1 Side UV Gloss

Ink-free zone dimensions

  • 6x18" bifold self-mailer

    • W x H: 4 x 2.375"

    • 0.15" from the center fold line

    • 0.25" from the bottom edge (including bleed)

    • Placement: Left panel outside

  • 12x9" bifold self-mailer

    • W x H: 4 x 2.375"

    • 0.15" from the center fold line

    • 0.25" from the right edge (including bleed)

    • Placement: Top panel outside

  • 11x9" bifold self-mailer

    • W x H: 4 x 2.375"

    • 0.15" from the center fold line

    • 0.25" from the right edge (including bleed)

    • Placement: Top panel outside

  • 17.75x9" trifold self-mailer

    • W x H: 4 x 2.375" 0.15" from the center fold line

    • 0.25" from the right edge (including bleed)

    • Placement: Top panel outside

    • Glue zone 9”x.5” (at 12” score)

A Carbon Neutral Mail certification will automatically be included within the official use address block on the backside for all bifold self-mailers printed by Lob. Read more about how you can send mail in a more environmentally responsible way with Lob in our section.

Self-mailer adhesives

Stain-resistant, low tack, clear fugitive glue is used for adhesives on the folded self-mailers.

Glue is positioned within 0.25" of the opening edges and placed opposite the final fold. Glue is applied by one of the following methods:

  • Continuous glue line at least 0.125" wide

  • Three or four glue spots at least 0.375" in diameter

  • Three or four elongated glue lines

Self-mailer best practices

Ensure your self-mailers get to their final destination by following these guidelines:

  • The from field is required for all self-mailers, regardless of the destination

  • Self-mailers should not contain any PII outside of the

  • Avoid any to ensure your mail does not get rejected by USPS

  • HIPAA-compliant self-mailers are not offered at this time, as self-mailers are not placed in envelopes

  • options may differ based on destination and use type (e.g. promotional vs non-promotional)

  • We do not recommend placing promotional address information in your creative in the bottom 2.375" of a mailpiece opposite the address panel. This will prevent the USPS from accidentally scanning the wrong side of the mailpiece.

Using metadata

Metadata tags

In the Lob ecosystem, metadata is used to “tag” each mail piece or each campaign. You can use metadata to find individual mail pieces more easily and group mail pieces together for reporting and attribution. Example metadata tags could include a campaign name, a customer segment, or an internal ID. Using metadata smartly can help bridge the gap between Lob and your internal systems, allow you track mail at a more granular level, and create data-driven stories to get the most ROI out of the direct mail channel.

See .

Metadata types

There are several kinds of metadata at Lob:

  • Mailpiece metadata can be used on our single mailpiece APIs.

  • Campaign metadata can be used with our Campaigns feature, and allow you to filter your searches by all mailpieces in a particular campaign.

  • Recipient metadata can be used within our Campaign UI feature in the dashboard, and allow you to filter by a specific subset of mailpieces.

Key-value pairs

Both mailpiece and campaign metadata rely on key-value pairs that you create.

  • The key, or tag name, is what will remain consistent across all the mailpieces you’d like to create. For example, “state”.

  • The value, or tag value, will be unique to each mailpiece, for example “NC” or “CA”.

  • When combined, you can easily find mailpieces with “state:NC” or “state:CA”.

Metadata objects can include up to 20 key-value pairs of custom data. Each metadata key must be less than 40 characters long and values must be less than 500 characters. Neither can contain the characters " and \. Metadata does not support nested objects.

Mailpiece metadata

Mailpiece metadata applies to each individual mailpiece sent. Mailpiece metadata is great for tags that are specific to each recipient, like state:NC or first_name:John.

You can create mailpiece metadata on our single mailpiece APIs by including a metadata object with each mailpiece POST request. Here is an example of a mailpiece POST request to our api.lob.com/v1/postcards endpoint, including a metadata object:

Campaign metadata

Metadata at the campaign level is configured on the POST /v1/campaigns or in the dashboard, in the Campaigns screen at the bottom “Add Tags” section.

Campaign metadata cannot be configured within your campaign CSV

Each individual mailpiece created through the campaign will inherit Campaign metadata. This is great for tags you’d like to apply to an entire campaign.

Recipient metadata

In addition to Campaign metadata, you can assign metadata on the individual recipient level. This is great for instances in which you'd like to apply context specific to each individual such as a unique identifier, customer id, or email address.

Filtering your metadata

In the dashboard, you can filter metadata at the single mailpiece level. Any mailpiece created in the Campaigns function will also be visible within the single mail piece tabs.

Example: In the section, click on ‘Filters’ and search by Metadata

​

You can also go into any individual mailpiece, and see the key-value pairs tagged in the 'Metadata' section under the 'Details' section.

Postcards

Postcards stand out in direct marketing for their ability to deliver eye-catching, concise content that engages recipients instantly, making them highly effective for promotional campaigns. For transactional or operational communications, their streamlined, envelope-free design ensures important information is immediately visible, enhancing clarity and response rates for critical updates or calls to action.

Let's get started! First, be sure to check out the following resources:

  • API documentation: or

  • Lob dashboard: section or for postcard campaigns

  • for HTML templates

  • for ready-to-use creatives and design inspiration

Layout dimensions & specs

Layout dimensions

The front side of the postcard is fully available for customization.

For the backside of the postcard, follow the guidance provided in the templates below to leave enough room for ink-free areas.

You may also to your postcards to incorporate personalized tracking.

Paper specs

We use a few pre-approved papers across our commercial printer network. In ensuring uniform quality and consistency across all of our mail pieces; each paper source specification must fall within a small range. The specification/value range pairs are listed below:

  • Basis Weight: 100# - 120#

  • Cover GSM: 255 - 325

  • Full Bleed

  • 1 Side UV Gloss

Ink-free zone dimensions

4x6" Postcards:

  • W x H: 3.2835 x 2.375"

  • 0.275" from the right edge (including bleed)

  • 0.25" from the bottom edge (including bleed)

All other postcard sizes:

  • W x H: 4 x 2.375"

  • 0.275" from the right edge (including bleed)

  • 0.25" from the bottom edge (including bleed)

For all postcards printed by Lob, a Carbon Neutral Mail certification will automatically be included within the official use address block on the backside. Read more about how you can send mail in a more environmentally responsible way with Lob in our section.

Postcard best practices

Ensure your postcards get to their final destination by following these guidelines:

  • All US postcards can be sent as either First Class or Marketing Mail (Standard Class Mail)

  • The from field is not required for US postcards, but is required for international destinations

  • Only 4x6" postcards can be sent to

  • Postcards cannot include any PII outside of the

  • Avoid any to ensure your mail does not get rejected by USPS

  • We do not recommend placing promotional address information in your creative in the bottom 2.375" of a mailpiece opposite the address panel. This will prevent the USPS from accidentally scanning the wrong side of the mailpiece.

US AV product suite

Lob's Address Verification API is able to correct and identify over 156 million US domestic addresses (and more globally) to determine whether or not these physical addresses are deliverable. This is because Lob is , meaning the API has been thoroughly tested by the USPS to ensure that it can accurately correct and validate street addresses. When our API confirms that a physical address is deliverable, you can be much more confident that your mail will be delivered.

US Verifications

Validate, automatically correct, and standardize US domestic addresses based on USPS's . See our for more details.

If your addresses are returning as undeliverable, refer to the various fields in the US verification object in our for detailed definitions and explanations.

Supported US States & Territories

Our US Address Verification API supports the following states and territories:

  • All 50 states

  • Washington, D.C. (District of Columbia)

  • Armed Forces (Africa - AE, Americas - AA, Canada - AE, Europe - AE, Middle East - AE and Pacific - AP)

  • American Samoa

  • Federated States of Micronesia

  • Guam

  • Marshall Islands

  • Commonwealth of the Northern Mariana Islands

  • Palau

  • Puerto Rico

  • The U.S. Virgin Islands

US Autocomplete

Given partial address information, including optional input of city, state, and zip code, US Autocomplete returns up to 10 full US address suggestions. Not all of them will turn out to be valid addresses; they'll need to be . See our for more details.

Use of the US Autocomplete API is included with every Address Verification subscription. See our pricing page for different for more information.

Reverse Geocode Lookup

Find a list of zip codes associated with a valid US location via latitude and longitude; a live API key is required to use this feature. See our for more details.

Zip Lookups

Lob's Zip Lookup tool can verify US zip codes without having to provide a full address. If the inputted zip code is real, Lob can return information about the zip code including a list of cities, states, and other associated information. If it's not a real zip code, Lob will return an "invalid zip code" error message. See our for more details.

AV Elements

Lob Address Verification Elements verifies an address by intercepting the original form submission and pre-validating the address fields with Lob. Thus our APIs can be leveraged in customers' address entry workflows without any major rewrite required--just a few additional attributes to add to any existing markup, and it'll be running with a few minutes of work.

See our to get started.

Lob Confidence Score

The Lob Confidence Score is an object returned from the US verification endpoint that provides a value between 0-100 of the likelihood of the address being deliverable. Lob leverages its extensive insights, having sent mail to more than 1 in 2 US households, to generate a confidence score and provide more comprehensive address deliverability data.

Score definitions

  • 70-100% - This address has received one or more successful deliveries

  • 40-68% - This address has both mail returned to sender and successful deliveries

  • 0-39% - This address has more mail returned to sender than successful deliveries

  • None ("") - Lob does not have data on this address

Note that high scores do not guarantee deliverability. These are estimates based on Lob’s extensive mail tracking data.

See our under the JSON object lob_confidence_score for more details.

Choosing a delivery strategy

Thinking through your mail delivery strategy can be a powerful differentiator in fostering meaningful connections, and should be a strategic pillar in building any direct mail program. Being adaptive in how you send and deliver mail given fast-changing customer preferences and market conditions can have an outsized impact on improving your reach, relevance, and responses.

Lob’s automation technology offers different delivery options to deploy your direct mail campaigns with regards to speed, reach, and timing, so you can get in front of your target audience in a way that engages them the most.

Immediate (or "ASAP") mailings

As a default, Lob mail will be immediately sent and routed to production after the customer submits a mail order, pending any applied at the account or campaign level. This is the primary API setting for Lob mailings that is available to all customers, and optimizes for speed of delivery over delivery timing or reach.

See on how to track individual mail pieces at each step of the production and delivery process, and see on setting up and surfacing mail tracking notifications.

Scheduled mailings for a future date

Scheduled Mailings is available only to customers. Contact or your Account Manager to gain access to this feature.

Mailings can be scheduled up to 180 days in the future. Until that time, mailings can also be canceled. You can use this feature to

  • Create automated drip campaigns (e.g. send a postcard at 15, 30, and 60 days)

  • Schedule recurring sends

  • Plan your mailing schedule ahead of time

Up until the time a mailing is scheduled for, it can also be canceled. If you use this feature in conjunction with a cancellation window, the send_date parameter will always take precedence.

Example: Create request using send_date

Scheduling a future mailing

Scheduling a mailing for the future just requires one additional parameter: send_date. This specifies a date and time up to 180 days in the future to start processing the mailing. For billing purposes, requests will count towards the month of their send_date, and will not be charged if they are canceled before that time. If your account has a set for the resource you are creating, passing a send_date will override that window. For more detailed request information, see our .

Canceling a future mailing

If something changes on your side and you no longer wish to send a mailing that had already been scheduled (such as the customer taking a certain action), you can programmatically as long as the mailing's send_date has not passed. Additionally, you can cancel a mailing from your on the page associated with your mail piece.

Target delivery date

Target Delivery is under development; contact or your Account Manager to explore this functionality.

Lob prides itself on speed of execution: our goal is to get mail into the USPS mailstream within 2 business days from submission. However, we’ve heard from customers that more exact timing of delivery is of equal importance. We are currently developing a new feature for timing mail arrival in the end-recipient’s mailbox.

Our goal with Target Delivery will be for 80% of campaign mail pieces to land in the recipient’s mailbox on or within 3 business days before or after the specified in-home target date. With a target release date in 2024, this feature will be available to Enterprise edition customers and prospects who can meet the requirements of volume and saturation.

AV best practices

One of the most prized value propositions of our Address Verification solution is our access to detailed USPS deliverability data which provides a clear, binary value as to whether or not an address is capable of receiving mail. Because Lob sends millions of mailpieces, we also have the data and the intelligence to provide more context that can be useful when considering whether or not to send mail to a specific address.

This useful information is returned to you in the Address Verification API response; .

What you’ll see in the AV API response

Deliverability

The USPS returns empirical data to Lob on whether or not an address is deliverable (returned in the deliverability field), but it’s important to keep in mind the term “deliverable” is literal here— while the address itself may literally be deliverable, it does not guarantee the intended recipient can/will accept mail upon delivery attempt.

This is where it becomes important to make further analysis of the API response.

Address Type

While evaluation on this metric doesn’t really have a bearing on the number of successful deliveries in your campaign, under components, the address_type field contains human-readable definitions for the type of the specified address.

Address type may be very relevant, depending on the goal of your campaign. For example:

  • Realtors may only be interested in addresses with an address_type of “residential”

  • A startup pitching to companies may only be interested in those noted as “commercial”

  • Those who wish to opt-out of sending mail to more rural areas would want to filter out address types returned as “rural route”

A full list of address types can be found

Delivery Point Validation (DPV)

Under deliverability_analysis we provide more information about addresses. provides the highest level of address accuracy-checking: the address is checked against the USPS Address Management System (AMS) data file to ensure that it exists as an active delivery point to where mail can be delivered. DPV is intended to confirm USPS addresses but also identify potential addressing issues that may hinder delivery. Several sub-fields are included in DPV data to provide additional context on the given address; these fields are one of many variables factored into USPS decision-making when determining deliverability.

The dpv_active field corresponds to the USPS field dpv_no_stat. Even if an address is deliverable by definition, it could still be flagged as "N" for inactive. "N" indicates an address is not receiving deliveries for one reason or another:

  • the address has been vacated recently

  • the address has been unoccupied for 90+ days, thus considered temporarily vacant

  • the address does not wish to receive mail for unspecified reasons

Remember: If an address returns a dpv_active status of “N,” any mail sent to this address is at risk of being returned to sender.

Lob Confidence Scores

The (lob_confidence_score) is our prediction of successful delivery based on our historical data for an address. If we sent 10 mailpieces to an address, and all 10 were successfully delivered, the address would have a score of 100. If we sent 10 mailpieces to an address, but 8 were , it would have a much lower score of 20. Our Confidence Scores are updated monthly to reflect new delivery attempts.

You may want to consider using the Confidence Score based on the that you send:

  • If you are sending operational mail, you may only need proof that the mailpiece was sent to a valid address on file, and successful delivery may not be as important.

  • If you are sending marketing mail, it is strongly suggested that you consider this field before sending, as addresses with Confidence Scores under 100 indicate the address has rejected mail before.

Return to sender (RTS) rates

Without validation, the industry average RTS rate is 5-10%, but through the use of our AV solutions, we see customers with an average RTS rate of 2% or less. Historically, mail campaigns have been prone to imperfection, but through the use of the best practices provided, return-to-sender rates can be driven lower.

Cache if you can!

Lastly, for customers working with full tech stacks, we highly recommend caching responses to our AV endpoint, as prices are made per API call. So, if an end-user has made a request for the validation of an address (ex: “210 King St, San Francisco, CA”), cache this result internally for at least 24 hours. Now, if another customer attempts to validate that same address, you can pull it from the cache instead and are only charged for the original API call.

Microsoft Dynamics 365

This platform is in closed beta. reach out to your Account Manager to enable or

Overview

Microsoft Dynamics 365 (MD365) is an integrated suite of business applications that combines customer relationship management (CRM) and enterprise resource planning (ERP) capabilities. This platform helps organizations streamline their operations, improve customer engagement, and make data-driven decisions.

The integration of MD365 with Lob enables businesses to enhance their operational efficiency by triggering mailpiece creation populated by data within MD365. This ensures a cohesive and effective approach to business process management and customer interaction strategies.

How to connect Lob with Microsoft Dynamics 365

New Registration in Microsoft Azure

  1. To begin, you'll need to your associated Azure account as an admin. If you do not have an Azure account, you learn how to create one .

  2. Once in the Azure Portal, navigate to the App Registration page (you can use the search bar at the top to find it.)

  1. Click New Registration at the Top

  2. Set the Redirect URI to

  1. Click on Register to create the application.

  1. Select Manifest tab, in the manifest editor, set the allowPublicClient property to true and click on Save.

  1. Select the API permissions tab and then go ahead and click "Add a permission".

  1. Search for and choose Dataverse under the APIs my organization uses tab. If Dataverse is not found, then search for Common Data Service.

  1. Click on Delegated permissions, check the options, and click on Add permissions. This will wrap up registering your app in the Azure Active Directory!

Connect to Lob

  1. Within the Lob Dashboard, navigate to the Integrations page and click on “Microsoft Dynamics 365.”

  2. Click the “Connect” button to begin.

  • Client ID is on the overview page

  • A Client Secret can be made by navigating to the "Certificates and Secrets" tab on the left

    • Click " + New Client Secret"

    • Give it a description

    • The Value is your Client Secret (NOTE: Save this value somewhere else just in case!)

  • The Organization ID and Environment URL can pulled by your admin in the "Power Platform admin center" page under "Environments."

    • Click the environment you want to integrate with.

For Environment URL, you will need to prepend with https://

  1. Once you have connected your Salesforce account to Lob, if successful the “Not Connected” label will show “Connected."

Once you’ve successfully connected Lob to your MD365 account, you can from within the Campaigns flow.

Shopify App: Address Cleanser

Shopify overview

is an e-commerce platform that allows anyone to set up an online store to sell their products. With Lob’s Address Verification integration, you can validate every address submitted within your Shopify store, ensuring that your addresses are deliverable and that shipments arrive at the right place.

Benefits:

  • Ensures accuracy by correcting mistakes and misspelled addresses

  • Suggested addresses meet USPS address formatting requirements with data standardization

  • Flag missing mandatory delivery fields such as unit numbers, streets suffixes, etc.

  • Identify P.O. Boxes and residential or commercial buildings

  • Reduce non deliverable addresses with delivery verification

Getting started

Step 1: Visit the Shopify store

Visit the “Lob Address Cleanser” page in Shopify and add the app to your store:

Step 2: Install Lob’s Address Cleanser

Once you click “Add app”, Shopify will guide you through the installation process, which will require you to select your store and click their “install app” button.

Step 3: Customize your shopper’s experience

Once installed, you’ll be taken directly to getting started page within Shopify. Address Cleanser will be disabled by default once installed, and here you’ll have the option to customize the experience your customers will see in your store. You can customize the font type as well as color theme to match your branding.

The above popup will show to your customers after they have submitted their order to give them the option to correct and dial in their shipping address for more accurate delivery.

Step 4: Enable Address Cleanser on your store

Payment details are required in order to set Address Cleanser live on your Shopify store. Click the “View Plans” tab within the app, and you’ll see two options for you to submit payment:

  1. If you’re an existing Lob customer, you can link your Lob live environment API key to the Shopify account, and you’ll be set! Address Verification will be live and enabled on your Shopify store.

  2. If you’re not a Lob customer, you can use the left widget which will allow you to connect payment through Shopify. As a new customer to Lob, enjoy 300 address verifications on us! After 300, you’ll be charged $.02 for a verification in the United States. $.04 for international orders.

You’ll see an option in which you can set a max spend per month, and after setting, you’ll be taken to a final screen to approve the billing through Shopify’s portal. Click “Approve” and you’re set!

Step 5: Sit back, relax, and have confidence around your addresses

Now that is up and running on your store, know that the addresses coming into your Shopify account are deliverable and validated. If any incorrect information is provided by the customer, the customer will have a chance to correct it by selecting the address we automatically corrected for them, or allowing them to go back and edit their address.

Once updated, a customer will then see the updated address on their checkout screen. As a merchant, you will see the updated and latest address in your orders list for that customer.

We hope you enjoy ! If you have any questions, or check our .

Postcards API
Campaigns API
Postcards
Campaigns
GitHub library
Template Gallery
4x6" postcard template
6x9" postcard template
6x11" postcard template
add QR codes
Carbon Neutral Mail
international destinations
no-ink zone
prohibited artwork
Learn more here.
CASS (Coding Accuracy Support System) Certified
Coding Accuracy Support System (CASS)
API reference
API reference
verified
API reference
Address Verification editions
API reference
API reference
AV Elements Quickstart guide
API reference
see a response sample here
here.
Delivery Point Validation
Lob Confidence Score
returned to sender
type of mail
https://integrations.hg.lob.com
sign up here.
log into
here
set up an Automated campaign
Client ID
OrganizationID and Environment ID

Send via the Lob Dashboard

Send via Campaigns API

API integrations

No-code integrations

Cover
Cover
Cover
Cover

All about addresses

Anatomy of a mailpiece

When you send an API request to Lob, you are sending 3 pieces of information:

  1. the "To" address,

  2. the "From" address, and

  3. the content.

Below are some best practices to follow around formatting your address data with Lob.

What's an address?

An address gives the location of a structure or land using identifiers to help with navigation to that location. They also aid in the routing of mail.

The delivery address is the most important information on your mail piece. Use the following format for your delivery addresses:

  1. Name (or attention)

  2. Company* (if applicable)

  3. Delivery address: Line 1, and Line 2* (if applicable)

  4. City, State, ZIP Code, Country*

Items marked with a * are optional.

For more details on character limits etc., reference our API docs or see the Formatting fields and record values in our Campaigns audience guide.

Address book

The Address Book is a collection of a customer’s addresses uploaded and stored in our system, which can be accessed in the Lob dashboard or you can leverage the address_id to retrieve that entry's information programmatically. Rather than passing the full address + mail information in one API call, customers can also pass the address_id (provided upon creating the address in the address book) that will look for the associated address information. This makes requests faster and simpler.

Standardization & verification

We cleanse all newly created addresses in order to optimize for maximum deliverability.

  • All US addresses will be automatically standardized, cleansed, and verified through our CASS-Certified Address Verification system before being returned back to you in the API response.

  • All international addresses will simply be standardized by being transformed to all uppercase.

Mail requests will be run through CASS and NCOA, as these are requirements for sending with USPS. This may result in the final mailing address being different from the ones you see in your API requests and Dashboard.

Coding Accuracy Support Systems (CASS™)

The Coding Accuracy Support Systems (CASS™) certification process is designed in cooperation with the mailing industry to improve the accuracy of postal codes, i.e., Five-Digit ZIP Code, ZIP+4, delivery point codes (DPCs), and carrier route codes that appear on mail pieces.

Lob is CASS™ certified (Cycle O) to ensure your addresses are standardized before any mail is sent.

National Change of Address (NCOALink®)

National Change of Address (NCOALink) is a service offered by the USPS, which allows individuals or businesses who have recently moved to have any mail forwarded from their previous address to their new address.

Addresses will be corrected to reflect an individual's or business's new address in the case that they have moved (only if they have registered an NCOA with the USPS). The National Change of Address (NCOALink) database check only runs for US-based addresses. It does not run for non-US addresses or for non-deliverable US addresses. For more visibility of address changes, learn more about additional NCOA functionality offered here.

Adding & deleting addresses

You cannot edit any existing addresses via the dashboard or API request. You can however delete the current address and add a new one with the updated information. For more details on adding a new address to your address book, refer to the API documentation.

If you are interested in mass-deleting addresses, you will need to set up a delete address request script. See more details on deleting in our API documentation.

Note that Lob is not permitted to add or delete addresses on behalf of customers.

Autoverify

Autoverify is included in all US Print & Mail subscriptions. Lob verifies the deliverability of all addresses before sending a request to our print partners.

Strictness settings

Depending on what business logic you'd like to take, based on your verification result, you can toggle your US address strictness settings in your Lob dashboard. There are three possible strictness levels: Strict, Normal, and Relaxed.

Learn more about the importance of mail strictness settings and how to adjust them as required by your business.

Using "Current Resident" as the recipient

The purpose of including "Current Resident" as the recipient of your mailpiece is to ensure that your message reaches its intended audience. This serves well in a case in which you're uncertain that the person(s) living at that address are the intended recipients and you do not wish to risk offending the current residents by potentially sending someone else's mail. Using the phrase "Current Resident" can be a good idea if your mailpiece is time-sensitive and the recipient may be variable.

To make an informed decision on whether or not to include the phrase, consider the purpose of your mailpiece and your target audience:

  • If your mailpiece is intended to be a personal communication or a marketing message that relies on building a relationship with your audience, then you may want to avoid using the phrase "Current Resident." Learn more about dynamic personalization here.

  • On the other hand, if your mailpiece is informational and the message is more important than the recipient, then you may want to include the phrase, as any recipient can still respond.

To indicate your recipient as "Current Resident," simply provide that as the name value where you would normally input a recipient's full name.

First Class Mail Advertising Promotion

What is the USPS First Class Marketing Mail promotion?

The First-Class Marketing Mail promotion offers businesses a unique opportunity to blend the reliability and prestige of First-Class Mail with impactful advertising. Whether it’s standalone advertisements or marketing messages integrated into First-Class Mail pieces, this promotion allows businesses to captivate recipients and drive meaningful engagement. By leveraging First-Class Mail’s superior delivery service and incorporating effective marketing strategies, you can unlock powerful ways to connect with your audience and achieve your marketing goals.

How can I take advantage of the USPS First Class Marketing Mail promotion with Lob?

Eligible mail options

First-Class Mail, including letters, cards, and flats, is eligible for this promotion. Your First-Class mailings must include one of the following:

  1. Marketing messages within First-Class mailpieces

  2. Standalone advertisements using First-Class mailpieces

Examples of eligible marketing messages

Here are examples of the types of marketing messages you can include (not a comprehensive list):

  • Discount offers:

    • “Save 10% on your next purchase with this exclusive coupon!”

    • “Unlock a special 20% discount with your personalized code!”

  • Limited-time offers:

    • “Act now! This offer expires in 7 days.”

    • “Last chance to save - this offer ends Friday!”

  • New product introductions:

    • “Be the first to try our latest product—now available!”

  • Customer loyalty rewards:

    • “Earn double rewards points on all purchases this month.”

  • Event Invitations:

    • “Join us for our exclusive VIP event next week!”

    • “You’re invited! Attend our launch party next week!”

  • Personalized Offers:

    • “Here’s a gift for you, [Customer Name]! Save 15% on your next order!”

Ineligible marketing messages

The following types of messages will disqualify your mailpieces from the promotion:

  • Content that promotes mail diversion (e.g., “Go paperless” or “Switch to e-billing”).

  • Non-marketing messages, such as those about paying bills online.

  • Purely informational messages without a marketing element (e.g., “Our hours of operation have changed”).

  • Marketing messages that only appear on buck slips, stickers, note cards, or similar inserts (they must be on the mailpiece itself).

Getting campaign approval through Lob

After selecting the marketing message you plan to use for your First-Class Marketing Mail campaign, log into the Lob promotions portal to submit your campaign for approval.

Note: In order to participate in this promotion, you will first need to “Opt In” in the Lob Promotions Portal and accept the terms and conditions of participating in the promotion through Lob.

Follow this process for campaign approval:

  1. Design and submit your mailpiece:

    1. Incorporate your selected marketing message directly onto your mailpiece.

    2. Ensure your design meets the promotion's requirements.

    3. Use the Lob Promotions Portal to submit your Mailpiece Pre-Approval:

      1. Upload PDF samples of your design.

  2. Receive pre-approval

    1. Any changes to the final mailpiece from the submitted prototype may result in disqualification from the discount.

    2. Prototypes must be approved in writing before the mailing date.

  3. Register for the promotion

    1. If you haven’t already, sign up for the First-Class Mail Advertising Promotion on the Lob Promotions Portal. This must be completed at least 2 hours before mailing.

  4. Finalize and send

    1. Lob will prepare your postage statements and submit them electronically using the CCR code FA to reflect the discount.

    2. Send your mailing and keep a hard copy for your records.

  5. Watch your customer engagement rise!

When is this promotion live?

The First-Class Marketing Mail promotion runs from September 1, 2025, to December 31, 2025.

What’s the easiest way to take advantage of this promotion with Lob?

  • Add a marketing message: Update your operational or transactional mailpieces to include at least one marketing message directly on the mailpiece.

  • Upgrade to First-Class Mail: Ensure your mailpieces are sent using First-Class Mail to qualify for the discount.

Who does Lob recommend for this promotion?

This promotion is ideal for operational and transactional customers currently using Lob’s First-Class Mail product. By adding a compliant marketing message to your mailpieces, you can unlock this discount while enhancing customer engagement. Just remember to avoid any messaging that encourages mail diversion, such as “See our website for your offers!”

Take advantage of this opportunity to elevate your mail campaigns and drive better results with Lob’s seamless workflows and USPS First-Class Marketing Mail discounts!

Tactile, Sensory & Interactive Promotion

What is the USPS Tactile, Sensory, and Interactive promotion?

The Tactile, Sensory, and Interactive (TSI) Promotion encourages mailers to excite their customers’ senses by incorporating innovative techniques into their First-Class Mail and USPS Marketing Mail. New developments in papers and paper stocks, substrates, finishing techniques, and inks can be incorporated into mailpieces to create a multi-sensory experience through special visual effects, sound, scent, texture and even taste! Features like pop-ups, infinite folds, and other dimensional treatments encourage interaction and drive customer engagement.

The USPS offers a discount for three types of new experiences:

  1. Specialty inks

  2. Sensory treatments

  3. Interactive elements

How can I take advantage of the USPS TSI Promotion through Lob?

The USPS Tactile, Sensory, and Interactive (TSI) promotion is all about helping you make your mail stand out. By adding unique design elements that engage the senses, you can create a stronger connection with your audience and save money. Here’s everything you need to know to qualify.

Eligible mail types

The TSI promotion is open to these types of mail:

  • First-Class Mail: Letters, cards, and flats

  • USPS Marketing Mail: Letters and flats

  • Nonprofit USPS Marketing Mail: Letters and flats

Keep it on-message

Mailpieces that include mail diversion messaging—such as “Go paperless” or “Switch to e-billing”—are not eligible for the discount. Even if your piece includes the right treatments or technology, these types of messages will disqualify you from the promotion.

Where treatments can go

To qualify, your mailpiece needs to feature one or more eligible treatments. These can appear:

  • On the outside of the envelope

  • Directly on the mailpiece itself

Important: Treatments like blow-in cards, inserts, order forms, or reply envelopes don’t qualify for this promotion.

Choose Your Treatment

To take advantage of this promotion, select the sensory treatments for your mailpiece. All treatments must be produced using Lob’s Custom Format product, unless noted otherwise.

By adding these creative touches to your mail, you can enhance engagement and qualify for USPS discounts—all while creating a memorable experience for your audience.

Eligible treatments for the USPS TSI promotion

The USPS Tactile, Sensory, and Interactive (TSI) promotion is designed to encourage creative, engaging direct mail that stands out in the mailbox. To qualify for the promotional discount, mailpieces must include one or more of the eligible treatments outlined below.

Specialty inks

Showcase unique ink properties in ways that are visible and distinguishable to recipients:

  • Conductive inks: Activate electronic devices or include printed, battery-powered circuits.

  • Thermochromic inks: Change colors in response to temperature shifts.

  • Photochromic inks: Change colors when exposed to UV light.

  • Metallic and optically variable inks: Create reflective effects or metallic sheens.

  • Piezochromic inks: Change appearance when pressure is applied.

  • Hydrochromic inks: Transform when exposed to water or liquids.

  • Scented inks: Add fragrances using scented varnishes or coatings to amplify your message.

Non-eligible ink treatments: If the specialty ink resembles a photo or doesn’t create a distinguishable effect as listed above, it won’t qualify. Treatments must deliver a noticeable and impactful effect to recipients.

Sensory treatments

Engage the senses with innovative designs that appeal to sight, sound, smell, taste, and touch:

  • Texture: Use papers that feel soft, leathery, crinkly, or feature embossing for a tactile experience.

    • Pro tip: Lob can swap standard blank #10 envelopes with grooved blank #10 envelopes, which can run through our normal workflow and qualify for the discount. Reach out to your AM to discuss your options.

  • Scent marketing: Incorporate unique aromas using scented varnishes, coatings, or labels.

  • Visual effects: Add holographic treatments, filters, or lenticular designs to enhance your message.

Interactive Elements

Deliver a dynamic and engaging experience that encourages recipients to interact with your mailpiece:

  • Integration: Use three-dimensional elements, pop-ups, zip strips, clean-release cards, and more to surprise and delight.

  • Infinite folds: Include layers of hidden information behind folds for customers to uncover.

  • Trailing edge die- cut (TED-C) envelopes: Add eye-catching cutouts and shapes that make your piece stand out.

  • Pro tip: Lob offers “Tip-on-Card” or “Card Affix” options through our normal workflow, which qualify for the promotion when used in tip-on-card (TOC) campaigns.

By incorporating one or more of these eligible treatments, you can transform your mailpiece into an unforgettable experience and qualify for the USPS TSI promotional discount.

How to Get Campaign Approval for USPS TSI Promotion with Lob

Participating in the USPS TSI promotion through Lob is simple with a step-by-step process designed to help your campaign qualify for discounts while delivering standout mailpieces.

Step 1: Select your sensory treatment

Decide which eligible sensory treatment you’d like to incorporate into your campaign. Options include specialty inks, tactile finishes, or interactive elements.

  • For grooved envelopes or Tip-On-Cards: Use Lob’s standard workflow by specifying the inventory item in your API call. In order to participate in this promotion starting on 2/1/2025, customers need to have their inventory order placed for either their grooved envelopes or Tip-On-Cards by 12/31/24.

  • For other sensory treatments: Submit your campaign through Lob’s Custom Format workflow.

Step 2: Opt-in to the promotion

To get started, log into the Lob Promotions Portal:

  1. Select “Opt-In” for the USPS TSI promotion.

  2. Accept the terms and conditions for participating in the promotion through Lob.

Step 3: Design and sample your mailpiece

  1. Design: Work with your Lob Account Manager (AM) to create a mailpiece featuring your selected treatment.

  2. Sample approval:

    1. Create digital and physical samples of your mailpiece.

    2. Upload the sample via a Service Request in the Lob Promotions Portal.

Step 4: Submit for USPS approval

  1. Lob will print the relevant information from your service request and mail it, along with your mailpiece sample, to the USPS Promotions Office.

  2. You’ll receive approval via email and in the Promotions Portal.

Step 5: Finalize program enrollment

  1. Lob will enroll you in the Tactile, Sensory, Interactive Program on the Business Customer Gateway.

  2. Lob will prepare and electronically submit your postage statements, using the CCR code “SS” to reflect the discount.

Step 6: Send your mailing

  • Keep a hard copy of your mailpiece for your records.

Step 7: Enjoy the results!

Once your mail is sent, sit back and watch your customer engagement rise—thanks to the powerful impact of sensory, tactile, and interactive direct mail!

For any questions or assistance, your Lob AM is here to help every step of the way.

FAQ: How to Take Advantage of the USPS TSI Promotion with Lob

What’s the easiest way to qualify for the TSI promotion?

  • If you’re sending letters in Lob’s standard blank #10 window envelopes, contact your Account Manager (AM) about switching to Grooved Standard #10 envelopes. This upgrade qualifies your mail for the promotion while keeping your workflow simple.

  • For customers interested in tip-on cards (TOC), Lob’s standard product supports this option. Work with your AM to source the necessary inventory and set up your campaign.

Who does Lob recommend this promotion for?

Lob recommends all letter customers update their Standard Blank #10 envelopes to Grooved Standard Blank #10 envelopes to take advantage of the TSI promotion. This quick and easy change ensures eligibility while enhancing your mailpiece’s tactile appeal. Ensure you speak with your AM about your Grooved Envelope inventory needs prior to 12/31/2024.

When does the USPS TSI promotion run?

The promotion runs from February 1, 2025, to July 31, 2025. Be sure to plan and execute your campaigns during this period to maximize your savings and engagement.

How do I get started?

Reach out to your Lob AM to discuss your options and ensure your mailpieces meet the requirements for this exciting promotion.

{
    "description": "demo",
    "to": "adr_210a8d4b0b76d77b",
    "from": "adr_210a8d4b0b76d77b",
    "front": "tmpl_a1234dddg",
    "back": "tmpl_a1234dddg",
    "size": "6x9",
    "mail_type": "usps_first_class",
    "metadata": {
        "spiffy": "true",
        "first_name": "John",
        "state": "NC",
        "segment": "012b-ACQ"
    },
    "send_date": "2022-01-01T00:00:00.000Z"
}
here for more coding examples using metadata tags
API call
Configure Settings
Postcards
  curl https://api.lob.com/v1/postcards \
    -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
    -d "description=Demo Future Postcard" \
    -d "to=adr_bae820679f3f536b" \
    -d "from=adr_210a8d4b0b76d77b" \
    -d "front=tmpl_b846a20859ae11a" \
    -d "back=tmpl_01b0d396a10c268" \
    -d "merge_variables[name]=Harry" \
    -d "send_date=2021-07-26"
cancellation rules
Tracking your mail
webhooks
Enterprise edition
Sales
cancellation window
API documentation
cancel those requests
dashboard
Sales
Print & Mail edition
sales team
Self-Mailers API
Campaigns API
Self-mailer
Campaigns
GitHub library
Template Gallery
6x18” bifold template
12x9” bifold template
11x9" bifold template
17.75x9" trifold template
ink-free zone
Carbon Neutral Mail
no-ink zone
prohibited artwork
Mailing Class
Learn more here.
Shopify
https://apps.shopify.com/lob-address-cleanser
Lob’s Address Cleanser
Lob Address Cleanser
Lob’s Address Cleanser
Address Cleanser
reach out to us
Support page

Letters

Letters are highly effective for direct marketing due to their personal touch and tangible presence, enhancing recipient engagement. They also serve well for transactional or operational communications, offering a formal and reliable delivery of important information that stands out from digital clutter.

Lob offers two sizes of letters: 8.5x11" and 8.5x14".

To get started with sending letters, check out our Letters API documentation, our GitHub library, or Lob's Template Gallery for inspiration.

Layout dimensions & specs

Layout dimensions

8.5x11" letters

Lob offers 8.5" x 11" letters in both black & white and in color, which can be printed single or double-sided. Letters and checks not exceeding 6 tri-folded sheets of paper in total will be sent in standard #10 double-windowed outer envelopes. Letters and checks over 6 sheets of paper but not exceeding 60 total sheets of paper will be mailed in a flat envelope.

Reference our design templates on where to place your design elements for letters; carefully note the placement of the address block.

  • Letter design template (for 6 sheets of paper or less)

  • Letter design template (for over 6 sheets of paper but not exceeding 60)

Lob standard letters cannot accommodate letters that bleed or print edge-to-edge. All text and design must be 1/16” from all sides leaving the required 1/16” clear space on all sides.

What is that small QR code printed on my letters?

What looks like a small QR code printed on letters is a data matrix, a type 2D barcode used by our print partners to encode information to facilitate efficient sorting, tracking, and delivery. Recipient attempts to scan this code won't direct anywhere, but cameras read these small barcodes during the automation process. Typically, this appears on the lower corner of letters (as noted on our templates), though some print partners may place it in the address block area (as shown below).

What is the difference between a page and a sheet of paper?

A "page" in the context of a Lob letter is a PDF page, while a "sheet" refers to the physical paper that is used to print the letter. Lob charges based on the length of a letter in PDF pages, while the length of a letter in sheets is used to determine what envelope a letter uses.

8.5x14” Letters (“Legal letters”)

Legal letters are exclusive to Enterprise edition customers. Upgrade your Print & Mail edition to gain access to this mail format, or reach out to our sales team to learn more.

Legal letters currently have a 4-day SLA.

Lob offers 8.5x14" letters in both black & white and in color, which can be printed single or double-sided.

Using two parallel folds, a legal-sized letter is folded in half, then folded again with a slight overlap (two edge panels will be slightly larger than the middle panels); this allows it to fit in a standard #10 double-windowed outer envelope. Legal letters cannot exceed 3 sheets of paper at this time.

Reference our design templates on where to place your design elements for letters; carefully note the placement of the address block.

  • Legal letter design template (3 sheets of paper or less)

Lob Legal letters cannot accommodate letters that bleed or print edge-to-edge. All text and design must be 1/16” from all sides leaving the required 1/16” clear space on all sides.

What is that small QR code printed on my letters?

What looks like a small QR code printed on letters is a data matrix, a type 2D barcode used by our print partners to encode information to facilitate efficient sorting, tracking, and delivery. Recipient attempts to scan this code won't direct anywhere, but cameras read these small barcodes during the automation process. Typically, this appears on the lower corner of letters (as noted on our templates), though some print partners may place it in the address block area (as shown below).

Paper specs

We use a few pre-approved papers across our commercial printer network. In ensuring uniform quality and consistency across all of our mail pieces, each paper source specification must fall within a small range. The specification/value range pairs are:

  • 8.5" x 11" B&W & color letters

    • Basis Weight: 60# text

    • C-fold letters

  • 8.5" x 14" B&W & color letters

    • Basis Weight: 60# text

    • Double parallel fold

Address placement

If you do not follow these address guidelines, your letter will be printed incorrectly.

The address_placement parameter specifies the location of the address information that will show through the double-window envelope. Options are top_first_page and insert_blank_page.

By default, Lob selects address_placement = top_first_page, meaning Lob will print address information at the top of your provided first page. Make sure to leave ample space for the address information to be printed, which will show through our standard double-windowed envelope. To see how this will impact your letter design, view our letter template (6 sheets or less).

Letters may shift slightly within their envelope during transit. As such, we do not recommend putting any sensitive content close to the window area.

If you pass address_placement = insert_blank_page, a blank address page will be inserted at the beginning of your file where we will print the address information to show through our standard double-windowed envelope.

If a blank address page is inserted, note that you will be charged for the extra page. Reference the Letter Unit Pricing section for charges you will incur based on your tier.

Logo placement

Your logo should be entirely within the blue box of the letter template, with no overlap of the red box, in order to print appropriately.

If you're looking to print a color logo then ensure you're setting the color parameter to 'true' if you would like to print in color otherwise you can set it to false.

Letter best practices

Ensure your letters get to their final destination by following these guidelines:

  • The from field is required for all letters, regardless of the destination

  • Letters may contain PII as envelopes have an interior security tint for privacy

  • Mailing class options may differ based on the destination and use case (e.g. promotional vs transactional)

Exporting mail data

Lob captures data for each mailpiece created and provides an easy way to export it as a CSV file. Exporting data allows for in-depth performance analysis, auditing, or other purposes, but we strongly recommend customers do this on a regular cadence for record-keeping and maintenance.

Lob’s will retain customer mailpiece data for a total period of ninety (90) days. See our data retention policy for further information.

Data available for download

Mailpiece details

ID, Description, URL, Color, Double Sided, Address Placement, Return Envelope, Perforated Page, Extra Service, Expected Delivery Date, Tracking Number, Mail Type, Size, Metadata, Date Created, Send Date, Merge Variables

Sender details

To.ID, To.Description, To.Name, To.Company, To.Phone, To.Email, To.Address Line1, To.Address Line2, To.Address City, To.Address State, To.Address Zip, To.Address Country, To.Metadata, To.Date Created

Recipient details

From.ID, From.Description, From.Name, From.Company, From.Phone, From.Email, From.Address Line1, From.Address Line2, From.Address City, From.Address State, From.Address Zip, From.Address Country, From.Metadata, From.Date Created

Tracking events (if applicable)

Regular Mail: Mailed, In Transit, In Local Area, Processed for Delivery, Re-Routed, Returned to Sender

Certified Mail: Mailed (Certified), In Transit (Certified), In Local Area (Certified), Processed for Delivery (Certified), Re-Routed (Certified), Returned to Sender (Certified), Delivered (Certified), Pickup Available (Certified), Issue (Certified)

Exporting your data from the Lob dashboard

  1. Log in to your Lob dashboard.

  2. In the left side menu of your dashboard, navigate to the appropriate mail format for which you'd like to download your data (e.g., "Postcards.")

3. Select the environment (Live or Test) from which to download your data. In our example below, "Test" environment is selected.

Recall that physical mail is only sent when requests are made in the Live Environment.

4. Filter for the date range you want mailing details.

This search is inclusive, i.e., the first date that will have information retrieved will be the Start Date from 00:00 UTC, and the last day of information returned will be the End Date up until 23:59 UTC.

If you are retrieving multiple years' worth of data, we recommend that you download one year at a time, as larger requests will require more time to generate.

Note that we have a limit of 250K rows per export at this point in time.

5. Once you have your filters selected, click "Apply" to filter on the range being displayed.

6. From this newly filtered view, select the "Export" button.

  • Export Tracking events: If you are exporting Live environment requests, and there are tracking events associated with them, a pop-up will appear to "Select Tracking Events." If you choose Yes, you will receive a second export of tracking events. You will have the option to include all events or a specific subset of events. Click "Submit."

  • A pop-up will show your data selections for the Product, Mode, and Date Range parameters. If you have selected to receive an additional CSV of tracking events, this will be noted. Once you are satisfied with your data selections, hit the “Confirm” option on the bottom right. Examples:

Test data export - no tracking events
Live data export - with tracking events

7. You will be emailed an export link to the report that you just requested. (This will be emailed to the user who is logged into the Lob dashboard making the request.)

Data export examples
Email examples

Test environment data export with no tracking events

Live environment data export with tracking events

Video walkthrough

If you have any questions regarding exporting your data, reach out to your Customer Success Manager or to [email protected].

Rendering errors

Lob occasionally encounters problems with the creative when rendering mailpieces; this can occur with either PDFs or HTML. To avoid sending out erroneous mailpieces, Lob provides visibility of these errors, with proactive notification of rendering errors in place.

We always recommend testing; and where possible, sending yourself a printed mailpiece.

PDF

Lob will fail incorrectly formatted PDFs. See our PDF preflight checklist here to ensure your file will process through our rendering engine.

HTML

Lob will fail HTML that includes inaccessible assets (images, fonts, any other URLs):

  • the link to an asset is incorrect

  • the asset referenced in the file is missing

  • Lob has not been given the correct permission to access the asset (ensure that the link is set to public viewing, and not private)

  • when a remote asset references a local asset (for example, a remote asset is at www.example.com which then references something local in that directory)

  • slow or under-resourced server providing the asset (we recommend using a performant service, such as Amazon S3, to host the content)

HTML Template Preview

If your HTML contains an inaccessible asset, your HTML preview will error. Details of the error will be displayed in a future release.

In the Campaigns UI flow

  • When creating your Campaign, you may be notified when you generate a Creative Proof (if the sample mailpiece that is rendered results in an error); if this occurs you should troubleshoot against the above list.

  • After placing the order, you will be notified in the dashboard, and the reason for the error will be provided (click to enlarge):

Campaigns - dashboard
Campaigns - Form factor (ex: Postcards)
Campaigns - Form factor (ex: Postcards)
Campaigns - order details
  • The Lob support team will proactively reach out.

API users

  • API customers will receive an error notification in the API response.

  • The Lob support team will proactively reach out.

Webhooks

Webhooks users can subscribe to receive notifications of failed orders. (Learn more about using webhooks here.)

  1. Under Webhooks in the dashboard, in the Live environment, click Create.

  2. Check [formfactor].failed; click Create.

self_mailer.failed also available

If subscribed to postcard.failed, letter.failed, and/or check.failed, and Lob fails an order during rendering, the following error messages are possible:

"Rendering failed due to asset issue:

  • The requested asset was not found: <asset link>"

  • The requested asset is not permitted: <asset link>"

  • Authentication is required to access the requested asset: <asset link>"

  • An internal server error occurred for: <asset link>"

  • The requested asset timed out: <asset link>"

  • An unknown server error occurred for: <asset link>"

  • The requested service is unavailable for: <asset link>"

  • An unknown error occurred for: <asset link>"

If not one of the most common errors above, or a PDF failure, "try re-render” will be returned.

If you are unable to resolve the error, please reach out to [email protected]

Declaring mail use type

Overview

Identifying your mail use type helps Lob populate the right mail settings and postage options to ensure your mail is produced and delivered in an optimal way. Lob requires that you identify—or tag—your mail with one of the following use type options:

  • Marketing mail: Any mailers that are sent for marketing, advertising, and promotional purposes

  • Operational mail: All other mail, typically transactional or functional in nature, such as invoices, adverse action notices, statements, and other confidential mail that include sensitive PII/PHI data

It will be your full responsibility to accurately represent the purpose of mail that is created and sent. Lob will be unable to make any determination of which use type should be applied to your mail being sent, or for making retroactive changes to your API calls.

How to declare your mail use type

You should declare your mail’s use type at the appropriate level based on your organization's usage (at the account, campaign, or mailpiece level).

1. Setting use type for an account (default)

If the majority of your mailpieces have a singular use type, then it is best to configure a default use type at the account level. This can be changed by an account administrator in the Use Type section in the Accounts Tab in the dashboard settings. An account-level setting will be applied to any mailpiece created without a use_type at the individual mailpiece or campaign level.

While an account-level designation is not required, the failure to declare a mail use type at any level means that in the absence of a default value, your organization will be prevented from sending any mail until a use type is declared.

To set an account-level default, go to your Dashboard Settings > Accounts tab:

2. Setting use types for each mailpiece

If you or your team sends mailpieces with varying use types (including different teams that utilize the same Lob account for different purposes), then it is best to declare your use types at the single mailpiece level or at the campaign level.

If you have built a native Lob integration to trigger individual mailpieces, you will want to configure a use type at the individual mailpiece level. A mailpiece designation will override your account-level use type, regardless of whether the default selection is made.

In the Dashboard

When sending a single mailpiece through the dashboard, use type will be a required selection for every mailpiece format (letters, postcards, self-mailers, or checks).

Example: Use Type selection when creating a new postcard in the Dashboard

In the API

When sending a POST request to the below endpoints, pass in a use_type value of either marketing or operational. Note that the account default will be overridden by passing in a use_type for each mailpiece. If no account default is set and no single endpoint-level use_type is passed in the request, the mailpiece cannot be created and will fail with a 422 error.

api.lob.com/v1/letters api.lob.com/v1/postcards api.lob.com/v1/self_mailers api.lob.com/v1/checks

Example: POST /v1/postcards request with use_type included

{
    "description": "demo",
    "to": "adr_42bb83a3a643c43f",
    "from": "adr_42bb83a3a643c43d",
    "front": "tmpl_a1234dddg",
    "back": "tmpl_a1234dddg",
    "size": "6x9",
    "mail_type": "usps_first_class",
    "use_type": "operational",
    "send_date": "2022-05-01T00:00:00.000Z"
} 

3. Setting use types for each campaign

The Campaigns product is designed to help send large volumes of mail quickly, either through the dashboard or Campaigns API.

If you have built a native Lob integration to send mail campaigns, you will want to configure a use type at the campaign level. A campaign-level designation will override your account-level mail use type, regardless of whether the default selection is made.

In the Dashboard

When sending a Campaign on the dashboard, selecting a campaign use type is a required step during the “Configure campaign” page in Step 1. You will be able to select one of two options: Marketing or Operational. Any selection will be applied to all mailpieces within the same campaign.

Example:

In the API

When using the Campaigns API, add the use_type field to the POST /v1/campaigns request. If the use_type is not added, the campaign will use the account default use_type. If no account default is set and no campaign-level use_type is passed in the request, the campaign cannot be created and will fail with a 422 error.

Example: POST /v1/campaigns request with use_type included

{
    "name": "Summer Campaign",
    "description": "Acquisition for new customers",
    "schedule_type": "immediate",
    "cancel_window_campaign_minutes": 40,
    "use_type": "marketing"
}

Error reference

If no account default is set and no campaign or mailpiece use_type field is passed in your API requests, your calls will fail with a 422 error.

Read more about error codes under the "Error Codes - Advanced" section of our API Reference.

To ensure your mail sends do not fail in the future, we strongly recommend you set an account default as a fall-back option as soon as possible

Creative formatting

Every form factor starts with your creative, or the content of your mail piece. Lob’s core technology is built around modern APIs that remove the typical complexities and limitations of the print and mail industry. We can accept static PDFs, but similar to email sends, HTML enables dynamic personalization so each and every mail piece is unique.

Example mail pieces

Artboard or layout templates can be found under each mail format (see ). Or, visit Lob's on our website for pre-designed templates to help you get started; you can download these to use as inspiration and a guide to create your own designs.

File formats for creative

HTML for dynamic creatives

We recommend designing your direct mail in HTML to enable personalized content at scale. HTML allows you to include dynamic merge variables, similar to how you would personalize an email campaign, to maximize engagement and conversions.

See for more details on how to take advantage of HTML and merge variables.

PDFs for static creatives

You can submit your creative file in PDF format, but keep in mind that PDFs are static and don’t support personalization.

We ask that you follow our PDF formatting guidelines outlined in our to help ensure successful and accurate printing. Here are some tips to

Font formats

Supported fonts

All fonts in any PDFs you provide should be embedded. Embedding a font in a PDF ensures that the final printed product will look as it was designed. Fonts can vary greatly in size and shape, even within the same family. If the exact font used to design the artwork is not used to print, the look and placement of the text is not guaranteed to be the same.

We make an exception for "standard fonts," a set of fonts that we have identified as being common. Otherwise, the request will be rejected. See our full list of in our API docs.

We support the following web font formats:

  • TTF

  • SVG

  • EOT

  • Google web fonts

  • Custom fonts within your HTML templates (any links must be to Lob)

Unsupported fonts

  • OTF ( into another type we support)

  • Type 1 fonts (Exception: standard base14 fonts)

  • Type 3 fonts

  • (These fonts require white-listing a specific domain, which Lob is unable to do. We recommend hosting the font yourself and using it within your HTML, or finding an appropriate non-Typekit font to replace it with.)

Image formats

PNG: This is a raster image format that can have a transparent background. It is generally of higher quality than other image formats.

JPEG: This is a raster image format that is often used for photographs. It does not allow for a transparent background.

When using PNGs or JPEGs with Lob, we require a minimum of 300 dpi. The dpi is calculated as (width of image in pixels) / (width of product in inches) and (length of image in pixels) / (length of product in inches). For example: 1275px x 1875px image used to create a 4.25" x 6.25" postcard has a dpi of 300. It is also recommended that you don't greatly exceed 300 dpi, as this will result in unnecessary additional file size.

Submitted images must have the same length-to-width ratio as the chosen product. Images will not be cropped or stretched by the API.

Hosting content

When you pass an image or send HTML in your API request, Lob will then render and host the content.

If you are sending at high volumes, we recommend you host the content yourself on a performant file hosting provider, such as Amazon S3, and send Lob a hosting URL to the content in your API request. This will reduce your API request time.

All URLs must be accessible. For example, broken links, missing files, and incorrect permissions will all cause mail pieces to fail. See here if you are experiencing

Design tools

We highly recommend using the Adobe Creative Suite (Adobe Illustrator, Photoshop, or InDesign) to design your content. This will give you design flexibility and multiple export options.

Please note that PNG files are RGB only—to prepare a file for printing, our rendering engine must convert this color profile to CMYK. During this conversion, there may be a slight variance in color that would impact the print result. If you require a very specific color experience (to abide by brand guidelines for example), then we recommend providing a PDF file and/or evaluating the color in Adobe Photoshop Pro.

Converting from PDF to HTML

If you want to take advantage of the personalization opportunities of HTML, we recommend using a developer to convert your PDF designs to HTML. We'd estimate 15 minutes to 2 hours of development time for the average file. Some applications like Adobe Illustrator come with HTML export options, but note that their exports won't typically produce HTML that conforms to Lob's requirements.

Need help with converting your creative files to HTML? You can now easily import your creative from popular design programs and quickly spin up merge variables. See for more info on our design tool integrations.

Proofing

To see how your HTML is rendered, create a Test API request either through the API or view a preview in the dashboard (HTML templates). Lob's HTML renderer is based on Webkit. For this reason, using the Safari browser will show previews more accurately.

This works for PDFs as well as long as the submitted PDF follows If a PDF not following guidelines is submitted, the rendered proof may not reflect the final printed product.

If using Campaigns in the dashboard, the Creative Proof will render and present a single mail piece. (It will include merge variables, address block, Lob carbon-neutral logo, and indicia, plus return address and QR codes if included.)

We highly recommend sending yourself a printed piece to validate the mail piece's appearance.

Why does my design render differently with Lob than it does with my design tool?

This difference is likely due to variations found in the rendering engine of your design tool vs. web-based browser, which seemingly results in slight deviations.

  • Design tools and web browsers are different mediums with different font-rendering engines. Put simply, design tools do not render based on CSS and HTML, as they are not web browsers. Different browsers (e.g., Safari vs. Chrome browsers) will show variations in rendering as well.

  • Points, for measuring typeface, are not a precise measurement. Point size (or ‘pt’) refers to the bounding box of the letter — not the letter itself. Differences in font files and rendering engines may also add to the rendering discrepancy.

    • For example, if you create a PDF in Adobe InDesign, that tool’s rendering engine will define “11pt” font differently than what Lob’s web-based rendering engine defines “11pt” to be. Points, for measuring typeface, are not a precise measurement. In metal type, point size refers to the height of the metal body on which a typeface’s character is cast. In digital typefaces, the metal body is replaced by an invisible box known as the em square. Each character fits inside that em square or em box. The em size of a font is equal to its point size. The point size is also used to measure leading (line-height), line length and other elements, apart from font size.

    • Given the point size system is not based on a universal standard, any differences that exist are likely due to rendering engines. It is best practice to review requests in your Test Environment, prior to requesting them in the Live environment.

  • The rendered image can also vary based on the DPI (Dots per Inch: a measure of the resolution of a printed document or digital scan) and zoom settings of your design tool vs. your web browser.

Why is the content of my mail missing?

If you are receiving a blank PDF when trying to render content, but the content of the link is not blank, it may be that the link was not performant. In order to avoid such issues, we recommend using a performant service, such as Amazon S3, to host the content.

In order for this content to be visible, ensure that the link is set to public viewing, and not private, as this is one of the common reasons why content may appear as missing or blank in your creative.

What are these smudges on my postcards and/or self-mailers?

are an industry-wide issue that has been extensively researched by our Production team. We've found that the USPS's high-speed sorting machines are what typically cause these scuff marks. If postcards or self-mailers get exposed to the belts for a millisecond longer than they're supposed to, they're at the risk of getting abrasions. This is not an isolated incident for our printer or for our mailers. Below links are a few articles that further explain the issue with examples of how these would look like.

We are unfortunately unable to provide a refund or credits for these smudge marks.

Mailing class and postage

What are mailing classes?

As Lob leverages USPS as our mail delivery carrier, the USPS offers a number of mailing services to suit the needs of the business. Leverage different mailing class options based on your time sensitivity, budget, and need for other adjacent services.

First Class Mail

  • Used to send Lob postcards, self-mailers, letters, and checks

    • Intended mostly for personal or business correspondence

    • Invoices, statements, and other confidential mail that include PII/PHI or sensitive data of any kind must be sent via First Class or risk being flagged by USPS and taken out of the mail stream

    • Businesses have the option of adding on additional services, like Certified Mail

  • Must weigh 13oz or less; anything over 13oz can be sent as Priority Mail

  • First Class delivery is given priority over Standard Class Mail, both locally & nationally

  • Includes forwarding and return services with no additional charge

  • Domestic mailings typically take 4-6 business days, and international mailings typically take an additional 5-7 business days to be delivered

Standard Class Mail or Marketing Mail

  • Broadly known as Marketing Mail, or "bulk mail" in the industry

    • Lob will often refer to it by its previous name, Standard Class Mail, in our product offerings

  • Used to send Lob postcards, self-mailers, and letters with marketing-related content

    • Intended more for advertisements and mass communication purposes

    • Must not contain any sort of sensitive personal information or PII outside the address box

  • Must weigh 16oz or less, and meet a minimum quantity of 200 pieces or 50lbs of mail

  • Processed by USPS on a "time available" basis; no delivery time guarantees provided by USPS

    • Best to avoid with time-sensitive mailings

  • Least expensive postage mode available on Lob

  • Mailings typically take 7-21 business days (only available in US)

  • Standard Class mail cannot be sent internationally

  • Standard Class mail is not forwarded or returned if undeliverable unless a special endorsement is used; undeliverable mail will be destroyed by USPS

Any mailpiece that contains PII or PHI must be sent as First Class and cannot be sent as Standard Class Mail per USPS regulations. Non-compliance will result in potential removal of your mail batch from the mailstream, customer delays, and/or order cancellation.

USPS Marketing Mail eligibility

As marketers are adding greater amounts of "personal information" in their direct mailings that include advertising mailers typically sent as USPS Standard Class or Marketing Mail, around which class of mail can be utilized given the level of "personal information" included in your mailers.

These have been in effect since June 1, 2005, and are enforced at the discretion of the USPS Customer Support Rulings agent. The main conclusion: Standard Class (aka Marketing Mail) should not be utilized for sending mail that includes personal information or sensitive data in any way.

If you are planning any Marketing Mail campaigns that include the personal information of the recipient, make sure to mail it First Class to avoid USPS rejection which will result in delays for your mail.

Lob cannot currently prevent customers from sending personal information or sensitive data as Standard Class Mail. Consult your Customer Support Manager for further guidance on eligibility.

Available mailing class options

Postcards

  • 4x6, 6x9 and 6x11 postcards: Mailed via USPS First Class Mail (takes 4-6 business days and international mailings take an additional 5-7 business days).

  • 4x6, 6x9 and 6x11 postcards: Mailed via USPS Standard Class Mail (takes 7-21 business days) and only within the US.

Self-mailers

  • Mailed via USPS First Class Mail or Standard Class Mail

  • USPS Standard Class Mail may only be used for sends within the US

Letters

  • Mailed via USPS First Class Mail (takes 4-6 business days)

  • Mailed via USPS Standard Class Mail (takes 7-21 business days) and only within the US

Checks

  • Mailed via USPS First Class only (takes 4-6 business days)

    • USPS Standard Class Mail is not available for checks

  • Overnight/expedited mailing options are not available

Postage

Our fulfillment partners programmatically print their own indicia on all postcards and self-mailers. This indicia is then used to prepare the mailing paperwork for USPS. There is no need to mark the in your submitted creatives.

Our return envelopes are blank and come without prepaid postage; mail recipients will be responsible for adding their own postage when sending reply mail.

Mail collection & cut-off times

Our daily cut-off times for all mail submissions are 10am PST each business day; anything submitted after that will be processed in the following business day's production run.

Remember: if you use the or and your send date surpass a daily cut-off time, it will be slotted for the next production day. Production days are based on normal business days, including .

If you have more questions regarding cut-off times, reach out to [email protected] or your Customer Success Manager.

Lob's Print Delivery Network (PDN)

Lob's Print Delivery Network (PDN) is the backbone of our Print & Mail offering. By building an integrated, distributed network of professional printers, we simplify client print operations and vendor management on behalf of our customers. Qualified commercial printers are thoroughly vetted by our print experts and integrated into our PDN ecosystem, enabling our customers to easily access different mail delivery strategies without the hassle of management. The strength of our PDN is predicated on automated production, dynamically-adjusted throughput, and consistency of quality that's on-demand and at scale.

Any mail that is sent through Lob is dynamically distributed to the prints within our PDN, based on a number of factors, including:

  • Mail form factor and permutation availability

  • Mail volume capacity

  • Paper stock and ink availability

  • Distance from end-recipient of mail

  • Other manufacturing and logistical capacity needs

  • Regulatory requirements (e.g. HIPAA)

If you're a printer that's interested in exploring a partnership opportunity with us, !

AV pricing

Full price list for Address Verification API

US verification

Developer
Startup
Business
Growth
Enterprise
  • US Autocomplete is included in all plans

  • Zip Lookups count toward US Verification usage

International address verification

Developer
Startup
Business
Growth
Enterprise

International autocomplete

International address autocompletion for non-US addresses is not currently available. If you believe this feature is integral to your business, please reach out to to see if we can support your needs.

Add-Ons

In 2025, USPS is offering Add-on Promotions that provide additional postage discounts for mailpieces that already qualify for regular USPS promotions.

Add-ons are designed to help you save even more by meeting specific criteria alongside your standard promotional mailings. Explore the details below to see how Lob can support you in applying for these extra savings.

Informed Delivery

What is the Informed Delivery add-on?

Informed Delivery by USPS enhances the traditional mail experience by providing subscribers with a daily email preview of their incoming mail. This preview includes either a representative image or an actual scan of the mailpiece.

The email also includes a ride-along image: a small, full-color, interactive image that links to a target URL. This additional content reinforces your mailpiece’s messaging and call-to-action while providing a digital touchpoint for engagement.

In order to qualify for the Informed Delivery Add-On, your mailpiece has to qualify and be approved for a promotion as well. A mailpiece that does not have a promotion attached to it will not receive the 1% discount.

Why should mailers use Informed Delivery?

Combining direct mail with digital technologies, such as Informed Delivery, amplifies campaign success by connecting physical and digital marketing strategies.

Key benefits

  • Increased customer engagement: Seamlessly integrates physical mail with digital campaigns, enhancing interaction.

  • Extended marketing reach: Adds a supplemental digital footprint for your mail campaign at no extra cost.

  • Attribution data: Provides actionable insights into campaign performance, helping refine future strategies.

Impressive reach

As of March 2024, 62.4 million users are actively subscribed to USPS’s Informed Delivery program, providing a substantial and growing audience for your campaigns.

How can I sign up for Informed Delivery through Lob?

Step 1: Sign up for the Informed Delivery promotion

  1. Log into the Lob Dashboard:

    1. Navigate to Billing > Promotions, and click Create an Informed Delivery Promotion.

  2. Enter promotion details:

    1. Promotion Name

    2. Promotional URL (where the ride-along image will redirect users)

    3. Upload your Ride-Along Image

  3. Ride-along image specifications:

    1. Format: Full-color JPG

    2. Dimensions: 200x300 pixels

    3. Max File Size: 200KB

  4. Submit for approval:

    1. Click Create an Informed Delivery Promotion to send your application to USPS.

    2. Allow 3–5 business days for approval and watch for email notification once approved.

Step 2: Send an Informed Delivery Campaign

You can send an Informed Delivery campaign via API or Campaigns in Lob.

Option 1: Send via API

  1. POST campaign data:

    1. Use the Lob API to send the informed_delivery_campaign and retrieve a campaign_id.

  2. Include required fields:

    1. Promotional URL

    2. Campaign size

  3. Optional fields:

    1. Brand name: Defaults to the company name in Lob unless specified.

    2. Representative image: A sample image of the mailpiece. This should reflect all mailers in the campaign and must not include PII. If omitted, USPS will display a scan of the mailpiece instead.

  4. Validate campaign: After a successful POST, receive the campaign_id and confirm qualification for existing promotions.

  5. Send mail: Include the informed_delivery_campaign_id in your submission to Lob as usual.

Option 2: Send via Lob Campaigns

  1. Set up campaign:

    1. Begin your campaign setup in Lob Campaigns.

  2. Enable Informed Delivery:

    1. When prompted, select the option to use Informed Delivery.

    2. Choose from available approved promotions obtained in Step 1.

  3. Enter campaign details:

    1. Promotional URL

    2. Upload the Ride-Along Image.

  4. Ride-Along Image specifications:

    1. Format: JPG

    2. Dimensions: 500x780 pixels

    3. Max file size: 200KB

  5. Optional fields:

    1. Brand name: Appears in the Informed Delivery email sent to subscribers. Defaults to your company name in Lob unless customized.

    2. Representative image: A sample of your mailpiece (similar rules as for API campaigns apply).

  6. Launch campaign:

    1. Complete your setup and submit. Lob ensures that the mailpiece adheres to USPS’s Informed Delivery standards.

Sustainability

What is the USPS Sustainability Add-On?

The USPS Sustainability Add-On rewards businesses that use environmentally friendly materials in their print production by offering an additional 1% discount on all eligible mailpieces. This add-on promotes eco-conscious practices and helps businesses reduce their environmental impact.

How can I take advantage of the USPS Sustainability Add-On through Lob?

As long as you opt into the Sustainability Add-On in the USPS Promotions Portal, any mailpiece tied to a USPS promotion will automatically receive the 1% sustainability discount add-on.

Billed annually

$0

$20

$100

$390

Talk to Sales

Billed monthly

$0

$25

$120

$450

Talk to Sales

# of API requests included/month

300

1,000

10,000

50,000

Talk to Sales

$ per add'l request (billed annually)

N/A

$0.020

$0.010

$0.008

$0.000

$ per add'l request (billed monthly)

$0.050

$0.025

$0.012

$0.009

$0.000

Billed annually

$0

$25

$95

$465

Talk to Sales

Billed monthly

$0

$30

$115

$550

Talk to Sales

# of API requests included/month

0

500

2,000

10,000

Talk to Sales

$ per add'l request (billed annually)

N/A

$0.050

$0.048

$0.047

Talk to Sales

$ per add'l request (billed monthly)

$0.070

$0.060

$0.058

$0.055

Talk to Sales

support
Ride-along image
Mail piece design specs
Template Gallery
dynamic personalization
PDF preflight checklist
create print-ready PDFs with InDesign.
supported PDF Fonts
accessible
Can be converted
Adobe (Typekit) fonts
rendering errors.
Creative conversion tools
our guidelines.
Smears and smudges
Example translation of HTML for a postcard front

Send campaigns via the Campaigns API

This functionality is in beta. Please reach out to [email protected] or your Account Manager with any feedback or feature requests.

Use our Campaigns API to send your large-scale direct mail campaign sends more programmatically.

When creating campaigns, you’ll interact with 3 main models: campaigns, creatives, and uploads.

  • The campaigns model is used to set up high-level information about your campaign

  • The creatives model is used for uploading artwork and artwork settings for your campaign

  • The uploads model is used to build your audience and configure any recipient-level details for your campaign

Follow the steps below to create your first campaign in the API.

Step 1: Create your campaign

Endpoint: POST api.lob.com/v1/campaigns Documentation: Create Campaign

First, create your campaign. At a minimum, your campaign needs a name and a schedule_type and a use_type if one has not been declared at the account level. It is highly recommended that a cancel_window_campaign_minutes is provided given it will allow you to cancel the campaign within the specified window if needed.

{ 
    "name": "Demo Campaign",
    "schedule_type": "immediate",
    "use_type": "marketing",
    "cancel_window_campaign_minutes": "120"
}

Step 2: Add creative

Endpoint: POST api.lob.com/v1/creatives Documentation: Create Creatives

The next step is to create your creative object that will be associated with the campaign. You can only associate a single creative with a campaign. You are required to add a campaign_id, resource_type, and any requirements for your selected resource_type. This payload is subject to change depending on your form factor. See examples below.

{ 
    "campaign_id": "campaign_id",
    "resource_type": "postcard",
    "front": "{{pdf || url || template_id}}",
    "back": "{{pdf || url || template_id}}",
    "details": {
        "size": "4x6",
        "mail_type": "usps_standard_class",
    }
}

Note: the details section has additional optional parameters, see docs for more info.

{ 
    "campaign_id": "campaign_id",
    "resource_type": "letter",
    "file": "{{pdf || url || template_id}}",
    "from": {
        "name": "Lob.com",
        "address_line1": "210 King St.",
        "address_city": "San Francisco",
        "address_state": "CA",
        "address_zip": "94107"
    }
    "details": {
        "color": true,
        "mail_type": "usps_standard_class"
    }
}

Step 3: Map columns from your data file to specified fields

Endpoint: POST api.lob.com/v1/uploads Documentation: Create Upload

Uploading your audience data file is the next step. Step 3 can be done prior to Step 2 as well. For more information on how to best structure your upload for Steps 3 and 4, visit our campaign audience guide.

If using optionalAddressColumnMapping, all fields must be specified (which means unused fields must be declared with a null value). If you're using an HTML template, double check that you have provided all keys and values for mergeVariableColumnMapping, if not all merge variables are mapped, your campaign will not be executable when it comes time to send.

{
    "campaignId": "{{campaign_id}}",
    "requiredAddressColumnMapping": {
        "name": "recipient",
        "address_line1": "address_line1",
        "address_city": "address_city",
        "address_state": "address_state",
        "address_zip": "address_zip"
    },
    "optionalAddressColumnMapping": {
        "address_line2": "address_line2",
        "company": null,
        "address_country": null
    },
    "mergeVariableColumnMapping": {
        "date": "date",
        "firstName": "firstName",
        ...
        "qr_url": "qr_url"
    },
    "metadata": {
        "columns": [
            "email"
        ]
    }
}

Step 4: Upload your file

Endpoint: POST api.lob.com/v1/uploads/{{upload_id}}/file Documentation: Upload File

After creating your upload object, you can now upload your file as a byte stream (binary file).

{ 
    "file": "{{file.csv}}"
}

Step 5: Execute your campaign

Endpoint: POST api.lob.com/v1/campaigns/{{campaign_id}}/send Documentation: Send Campaign

Finally, you can execute your campaign! To see the status of your mail pieces as they are created, use the GET api.lob.com/v1/uploads/{{upload_id}} endpoint.

{
   "is_draft": "false"
}

Step 6: Get failed addresses

Endpoint: POST api.lob.com/v1/uploads/{{upload_id}}/exports Documentation: Create Export

First, let us know that you would like to create a failure export. Your response will include an export ID, which will be used to retrieve the export URL in the next step.

{
   "type": "failures"
}

Endpoint: GET api.lob.com/v1/uploads/{{upload_id}}/exports/{{export_id}} Documentation: Retrieve Export

You can then retrieve the S3 URL of the export from the GET response above. Your export will include row-level details on why each record failed.

Step 7: Cancel your campaign

Endpoint: DELETE api.lob.com/v1/campaigns Documentation: Delete Campaign

As long as your campaign cancellation window has not passed, you can cancel your campaign using our DELETE route on the campaigns endpoint.

And that's it! If you have any questions, feel free to reach out to your Customer Success Manager, or to [email protected].

Dynamic table tutorial

In-depth tutorial of how to neatly break apart sets of data into paginated segments

For certain use cases, you may need a table of dynamic length. These tables should not have rows that are divided between pages, and you may need a header for each page. This tutorial breaks down how to create them using the Handlebars engine.

The tools

{{withGroup}}

This will allow you to group elements into the subarrays that will make each page of the dynamic table

{{each}}

This allows you to iterate over each "row" in the withGroup subarrays.

{{if}}

In this case, we're using the if statement to evaluate whether or not we're at the absolute final row for the entirety of our table

The template

CSS / HTML

        body {
            width: 8.5in;
            height: 11in;
            margin: 0
        }
        .page {
            page-break-after: always;
            position: relative;
            width: 8.5in;
            height: 11in;
        }
        table {
            border-spacing: 5px;
            margin-left: .35in;
        }

        td {
            vertical-align: top;
            text-align: left;
        }

        tr {
            font-size: 14;
        }

        tr:nth-child(odd) {
            background-color: #e4e4e4;
        }
    {{#withGroup items 9}}
    <div id="d2" class="page">
        <table>
            <thead class="columnheaders">
                <th colspan="6" style="font-size: 20">Your Invoice</th>
                <tr>
                    <th style="font-size: 20">Date of Service</th>
                    <th style="font-size: 20">Service</th>
                    <th style="font-size: 20">Provider</th>
                    <th style="font-size: 20">Charge</th>
                </tr>
            </thead>
            <tbody class="columnwrapper">
                {{#each this}}
                    <tr class="wrapper">
                        <td><b>{{dateOfService}}</td>
                        <td><b>{{provider}}</b></td>
                        <td><b>{{service}}</td>
                        <td><b>${{cost}}</b></td>
                    </tr>
                    {{#if superlast}}
                        <th colspan="6" style="font-size: 20">Thank you for choosing Lob for your services {{../../first_name}}!</th>
                    {{/if}}
                {{/each}}
            </tbody>
        </table>   
    </div>
    {{/withGroup}}

Within our template, let's place a table and use {{withGroup}}to break apart our rows merge variable parameter into 9 groups per page, or {{withGroup rows 9}}. We have chosen 9 because we have already determined that any more rows than this would spill into the following page. This of course, means that going into this, you'll need an idea of how much space each row will take.

Then, we'll use {{each}} to iterate over each of the 9 rows per page and access nested elements within the row.

Lastly, we'll use {{if superlast}} to evaluate if the row we're iterating over is truly the last in the spreadsheet. In our JSON, the last item of rows will have parameter superlast equal to true, which triggers this portion off. This logic enables the ability to append a footer to the last page in our spreadsheet.

You'll notice that within this section, we include {{../../first_name}}, this is because we're referencing the merge variable first_name two scopes up (one out of the each loop, one out of the withGroup loop).

The JSON merge variable data

When we're ready to merge_variables , we'll need to include our complete array of rows. Note the last item in "rows" has an extra parameter superlast which is set to true

    "merge_variables": {
        "first_name": "Michael",
        "rows": [
            {
                "service": "Eye Exam",
                "provider": "Dr. Mobius",
                "cost": "200",
                "dateOfService": "2/23/23"
            },
            {
                "service": "General Checkup",
                "provider": "Dr. Murphey",
                "cost": "300",
                "dateOfService": "1/23/23"
            },
            {
                "service": "Perscription Evaluation",
                "provider": "Dr. Mario",
                "cost": "200",
                "dateOfService": "1/19/23"
            },
...
...
            {
                "service": "Blood Test",
                "provider": "Dr. Morbius",
                "cost": "100",
                "dateOfService": "1/22/23",
                "superlast": true
            },
        ]
    }

Making the requests

Once we've implemented the logic for dynamic tables into our own templates, we can post to the /templates endpoint, making sure that the engine parameter is set to handlebars. This will provide back a template reference id. We can then use this in the file parameter for the /letters endpoint. For more information on advanced template creation and request submission see the associated hyperlinks.

USPS has added greater scrutiny
Marketing Mail eligibility standards
location of your indicia
cancellation window
scheduling feature
National Holidays
let's talk

Additional Lob NCOA functionality

Customers must meet certain requirements to access this additional NCOA functionality. Please review the below and reach out to your Account Manager to see if you are eligible.

NCOA overview

National Change of Address (NCOA) is a service offered by the USPS, which allows individuals or businesses who have recently moved within the US to have any mail forwarded from their previous address to their new address.

As a CASS-certified Address Verification Provider, all mail sent through Lob Mail will be run through CASS and NCOA, as these are requirements for sending with USPS. Addresses will be corrected to reflect an individual's or business's new address in the case that they have moved (only if they have registered an NCOA with the USPS). The National Change of Address (NCOALink) database check only runs for US-based addresses. It does not run for non-US addresses or for non-deliverable US addresses.

Additional Lob NCOA functionality

Lob also offers additional NCOA functionality to our Print & Mail customers, providing more visibility. Customers must meet certain requirements in order to access this functionality; please review the below and reach out to your Account Manager to see if you are eligible.

Signing a Processing Acknowledgement Form (PAF)

In order to have the Lob NCOA report feature enabled, our customers must sign a Processing Acknowledgement Form (PAF), which is required by the USPS. NCOA reporting cannot be enabled if a PAF has not been signed.

Reach out to your Account Manager to see if you are eligible to sign a PAF.

API-related changes

Due to privacy concerns and USPS constraints, for customers with the NCOA feature enabled, our API responses for a limited set of endpoints differ slightly in the case when an address has been changed through NCOA.

Endpoints affected

With Lob NCOA feature enabled, there are no changes to API requests sent to Lob. This is true whether you are using our client-facing libraries, or making raw HTTP(S) requests to our API. If you have Lob NCOA reporting enabled, all live API requests to the following endpoints will be run through NCOA. However, there are some changes to the API responses for the following endpoints:

  • POST /v1/addresses

  • POST /v1/checks

  • POST /v1/letters

  • POST /v1/self_mailers

  • POST /v1/postcards

  • POST /v1/campaigns

  • POST /v1/uploads

Response format

Though there are no changes to API requests received, there are significant changes to our API responses, but only in the event that an address has been changed through NCOA. If an address has not been changed through NCOA, the response would be identical to our standard API responses, except with the addition of a recipient_moved field, which is false for unchanged addresses.

Due to the USPS constraints mentioned above, if an address has been changed through NCOA, we are required to suppress the following response fields for that address:

  • address_line1

  • address_line2

  • The +4 portion of the ZIP+4 (5-digit ZIP code will still be present).

How do I know if an address went through NCOA?

The black boxes in the address block mean the address went through our National Change of Address (NCOA) process. If you ever see the primary and secondary lines blotted out but not the city, state, and zip (without plus 4), that likely means it has gone through NCOA. If you’d like to know if an address went through NCOA, you’re also welcome to reach out to Lob support.

Below is an example of how this would look like in your Lob dashboard.

In addition, if an address has been changed through NCOA, the address will have a recipient_moved: true flag. For more details about the response format, see the NCOA information in our API docs.

In addition to our API responses, the suppressed fields will (almost) always be suppressed in other places within the Lob platform as well. This includes:

  • In the PDF proofs and thumbnails generated for Print & Mail requests

  • In Exports for Postcards, Self-Mailers, Letters, Checks and Addresses resources

  • API Logs & Event Logs

  • Webhooks

  • Dashboard Search

There are two locations where these fields are not suppressed:

  • In the physical mail piece that will be sent to your customer.

  • In an NCOA export from the Lob Dashboard (discussed in more detail below).

The NCOA export is the only way in which you will be able to access the suppressed response data for addresses that have been changed through NCOA.

Accessing suppressed data

In order to allow our customers to access NCOA'd data, the USPS has given us the following constraint:

Customers must send at least 100 addresses through NCOA within one week in order to gain access to NCOA'd data.

This means that in order to access this data, you must send at least 100 live API requests in a one-week time span to any of the following endpoints:

  • POST /v1/addresses

  • POST /v1/checks

  • POST /v1/letters

  • POST /v1/self_mailers

  • POST /v1/postcards

  • POST /v1/campaigns

  • POST /v1/uploads

Additionally, the USPS has defined a "week" to be the following time ranges:

  • 1st-7th of the month (inclusive)

  • 8th-14th of the month (inclusive)

  • 15th-21st of the month (inclusive)

  • 22nd-28th of the month (inclusive)

  • 29th-30th or 31st of the month (inclusive, when a month has more than 28 days)

Once you have sent at least 100 live API requests in a one-week time span, you can access suppressed data through an NCOA export, which can be accessed in the Lob Dashboard Settings, under the Reporting tab.

Once in the Reporting Tab, you can select any week from the previous month or the current month, and generate an export for that week. Additionally, you have the option of only exporting addresses that have been changed during the NCOA process. This option is selected by default, as this tends to be the more useful option.

Once you have clicked the "Export" button, an email should arrive in your inbox with the exported data. Depending on how many requests you've sent and how many addresses have been changed through NCOA, this can take anywhere from a few seconds to a few hours.

The export is a CSV, which has the following fields:

  • id - The Address ID (not the mailpiece ID) for the address that has been changed.

  • name - The name passed with the API request.

  • company - The company passed with the API request.

  • phone - The phone passed with the API request.

  • email - The email passed with the API request.

  • address_line1 - The full, unsuppressed address_line1, which represents the new address for the recipient.

  • address_line2 - The full, unsuppressed address_line2, part of the new address for the recipient.

  • address_city - The city of the recipient's new address.

  • address_state - The state of the recipient's new address.

  • address_zip - The ZIP code (including the +4) of the recipient's new address.

  • address_country - The country of the recipient's new address. Always UNITED STATES.

  • metadata - The metadata associated with this address.

  • date_created - The timestamp this address was created.

One important thing to note is that the export only includes an address ID, and not a resource (postcard/self-mailer/letter/check) ID. This means that you must keep track of address ID for inline addresses created in Postcard, Self-Mailer, Letter and Check requests.

Usually, NCOA records get updated once every two weeks contingent on USPS updating their internal database. Since this is a recipient-led process, Lob does not have control over how often NCOA changes happen nor how often the database is updated by USPS.

Whenever you send a mailing through Lob, you reap the benefits of accurate address cleansing and verification powered by our CASS-Certified Address Verification API. Verifying addresses is a necessary part of sending mail at scale, to optimize the efficiency and accuracy of your mail delivery.

Iterable

Overview

Iterable is a cross-channel marketing platform that powers unified customer experiences and empowers you to create, optimize and measure every interaction across the entire customer journey. Automated connections in Iterable, called (Journey) Webhooks, can be set up in minutes with no coding. Webhooks can automate your day-to-day tasks and enable workflows with Lob that otherwise wouldn't be possible.

Each Webhook you create will connect to an HTML template that you have stored in your Lob account. You will map your Iterable data fields to the dynamic Lob merge variables in the HTML template, and trigger mail sends via either an individual user action (such as email unsubscribe, for example) or to a group of users via a batch send.

Getting started with Iterable

To get started with Iterable, you will need to sign up directly with Iterable (see Request Demo) or have your Iterable account enabled by your company.

Getting started with Lob

Sign up for a free Lob account; from there you can jump right in with sending requests for free with your secret Test API key. Instantly begin sending real mail by simply adding a payment method to your account and switching to your Live API key.

Connecting Iterable to Lob

  1. Login to your Iterable Account.

  2. Navigate to "Integrations" -> “Journey Webhooks”

  3. Now click on "New Webhook" near the top of the page.

4. Configure as follows:

a. Endpoint: Make sure the URL matches the resource you want to create (i.e., that you are sending postcard requests to the postcard endpoint). See URLs here.

b. Authentication: None

c. Custom headers: Use the Authorization Header and your Base64 Encoded API key to connect your Lob account

  • We recommend using your Test Lob API Key in order to test and validate your integration. Then switch to your Live API key when you are ready to send mail.

  • You can use a Base64 Encoder tool to encode your (test) API Key.

  • Use the encoded key as the value for the Authorization header and that you are base64-encoding your secret API key with a colon after the key. For example, the API key test_abc123 should be encoded as test_abc123:, which becomes dGVzdF9hYmMxMjM6.

d. Body: select ‘URL-encoded Form’, then add form fields below to map the required Lob parameters to the associated attributes within Iterable. Example:

  • The fields on the left are the required Lob request parameters, and your corresponding data fields are on the right.

  • The right column is where you can dynamically map to Iterable attributes, by using the corresponding Iterable variable for a given attribute.

  • Iterable variables will need to be enclosed like so: {{your_variable}}. For example, if you have a field that maps to “to{name}” in your data and you want the variable first_name to be used as that mapping, you would put {{first_name}} next to the “to{name}” field on this page.

  • Be sure to map to all of the necessary merge variables. For example, if you have a merge variable “name” in your template you need to add a form field of “merge_variables[name]” and set the desired value on the right.

5. Click 'Create Webhook.'

6. Ensure you are mapping all the required templates.

  • Postcards and Self-Mailers will utilize two templates, one each for the front and back of the postcards.

  • Letters have just one template, mapped to the parameter ‘file’ on the left side.

7. Click 'Save' on the right when you are finished.

8. Navigate "Messenging" -> "Journeys" (previously called “Workflows”)

9. Click on the Journey you want to incorporate this webhook into, or create a new Journey.

10. Find the event that will trigger your Lob webhook (for example, a customer is Added to a List, or opened an email), then drag in the “Call Webhook” tile and place it after that event in the Journey.

11. Open up that Webhook, and toggle on ‘Use Preset Journey Webhook’, then select the webhook you have created.

12. After you have successfully set up your Journey, send a test trigger by clicking on ‘Test Journey’. Check to see whether Iterable notes any errors.

13. Assuming no errors were caught, head over to your Lob dashboard and verify the results of the test. (Reach out to your CSM if you need assistance navigating the Lob dashboard.)

Best practices

API Keys

We strongly recommend testing any planned mail sends and webhooks by first using your Test Lob API Keys, and ensuring that the resulting records created in Lob match your expectations. Only then should you proceed to use your Live Lob API Key to actually generate mail.

HTML creatives

To leverage HTML creatives in Lob, you will want to save your HTML as a template within Lob, or host your HTML and generate a corresponding hosting URL. These can be passed to Lob from Iterable, but you are not able to pass a full HTML string directly to Lob from Iterable.

Iterable Journeys

There are 3 common scenarios in which Iterable Journeys trigger Lob mail sends:

  1. Single, triggered mailpieces from individual user actions. For example, someone unsubscribes to an email list, then a message is sent to Lob to trigger a single mailpiece.

  2. A regular job is run, resulting in mail being sent to all users who meet specific criteria.

  3. An audience list is exported from Iterable and uploaded to Lob, and mail is generated for each user in the list.

These scenarios all result in different volumes of mail requests being sent to Lob in a single batch, and there are some best practices for ensuring your integration is seamless for each batch size.

For any send types that will trigger fewer than 500 mailpieces in a single batch, as is typically the case with the first scenario above, you won’t need to take any additional steps to those listed above in this doc. However, for the second and third scenarios, in which single sends will contain more than 500 mailpieces, it is recommended that you connect with your Lob representative to discuss leveraging a Lob solution to manage non-rate-limited requests from Iterable.

Additionally, for the second and third scenarios above, you can take some additional steps to ensure that all requests reach Lob within the rate limit. For example, one possible workflow enhancement for batches typically between 500-3000 mailpieces is to include audience splits in the customer journey, with delays included to stagger the sends to Lob, thus reducing rate limiting errors. For large batches, it is also an option to export the audience list from Iterable and send it via Lob’s Campaign Dashboard, as it is purpose-built to handle batch sizes into the millions, and will ensure that all expected mail is generated.

Either way, if you expect to send batches above 500 mailpieces at a time, it’s beneficial to connect with your Lob representative so that we can walk through the best solution for sending at scale while preserving the automation benefits of connecting through Iterable.

No-code integrations

Automate campaigns from the Lob dashboard

Easily set up and manage trigger-based campaigns to integrate direct mail into your customer journeys. These solutions are best-fit options for teams that don't have easy access to engineering resources to build a full API integration and would like to connect to their customer data right from the Lob dashboard.

From the Integrations dashboard, users can connect and authenticate their CRM account, then from within the Campaigns tool, manage what changes or events trigger mail and automate the dispatch of individual mailpieces using these triggers.

No-code integrations are exclusive to our users on paid plans. Upgrade your Print & Mail edition to gain access, or contact our sales team to learn more.

Available no-code integrations

  • Agile CRM*

  • Freshsales Suite*

  • HubSpot

  • Microsoft Dynamics 365*

  • Pipedrive*

  • Salesforce

  • Salesforce Marketing Cloud

  • Zoho*

  • More to come! Don't see your tech stack on the list? Please note your interest here.

Starred platforms are in closed beta. reach out to your Account Manager to enable or sign up here.

How to send Automated campaigns from the Lob dashboard

Once functionality has been enabled in your account, you will be able to execute the following.

First, connect to CRM

From the Integrations tab on the Lob dashboard, you can add or manage available connections. Detailed instructions for each available platform are linked above.

sample Integrations tab

Then, you can set up an automated campaign

Users can directly create an automated campaign from the Integration section or click the “Create Campaign” button at the top of any dashboard page to launch the campaign creation flow.

  1. When you enter the Campaigns workflow, select the Automated option. This setting means that the mailpiece you create will be automatically sent out when the designated trigger, i.e., the change in the database, occurs. (You will set up the trigger in Step 2.)

  1. In Step 1: Configure campaign, select Postcard, (8.5x11) Letter, or Self-Mailer (other mail types or inventory not available).

  1. In Step 2: Add Audience, you will set up a Campaign Trigger. A trigger is the criteria in your database that signals Lob to create mail

First, you will select the Integration Type, or CRM you have connected to, then indicate the Table where the data resides. Next, specify the Function, or what change Lob will be looking for: A new row is added, A row is updated, or Date-based triggers. You will then have the option to Add Filters from there.

Trigger details

Row/record is added

A new member signs up or creates an account, prompting first touch outreach

Row/Record is updated

Something about an existing recipient has changed, i.e., their email address fell off, their address changed, a status changed (a prospect became a customer, or a customer downgrades), so a mailer wants to reach out

Future Dates

Mailer wants to reach out to customers whose renewal is in exactly 60 days, or falls anytime within the next 60 days

Past Dates

Mailer wants to reach out to members who signed up for a trial 14 days ago and encourage sign up for a paid plan

Filters

Filter by all types of attributes: - string: cities, states, etc.

- dates: birth dates, sign up dates, etc.

- boolean: true false attributes (e.g., Legacy customer = True or False)

- numeric: number of purchases, etc.

“IS” and “IS NOT” are supported

  1. Apply Advanced Settings.

  • Delay to Print: Timing when the mailpiece gets sent to the recipient

  • Frequency: If the same household meets the trigger logic, the user can control how many times they want to send this out

  • Suppression: Do not send mailpiece if the recipient has converted (coming soon)

  1. Next, you will map the required address variables from columns in the CRM. The data for these variables must be in the same table as the trigger.

  1. Then continue your campaign setup: Step 3: Choose Creative, and Step 4: Review campaign.

Your Lob Credits balance must be $25 or more to place an order for an automated campaign.

  1. After you "Place Order" the automated campaign will remain in an "Active" state and Lob will send out the designated mailpiece when the trigger occurs (whenever a selected change in the CRM/CDP happens).

Managing Automated campaigns

An automated campaign can be managed as you would any other in the Lob dashboard: select Campaigns from the left navigation. Filtering is available and you can click into any single campaign for more detail.

Summary-level and detailed information about your campaign will be displayed on the details page.

Pause Campaign or Resume Campaign at any time by clicking the button on the Campaign detail page. When a campaign is paused, Lob will not produce mail in response to any new trigger matches. Any already triggered/queued mailpieces will still go out.

Mailpieces can be canceled individually or in bulk from the View All Mailpieces tab on the campaign's detail page.

Troubleshooting Automated campaigns

Why don’t I see mailpieces for my Automated campaign?

Lob looks for trigger matches and generates mailpieces in response at the following times:

  1. When then the campaign is first ordered

  2. A scheduled job every 30 minutes specifically looking for trigger matches

If you do not see mailpieces, it is possible that the sync job has not occurred yet to look for trigger matches.

Mailpieces that do not match your campaign’s trigger criteria will not generate any mailpiece records. The trigger logic and settings are always available on the Campaign Details page to verify setup.

If you are missing mailpieces and would like additional help, please email us at [email protected] for assistance.

My campaign is paused because of data changes in my integration instance. What do I do?

Lob performs daily checks to ensure that the tables and columns used in your Automated Campaigns are still available. If a table or column used in an Automated Campaign is modified in your integration instance, we automatically pause the campaign and notify you via email.

To resolve this issue, you can either restore the deleted table or column, or rename another table or column to match the original naming convention.

Hubspot

Overview

Hubspot is a popular marketing automation software tool. In early 2022, Hubspot added Custom Code functionality to their Workflows, enabling a direct connection to Lob. Hubspot’s Workflows can be used to automatically trigger a mailpiece to be sent, via Lob.

(Looking for a no-code integration option? .)

Video walkthrough

Step-by-step walkthrough

Create accounts

A developer plan for testing with Lob is free, but you will need to to get your API Keys.

If you do not already have one, . You’ll want to enable Operations Hub / Marketing Hub Professional trial (note this lasts 14 days): Automation > Workflows > Start 14 Day Trial

Create contacts

You can create manually, or import from a CSV by clicking Contacts > Import. From there, walk through the flow to import a file from your computer: Start an Import > File From Computer > One File > One Object > Contacts. Ensure your contacts have address parameters; you can as an example.

We will be creating a list in the next step, so for this walkthrough, do not select “Create a List from this Import”.

In the Map File screen, for ‘Address2’, select ‘Create A New Property’, and name it ‘Address2’.

Create a List

Contacts > Lists > Create List > Select ‘Static’ List > Contact-based > Name your List

Create a Workflow

Select Automation > Workflows

Click Create Workflow

Click Contact Based > Blank Workflow

Set Up Trigger

For example, List Memberships > Select List you previously created > Is Member of List

Create a resulting Action

Click + button on Workflow, beneath the Trigger

Select Custom Code

Here you can select Python or NodeJS. For this example, we will select Language: Python. Then we will map Lob’s API fields to Hubspot properties, and enter our custom code. For this example, Map Properties To Include in Code as follows:

Finally, enter your Python code, with properties defined as per the prior step. See example code below to test with.

Example Python code

If copying and pasting the Python code above, it is advised to run it through a Python code validator to ensure that no formatting issues occur as a result.

Add your API Keys

Next we need API credentials from our Lob account. Retrieve these credentials from your Lob dashboard by clicking on the Settings menu on the sidebar, then clicking on the API Keys tab.

In the example Python code, replace YOUR_API_KEY with your Test API Key.

ENSURE YOU ARE USING YOUR TEST API KEY

Update Creative

You should also replace the front and back "HUBSPOT_CREATIVE" with your own HTML, template IDs, or links to hosted static creatives. For example:

Testing

Make sure to hit ‘Save’. Then you can open your custom code back up, scroll to the bottom of the panel, and click Test Action. Select a contact, and click Test to fire off a test request.

You can then log into your Lob account to verify that a mailpiece was generated.

Utilizing workflow

Once you’ve tested, you can Publish your workflow. From there, it will run whenever the trigger you set is fired. For example, if you followed the above example, you can now add some contacts to your list. This should automatically create mailpieces for each person on the list.

Now you can replace the Test API key in your Python code with your Base64 Encoded Live API Key, and your Automation is live. If you are using other test resources like address IDs or template IDs, those will also need to be transferred to your live environment.

Salesforce

Utilize External Services to automate direct mail

Overview

Lob is pleased to offer an API integration within , the world’s #1 CRM. Integrating Lob with Salesforce streamlines your direct mail campaigns by automating personalized outreach, enhancing customer engagement, and driving measurable results directly within your CRM.

With an integration via External Services, any Salesforce user can send automated direct mail, easily and at scale. External Services in Salesforce allow you to connect your Salesforce org to an external API. Using declarative tools and OpenAPI specifications to describe the external API functionality, External Services automatically creates invocable actions within Salesforce.

(Looking for a no-code integration option? .)

Set up the integration

First things first!

  1. Download this JSON file (Lob OpenAPI specs) to use in Step 2.

Step 1: Set up a Named Credential

  1. First, create a new legacy credential for Lob.com in Salesforce.

  2. Give it a label, a name, and set the URL field to

  3. Under Authentication, set the identity type to Named Principle, and set the authentication protocol to Password Authentication. In the username field, enter your test or live For the password field, copy and paste an empty character from a website like .

  4. Under Callout Options, there are no changes needed to the default selections.

  5. Save the Named Credential.

Step 2: Create an External Service

  1. Next, go to the External Services page and create a new External Service from API specification.

  2. Fill in an External Service Name, an optional Description, then select "Complete JSON" for Service Schema, and select the Named Credential you just created.

  3. In the JSON field, paste the entirety of the Lob OpenAPI specs you downloaded.

  4. Click Save and Next. This will bring up a list of operations that you can do that were imported from those Lob OpenAPI specs.

Step 3: Use External Services in a Flow

In this step, we will set up the trigger and corresponding flow; in this example, when a lead is updated in SF, send a postcard from Lob.

Although this documentation uses a postcard flow as an example, you can still follow along for letter and self-mailer creation. (Swap in "letter" or "self-mailer" where you see "postcard" if using those form factors.)

  1. Create a new Flow Trigger explorer and set it as an Actions and Related Records type.

  2. Choose the object field and configure it for when the record is created or updated. (Ensure that Actions and Related Records is selected.)

  3. Add a Scheduled Path called "zero hour delay" and set it to 0 hours after the record is created.

  1. Next, create a new resource called "postcard_payload" with the data type as Apex defined and set it to postcard editable.

  2. Use the Assignment node to map the required fields for creating a mail piece in Lob.

  1. Map merge variables (optional)

If you plan to send creatives as, you'll need to map out merge variables. One of the limitations of this integration within Salesforce is in how merge_variables are named. You'll notice that within the <mailpiece>_payload.merge_variables field that there are parameters variable1 - variable10 listed. This is because there is no way to name merge variables dynamically within External Services for Salesforce. So to work around it, any HTML templates used with Salesforce can only have merge variables named the same way, variable1 - variable10. The values of these can then be set accordingly within the Assignment action.

  1. Back in the Flow, add an Action node to send a mailpiece creation request to Lob's API using the External Service you created earlier.

  1. Map the "postcard_payload" resource to the "body" field in the Action.

  1. Save and activate the flow. (You can debug it by selecting a test record and pressing the Debug button.)

Pro tip: Add a Fault Path for the action in case the SalesForce flow (not Lob API) fails at this step.

Retrieving data back from Lob

From the mail execution action, there was a resource created called Outputs from send_<mailpiece>. There are three subfields; this data can be used within the flow to map information back into records.

  • 200: the body of the successful request - this includes all data returned in the Lob API response, including "id," recipient information, "URL," "send_date" and so forth

  • default Exception: if the mailpiece was unsuccessful, including the error message and code

  • responseCode: the of the API request made to Lob, which is useful for making decision trees

Evaluating the response

Although you have successfully integrated and know where to retrieve output data, it's important to evaluate your responses. It's the difference between knowing whether your request to create a mailpiece was successful or not!

We can see this detail above in the image of a sample Salesforce flow, where we use the "Decision" action to evaluate if the mailpiece was sent.

  1. You can edit the Decision:

  1. Now, you have two forked paths:

  • success - your mailpiece request was successfully processed

  • Default Outcome - your mailpiece request failed (for example, because the address passed was undeliverable)

  1. Now, you can add actions to the success path to act on the data you received back from the successful send (Outputs from send_postcard -> 200), or you can add actions to the Default Outcome path and perhaps notify an admin of the reason why the mailpiece request was denied (Outputs from send_postcard -> defaultExc -> error -> message )

Congratulations! You've successfully integrated Lob.com's API with Salesforce using External Services.

Monitoring computing resources

There are a number of computing resources that need to be monitored for SalesForce activities in order to ensure uninterrupted operations, Flows included!

These computing resources include:

  1. CPU Time: There is a limit on how much CPU time can be consumed during a single transaction (e.g., 10 seconds). When your flow or other processes exceed this limit, you'll get a CPU time limit exceeded error.

  2. SOQL Queries: Salesforce imposes a limit on the number of SOQL (Salesforce Object Query Language) queries that can be executed per transaction.

  3. DML Operations: There's also a limit on the number of DML (Data Manipulation Language) operations like INSERT, UPDATE, DELETE etc. that can be performed per transaction.

  4. Heap Size: This is essentially the limit on the memory storage space used by variables, objects, etc., during a single transaction.

  5. Callouts: These are HTTP requests to external services. There are limits on the number of callouts that can be made.

  6. Elements: For flows specifically, there are limits on how many elements (like assignments, decisions, loops, etc.) you can have in a single flow.

If a flow exceeds a hard limit (), it will be terminated immediately, and an error will be thrown. This can disrupt the business process that the flow was designed to manage. To manage these limitations, Salesforce administrators and developers have to keep a close eye on resource consumption and optimize flows and other customizations accordingly. Using tools like can help you monitor your organization’s performance and stay within limits.

Need support? You can reach us at or .

Artboard layout

Note: All measurements are in inches, denoted by the double prime symbol (e.g. 4"x6").

Artboard components

Mail piece size

The sizes of our mail pieces and their respective print layout requirements can be found in each respective section of the in the Help Center. Note that the API will return an error if you input a non-HTML file with the incorrect dimensions.

Bleed area

In the above postcard, you'll notice that the file that you are sending to Lob is actually 4.25" x 6.25" instead of 4" x 6". This extra space is what we call the Bleed Area. The Bleed Area is included in postcards and self-mailers to ensure that creatives get printed all the way to the edge. This is because the creative gets printed with slightly larger dimensions than the actual card area and is subsequently trimmed down in production. Backgrounds and graphics should be extended into the Bleed Area. If they don't extend into the Bleed Area, it can result in a white or unprinted border on the edge of the postcard or self-mailer.

There is no need to include in your submitted content.

Trim zone

The Trim Zone captures the finished size of a mail piece, which will result from the printer trimming down a larger sheet of paper. Artwork that extends into the Bleed Area will be trimmed down to the size of the actual mail piece.

Safe zone

Keep all critical text and artwork within 1/8" from the edge of the final size to ensure no important content is ever trimmed off.

No-ink zones

Address block & postage

On our artboard templates, there is a space marked as *RED: INK-FREE AREA* on the backside of the mail piece. Anything in this area will not be printed, as this space is where the postage and address information will be printed during the production process.

Address blocks for 4" x 6" postcards measure 2.375" x 3.2835", and all other postcard, self-mailer, and snap pack blocks measure 2.375" x 4.0".

On letters, the address block is 3.15" x 2" and is located 0.6" from the left edge and 0.84" from the top edge. A white box will be printed, upon which will be printed the address and barcode information. Any content in this area will be covered and will not be visible.

On checks, the check itself will be printed at the 8.5" x 3.625" area at the top. This area must thus be left blank. Anything printed in this area will not be printed to leave room for check details, including address information, payment amount, signature, and bank routing numbers. All text and important information should be included within the safe zone of the check bottom or check attachment pages. Special characters, such as emojis, should not be submitted for the address block.

Carbon Neutral Mail Certification

Lob is committed to setting a new standard for direct mail and helping our customers and partners meet their sustainability goals. Lob has partnered with USPS to include a to help customers demonstrate to their end-recipients that they are sending mail in an environmentally responsible way.

The Carbon Neutral Mail certification will automatically be included within the official use address block of postcards and self-mailers. (Support of this certification may be expanded to other mail types printed by Lob in the future.) It will not impact your workflow or the way you design your creatives in any way.

For any questions on our Carbon Neutral Mail certification, reach out to your CSM or .

Placement on postcards & self-mailers

On postcards or self-mailers, the Carbon Neutral Mail certification will be placed between the return address, postage indicia, and IMb, within the .

This red area in our templates represent a white box, which will be printed on top of all submitted artwork to hold return and recipient addresses as well as the IMb information.

Be mindful of where the red address box of ink-free zone is placed on different-sized postcards and self-mailers in relation to the edge of the actual mailpiece (trim), as well as the middle fold for folded self-mailers.

Placement for 4x6" postcards only
Placement for all other postcards & self-mailers

QR codes & sequence ID numbers

On letters and checks, there is a small QR code and a set of sequence IDs that will be printed on the bottom left corner during the mail production process, which are used as part of Lob's internal quality control process. These codes get scanned by cameras on our printers to ensure that the correct pages go into each corresponding mail piece as they get inserted into envelopes. They will both appear on each page that contains content, and cannot be removed.

Plan your artwork submissions accordingly by avoiding printing any important text or artwork in the area saved for the printer QR code and sequence numbers.

Intelligent Mail barcode

The is a 65-bar US Postal Service barcode used for mail sorting and tracking. It includes the routing ZIP and tracking information. USPS requires the use of the IMb in order for Lob's mail to benefit from automated processes.

Prohibited artwork

Stamp or indicia artwork: There is a risk that the USPS will reject mail that includes artwork that resembles a stamp or fake indicia.

  • Postcards & self-mailers: Indicias are automatically printed within the (see above section). Fake indicias should not be part of your submitted artwork elsewhere.

  • Custom envelopes: There is no need to include indicia outlines in your artwork for the risk of rejection.

Artwork near the indicia: Artwork (such as eagles or American flags) is sometimes added to the left of an indicia box to add a sense of importance or urgency to a mailed piece. A 0.125" clearance on all sides from the indicia is necessary for this addition.

Example: Fake indicia on postcard
Example: Artwork too close to indicia

Address "zone" warning

We do not recommend placing any address in your creative in the bottom 2.375" of a mailpiece opposite the address panel. This will prevent the USPS from accidentally scanning the wrong side of the mailpiece.

In the following example, promotional text (in the form of an address) included on the opposite side of the postcard could be mistaken by USPS scanners for the "To:" address.

Instead, if you would like to include a promotional address in your creative, we recommend you:

  • Place it above 2.375" from the bottom OR

  • Choose light text on a dark background (to clearly distinguish from the address/postage block)

Salesforce Marketing Cloud

Overview

Salesforce Marketing Cloud, not to be confused with Salesforce.com (SFDC), is a marketing automation platform used for managing and executing personalized customer journeys across marketing channels.

Our Salesforce Marketing Cloud integration allows you to create automated direct mail campaigns from within the Lob dashboard, based on any event trigger change within your SFMC account.

No-code integrations are exclusive to our users on paid plans. Upgrade your to gain access, or contact our to learn more.

How to connect Lob with Salesforce Marketing Cloud

  1. Within the Lob Dashboard, navigate to the Integrations page and click on “Salesforce Marketing Cloud” (SFMC) to view the SFMC connection page. When on the SFMC page, click the “Connect” button to begin.

  1. You will be prompted to enter your SFMC account credentials using the client id, secret, and subdomain of the account you would like to connect with Lob.

  • Your SFMC account / organization must be on a paid SFMC plan.

  • Lob will read the data extensions, fields, and data types that are available within that profile. This may take some time depending on your SFMC instance. Feel free to navigate away from the Integrations page or Dashboard while it completes. You can check the status on the Integration Detail page in the Integration section.

How to speed this along: The best way to limit data extension access is to create the integration ("Installed Package") underneath a business unit that has a limited number of data extensions. That way Lob will only need to iterate through the shared data extensions for that business unit, rather than all data extensions.

  1. When you have successfully connected your SFMC account to Lob, the label will show “Connected”.

Once you’ve successfully connected Lob to your SFMC account, you can from within the Campaigns flow.

SFMC setup

If you have a package installed

You can find your client ID, client secret, and subdomain inside one of your installed packages:

Your subdomain is a 28-character string that begins with the letters "mc." You can find it within the REST Base URI after the https:// and before the “.auth” portion of the string. In the example above, the subdomain would be mc1111111111111111111111111111.

If you don’t have a package set up yet

Follow the steps below to create one to then get your client ID, secret, and subdomain key.

  1. First, open SFMC and click your profile icon in the top right of the screen.

  1. Click Setup under the settings dropdown

  2. Once in Setup, under Platform Tools navigation, click Apps, then Installed Packages

  3. Click New to create a new package if there isn’t one currently installed.

  4. In the New Package Details window, enter a Name and (optional) Description and click “Save”

  1. Within the package, click “Add Component” and select API Integration as the component type; click “Next”

  1. Then select Server-to-Server integration; click “Next”

  1. Within the Server-to-Server integration, select the following properties to grant Lob the ability to gain access to the appropriate data sets to send automated direct mail campaigns from:

  • Data

    • Data Extensions: Read, Write

  • Contacts

    • Audiences: Read, Write

    • List and Subscribers: Read, Write

  • Marketing Cloud Connect

    • Read, Write

  • Automations

    • Automation: Read, Write, Execute

    • Journeys: Read, Write, Execute, Activate/Stop/Pause/Resume/Send/Schedule

  • Channels

    • Web: Read, Write, Send

  • Event Notifications

    • Callbacks: Read, Write, Update

  • Webhooks

    • Read, Write

You can read more about SFMC’s permission scopes .

  1. After selecting the checkboxes to enable the component properties, click “Save”

  2. You will then see a screen confirming the package information you have just set up, which highlights your Client Id and Client Secret keys within the Components section of the page.

Additional notes:

  • SFMC data will reflect the state of the table objects and fields at the time of the sync. Each night at 12am PST, Lob will run an update to pull the latest data that is available to the user’s profile to which Lob is connected.

Integrated Technology Promotion

What is the USPS Integrated Technology promotion?

As USPS’s Mail Service Provider of the Year, Lob partners closely with the postal service to offer innovative solutions designed to enhance the impact of direct mail campaigns. USPS Integrated Technology bridges the gap between physical and digital marketing by incorporating cutting-edge tools that engage consumers in new and exciting ways.

The Integrated Technology promotion can be applied to mailpieces meeting the following parameters:

  1. First Class letters, cards, and flats, or

  2. USPS Marketing Mail letters and flats

Four key USPS Integrated Technology experiences are available through Lob:

  1. Mobile shopping: Incorporate QR codes that lead to mobile-optimized websites showcasing physical products. Note that the product you are pointing recipients to must be a physical product.

  2. Artificial intelligence: Use generative AI to craft compelling copy or visuals to meet your campaign goals.

  3. Voice assistant integration: Encourage interactions through voice prompts to guide exploration.

  4. Augmented reality (AR): Create immersive experiences that blend physical and digital with 3D images.

How can I take advantage of USPS Integrated Technology with Lob?

Mail piece requirements

To qualify for USPS discounts, your mailpiece must meet specific requirements based on the technology included.

  • Technology triggers: Incorporate features such as apps, QR codes, or barcodes

  • Directional copy: Directional copy explains the action you want the recipient to take. For example: “Scan this QR code for an exclusive shopping experience.”

    Follow these guidelines:

    • Clearly display instructions for how recipients should interact with the mailpiece.

    • Place instructions (directional copy) next to the trigger (e.g., QR code, icon) to guide engagement.

    • Make the instructions visible on every page where the trigger appears.

    • Ensure the technology used supports the main purpose of the mailpiece.

    • Specify compatible platforms or devices if the experience is limited to a specific operating system (e.g., Android only).

  • Mobile optimization: Any linked websites must offer seamless, mobile-friendly experiences, especially for purchasing physical products.

Requirements for 4 USPS Integrated Technology experiences

Mobile shopping

The mobile shopping USPS Integrated Technology experience is ideal for retail or B2C campaigns targeting physical product sales.

How to qualify:

  • QR codes should meet size requirements (minimum ½ inch by ½ inch) and include adjacent directional copy, such as, “Scan for your personal offer.”

  • Directional copy must be as big as or larger than the marketing message.

  • Must direct users to a fully optimized mobile website with an end-to-end shopping journey.

Digital shopping experience requirements:

  • Scans must lead to a fully mobile-optimized website that supports the entire shopping experience, from browsing to purchase completion.

  • Landing pages can include pop-ups, provided users can easily close them.

  • The scan must direct users to a purchase site relevant to the mailpiece's message.

  • The purchase site must sell physical products (e.g., QR codes for credit card applications are eligible if a physical card is mailed to the customer).

  • Customers must be able to complete a purchase on the site.

Artificial intelligence

To qualify as an artificial intelligence Integrated Technology experience, a mailpiece must include text or images that were created by leveraging generative AI tools, such as Adobe Firefly, ChatGPT, or Microsoft Copilot.

How to qualify:

  • AI-generated text: Include at least one sentence of text generated by an AI tool (e.g. a call-to-action or supporting sentence).

  • AI-generated images: Use at least one AI-generated image directly related to the mailpiece's message.

Pre-approval is required to participate in this promotion. Here’s an overview of the pre-approval process:

  • Submit a digital file (e.g., PDF) showing the AI prompt alongside its output in an unedited format.

  • Optionally, include a link to the prompt and output for reference.

  • Provide a short description of how the AI tool was used in creating the copy or image.

  • If edits were made to the AI-generated content, explain the changes and the reasons for them.

  • Ensure there is a clear connection between the prompt and the AI-generated output.

  • The mailpiece must match the AI output entirely unless justified edits are documented.

Mailpieces are not eligible if they use edited AI-generated output without explanation or rely on prompts that directly instruct the AI to repeat specific phrases verbatim (e.g., prompting “Repeat after me, take me to xyz.com” to produce identical copy).

Voice assistant

To qualify for the Integrated Technology voice assistant experience, your mailpiece must include instructions directing recipients to use a voice prompt for a targeted response or action via a voice assistant. This promotion is best for retail or B2C companies.

How to qualify:

Eligible approaches include:

  • Using a simple voice command to direct recipients to a website related to the mailpiece's purpose.

  • Leveraging pre-existing modules in Alexa or Google Assistant without requiring a new skill or action.

  • Customizing pre-existing modules to include branded content or scripts unique to your campaign.

  • Developing a fully custom skill or action using tools like the Alexa Skill Kit (ASK).

All voice assistant experiences must deliver measurable business outcomes.

Mailpieces that do not have a clear reason for directing users to a specific website will not qualify for Voice Assistant discounts. For example, a mailer from ABC Travel that says, "Hey Google, take me to EFGusedcars.com" for a vacation promotion to the Bahamas, or a mailer saying, "Hey Siri, take me to EFGusedcars.com" without explaining the relevance of the website, will not qualify.

Companies must submit an audio file attachment demonstrating the voice command and response when submitting the mailpiece in the MPP during the pre-approval process. Any submission that does not include an audio file cannot be approved as final until USPS receives the audio file.

Augmented reality

The USPS Augmented Reality promotion allows businesses to integrate interactive 3D elements, animations, and digital experiences into their direct mailpieces, enhancing engagement by blending the physical mail with digital content.

How to qualify:

  • Ensure your mailpiece includes animation, and 3D elements, images, or modules.

  • Create a dynamic interaction between the physical mailpiece and digital content, engaging the recipient through 3D elements and animations that respond to their perspective.

  • Examples:

    • A QR code on mailpiece that directs customers to an interactive experience:

      • “Dive into your next trip with ABC Travel! Scan this QR code to splash in the pool before you arrive.”

    • A QR code opens the app store to download a branded AR experience:

      • “Want to dive deep in the ocean? Download our ABC Travel app to explore our favorite scuba tours.”

    AR experiences that include only static, pop-up, or worded displays that do not actively engage the recipient will not qualify. Similarly, 2D AR images, which lack interactive elements or depth, are also not eligible. For a valid AR experience, the recipient must engage with the content beyond just reading or clicking a button.

Getting USPS Integrated Technology promotion approval through Lob

  • In order to participate in this promotion, you will first need to “Opt In” in the Lob Promotions Portal and accept the terms and conditions of participating in the promotion through Lob.

  • Once you have selected which Integrated Technology element your mail pieces will include, you are ready to submit your campaign for pre-approval.

  • Log into the Lob Promotions Portal and select Submit Mailpiece Pre-Approval. Complete all fields and upload your PDF samples.

  • Any final mailpieces that deviate from the prototypes, mock-ups, or examples submitted for pre-verification will be subject to the loss of the discount.

  • Pre-Approval notification from the Portal is for the technology implementation only. The mailpiece must also satisfy all of the remaining requirements in this document to qualify for the promotion discount.

  • Past acceptance/approval in prior year promotion does not guarantee acceptance/approval in current year promotions. Please review the to ensure that the mail piece meets all the 2025 Program Requirements.

USPS Integrated Technology FAQs

When is the USPS Integrated Technology promotion live?

Lob will be supporting this promotion from 6/1/2025-12/31/2025.

How can I take advantage of the USPS Integrated Technology promotion through Lob?

The easiest way to leverage this promotion is by using Lob's QR code feature to direct recipients to a mobile-optimized website. This approach not only boosts website traffic but also qualifies you for a 3% discount for including a QR code linked to a mobile-friendly site.

Is the Integrated Technology promotion a good fit for my business?

The USPS Integrated Technology promotion is a good fit for retail and B2C customers aiming to enhance customer engagement and drive traffic to their websites or digital content. It’s particularly beneficial for those focused on boosting online conversions or promoting mobile-optimized shopping experiences.

  • A QR code on mailpiece that directs customers to an interactive experience:

    • “Dive into your next trip with ABC Travel! Scan this QR code to splash in the pool before you arrive.”

    • A QR code opens the app store to download a branded AR experience:

    ode on mailpiece that directs customers to an interactive experience:

  • “Want to dive deep in the ocean? Download our ABC Travel app to explore our favorite scuba tours.”

AR experiences that include only static, pop-up, or worded displays that do not actively engage the recipient will not qualify. Similarly, 2D AR images, which lack interactive elements or depth, are also not eligible. For a valid AR experience, the recipient must engage with the content beyond just reading or clicking a button.

Getting USPS Integrated Technology promotion approval through Lob

  • In order to participate in this promotion, you will first need to “Opt In” in the Lob Promotions Portal and accept the terms and conditions of participating in the promotion through Lob.

  • Once you have selected which Integrated Technology element your mail pieces will include, you are ready to submit your campaign for pre-approval.

  • Log into the Lob Promotions Portal and select Submit Mailpiece Pre-Approval. Complete all fields and upload your PDF samples.

  • Any final mailpieces that deviate from the prototypes, mock-ups, or examples submitted for pre-verification will be subject to the loss of the discount.

  • Pre-Approval notification from the Portal is for the technology implementation only. The mailpiece must also satisfy all of the remaining requirements in this document to qualify for the promotion discount.

  • Past acceptance/approval in prior year promotion does not guarantee acceptance/approval in current year promotions. Please review the to ensure that the mail piece meets all the 2025 Program Requirements.

USPS Integrated Technology FAQs

When is the USPS Integrated Technology promotion live?

Lob will be supporting this promotion from 6/1/2025-12/31/2025.

How can I take advantage of the USPS Integrated Technology promotion through Lob?

The easiest way to leverage this promotion is by using Lob's QR code feature to direct recipients to a mobile-optimized website. This approach not only boosts website traffic but also qualifies you for a 3% discount for including a QR code linked to a mobile-friendly site.

Is the Integrated Technology promotion a good fit for my business?

The USPS Integrated Technology promotion is a good fit for retail and B2C customers aiming to enhance customer engagement and drive traffic to their websites or digital content. It’s particularly beneficial for those focused on boosting online conversions or promoting mobile-optimized shopping experiences.

USPS Integrated Technology 2025 Promotion Guidebook
USPS Integrated Technology 2025 Promotion Guidebook
Salesforce
See here
266KB
Lob Openapi.json
https://api.lob.com/
Lob API key.
https://emptycharacter.com/
HTML templates
status code
like CPU time
Salesforce Health Check
[email protected]
submit a request
An example SF flow. Note the names and order of the nodes.

Managing mail settings

As you use the Lob API to send mail programmatically, it is important that you manage your account settings to send mail so that they accurately reflect the needs of your business workflows and the frequency of your customer engagements and outreach. Most of the following settings can be adjusted via the API or in your Lob dashboard.

Mail use type

For any mail piece that is sent through Lob, you will need to indicate which mail use type is being sent. This helps Lob populate the right mail settings and postage options to ensure your mail is produced and delivered in an optimal way.

The following use type options are available for your mail pieces:

  • Marketing mail: These are mail pieces sent for promotional purposes, such as for acquisition, cross-sell, retention, or win-back campaigns.

  • Operational mail: These are mail pieces sent for transactional purposes as part of your trusted business outreach and customer communications, such as account notifications, invoices and payment, policy changes, service announcements, or other similar reasons.

See Declaring mail use type for details.

US mail strictness settings

Depending on what business logic you’d like to take based on your verification result, you can toggle your US Address Strictness Settings in your dashboard. Each level of strictness determines how much you'd like for our platform to use internal data on deliverability to restrict mail from being created and delivered to potentially invalid addresses. There are 3 possible Strictness Levels:

  • Strict: Only US addresses that Lob and the USPS deem deliverable can be successfully used as the to address for postcard, letter or check resources. Mail piece requests sent with non-deliverable addresses will return a 422 (Unprocessable Entity) error. This maps to a deliverability value of deliverable (see API documentation). If addresses have never been run through verification (i.e. were created in the past), they will also err when used as the to address.

  • Normal: Mail pieces will be created for addresses that Lob and the USPS deem deliverable, as well as addresses for which secondary information is extraneous or missing. Otherwise, you will receive a 422 (Unprocessable Entity) error. This maps to the deliverability values of deliverable, deliverable_unnecessary_unit, deliverable_incorrect_unit and deliverable_missing_unit (see API documentation). If addresses have never been run through verification (i.e. were created in the past), they will also err when used as the to address.

  • Relaxed: All mail pieces will be successfully created and mail delivery will be attempted, regardless of address validity. You will not receive a 422 (Unprocessable Entity) for Address Strictness reasons.

Ultimately, this allows you completely control the destiny of your final pieces. Only want to send to addresses that are guaranteed to be deliverable? Pick "Strict" mode. Confident that your addresses are right and want us to mail them out anyway? Use "Relaxed" mode. We want to give you the power to decide when Lob should be sending mail or when we should be rejecting based on deliverability. Ultimately, this reduces the amount of undeliverable mail you send and saves you money.

Merge variable strictness setting

Depending on how much control you'd like over your HTML integration, we offer two different account settings that affect how we treat merge variables. This account setting affects the POST /v1/postcards, POST /v1/self_mailers, POST /v1/letters, and POST /v1/checks single endpoints in both test and live mode:

  • Strict: Lob will send a 422 error if you define a merge variable in your HTML that is not passed in the merge_variables field of that request. Pass '' or null to have a particular defined variable not render.

  • Relaxed: Lob will not send an error if you define a merge variable in your HTML that is not included in the merge_variables field of that request. Instead, we will simply render nothing in the HTML in place of that merge variable.

Note that in the Campaigns feature, you have additional flexibility to set merge variable strictness settings specific to each campaign, which will override your account-level settings. If you set campaign-level settings to 'Strict', any individual mail pieces that do not have a merge variable input value will not be sent. However, it is also possible to use a substitution value to replace missing merge variable input data, which will allow your mail pieces to be sent with generic values.

Regardless of your strictness setting, if you pass merge variables keys that are not defined in your HTML, no error will be thrown. Your HTML will simply be rendered as normal without substituting the extra variable(s).

NOTE: On the 2020-02-11 and later API versions which support JSON in merge variables, merge variable strictness will still apply to the nested object keys, i.e. if a nested merge variable is undefined on the strict setting, then Lob will send an error.

Cancellation windows

By default, all new accounts have a 4-hour cancellation window for any single mail piece that is created. Within this buffer timeframe, you can cancel mailings, free of charge. This gives you the flexibility to quickly QA your mailings before they are finally sent to production.

Note that in the Campaigns feature, you have additional flexibility to establish cancellation windows specific to each campaign, which will override your account-level cancellation window settings.

Once the cancellation time window has passed for any single mail piece or for a batch of mail pieces within a campaign, the mailing is no longer cancelable and has been sent to our printers for production.

Customers on higher editions can customize their cancellation windows by mail product in their dashboard settings. Upgrade to the appropriate Print & Mail edition if interested in gaining access to this ability.

Editing your cancellation windows

Growth edition customers and above can customize their cancellation windows. If you have access to this feature, your cancellation window can be anything from 0 minutes (no cancellation window) to up to 3 days.

Keep in mind that when you edit your cancellation window settings, any changes made will only apply to mailings created after the update was made. If you find yourself constantly changing your cancellation window for different use cases, we recommend using our scheduling mailings‍ feature instead.

Canceling your mailings

Within your chosen cancellation window, any single mail piece or batch of mail pieces within the Mail Campaign feature is cancelable. This means that they will be completely removed from production and that they will not count towards your monthly usage for billing purposes.

To cancel a mailing, either use the API endpoint or cancel the mailing from the dashboard. In either case, the mailing will only be cancelable if its send_date has not yet passed.

To cancel a list of mailings, you can use a combination of our LIST and DELETE endpoints to paginate through results and attempt to delete mailings that meet the specific criteria you set.

Bypassing cancellation window with scheduled mailings

Even if you have a cancellation window set on your account, using the scheduling mailings‍ feature to schedule a mailing will override your cancellation window and the send_date passed will be used instead.

Not only is this useful for scheduling mailings far off in the future, but it is also handy for completely bypassing any cancellation window you might have and sending one mailing or batch off to production immediately.

Best practices on establishing cancellation windows

  • Upgrade to a Growth edition or above to take advantage of configurable cancellation windows. Adjust this window to a time that works for you so you have time to cancel on your end

  • Have your developer build in buffer time into your Lob integration to give your team extra buffer time to cancel before submitting a live production request to Lob

    • Protip: configure different cancellation windows per mail format / use case individually in your dashboard settings

  • If you were unable to stop a check sent through Lob, you can still prevent it from being deposited by contacting your bank and placing a stop payment on the check. This can be done by contacting and providing your bank with the check number.

  • Give yourself a longer buffer while your team becomes familiar with the Lob platform, especially when sending through the Mail Campaigns feature, as sending large-scale mail volumes may amplify the magnitude (and costs) of any errors committed. Once you've become familiar with Lob and its functionalities, gradually adjust your buffer time in order to send your mail to production sooner.

  • Cancellation windows on your account will delay the sending of any outgoing mail by the desired time window. Make sure to account for cancellation windows when considering daily production cutoff times of 10am PT.

    • For example, if you want to make the cutoff time of 10am PT and your cancellation window is 60 minutes, your cutoff time is actually 9am PT.

    • If you want to bypass your cancellation window for a certain send, you can do so by scheduling your mailings.

Idempotent requests

Idempotent Requests are requests that can be called many times without producing different outcomes. GET and DELETE requests are idempotent by definition, meaning the same backend work will occur no matter how many times the same request is issued. POST requests, however, are not idempotent. Sending a successful POST request once will result in a newly created object. If you send the same POST request 5 times, you will create 5 resources, assuming none of those requests err. If a network error occurs, there is no deterministic way to ensure the exact number of resources created.

For this reason, we have added a feature that will allow you to safely resend the same POST request to single endpoints (such as /v1/postcards, /v1/self_mailers, /v1/letters, or /v1/checks) and ensure that duplicate products are not created. To perform an idempotent POST request, you simply need to provide an additional Idempotency-Key header that uniquely identifies that resource. See our API documentation for more specific information.

Generating idempotency keys

The Idempotency Key is a feature that allows you to pass a unique key along with each request and guarantee that only one mailer is created and sent to prevent any duplicate mailings from being created. You can safely retry the same request with the same Idempotency Key and be assured that no duplicates are created even if the API is called multiple times within 24 hours.

We suggest using V4 UUID or another appropriately random string, but how you create the unique keys is up to you. For example, if you would like to associate a check with an internal unique ID of the user you are sending the check to, you may use that user id and the transaction date as an Idempotency Key (as long as you can guarantee the uniqueness of each Idempotency Key across requests to the same product). This key will expire after 24 hours, meaning if you resend the same request with the same Idempotency Key after 24 hours, a second resource will be created. Ultimately, it is up to you to make sure that you are appropriately setting the uniqueness of your keys based on your business logic. See resources below for help generating V4 UUIDs in various languages.

Sending requests on retry

In case of failure, we recommend following something akin to an exponential backoff algorithm for retrying your idempotent requests. This ensures that you aren't retrying continuously on a downed server, thereby contributing to the issue at hand.

Resources

Below are resources we recommend in various languages for generating V4 UUIDs.

  • Node: https://www.npmjs.com/package/uuid

  • Ruby: https://rubygems.org/gems/uuid/

  • Python: https://docs.python.org/3/library/uuid.html

  • PHP: http://php.net/manual/en/function.uniqid.php

  • Java: https://docs.oracle.com/javase/7/docs/api/java/util/UUID.html

import requests
import json
import base64
import os
from hubspot import HubSpot
from hubspot.crm.contacts import ApiException
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry


def retry_session(retries, session=None, backoff_factor=1):
    session = session or requests.Session()
    retry = Retry(
        total=retries,
        read=retries,
        connect=retries,
        backoff_factor=backoff_factor,
        status_forcelist=[500, 502, 503, 504, 429],
        allowed_methods=['POST']
    )
    adapter = HTTPAdapter(max_retries=retry)
    session.mount('http://', adapter)
    session.mount('https://', adapter)
    return session


def main(event):
    address = event.get('inputFields').get('address')
    address2 = event.get('inputFields').get('address2')
    city = event.get('inputFields').get('city')
    state = event.get('inputFields').get('state')
    zip_code = event.get('inputFields').get('zip_code')
    email = event.get('inputFields').get('email')
    hs_object_id = event.get('inputFields').get('hs_object_id')
    phone = event.get('inputFields').get('phone')
    firstname = event.get('inputFields').get('firstname')
    lastname = event.get('inputFields').get('lastname')

    url = "https://api.lob.com/v1/postcards"

    payload = {
        "description": "HUBSPOT DEMO POSTCARD",
        "to[name]": firstname + ' ' + lastname,
        "to[address_line1]": address,
        "to[address_line2]": address2,
        "to[address_city]": city,
        "to[address_state]": state,
        "to[address_zip]": zip_code,
        "front": "https://s3.us-west-2.amazonaws.com/public.lob.com/solutions/retail_pdfs/4x6+Retail+front.pdf",
        "back": "https://s3.us-west-2.amazonaws.com/public.lob.com/solutions/retail_pdfs/4x6+Retail+back.pdf",
        "size": "4x6",
        "metadata[customer_id]": hs_object_id,
        "metadata[campaign]": "HUBSPOT_TEST",
        "metadata[phone]": phone,
        "metadata[email]": email,
        "metadata[front_creative_name]": "demo_hubspot_front_creative",
        "metadata[back_creative_name]": "demo_hubspot_back_creative",
        "metadata[address_city]": city,
        "metadata[address_state]": state,
        "metadata[address_zip]": zip_code
    }

    session = retry_session(retries=5)
    r = session.post(url, auth=requests.auth.HTTPBasicAuth(YOUR_API_KEY, ''), data=payload)
    j = r.json()
    print(j)
"front": "https://s3.us-west-2.amazonaws.com/public.lob.com/solutions/retail_pdfs/4x6+Retail+front.pdf",
"back": "https://s3.us-west-2.amazonaws.com/public.lob.com/solutions/retail_pdfs/4x6+Retail+back.pdf",
See here
create a Lob account
create a Hubspot account here
use this CSV

The certification measures 0.349" x 0.349", and is printed in either full color or black & white, depending on the letter settings. Address block placement and measurements for applicable formats can be found below. You will be able to see the Carbon Neutral Mail logo in the proof PDF.

Address block size: 2.375" x 3.2835"

Placement within red box:

  • From right: 1.33"

  • From bottom: 1.69"

Address block size: 2.375" x 4.0"

Placement within red box:

  • From right: 1.33"

  • From bottom: 1.69"

While the red zone around the QR code is 0.5" x 0.5" large, keep a 0.58" x 0.58" sized area at the bottom left corner of the letter clear of any content as it will be covered and obscured by a white box that will be printed around the QR code.

Sequence IDs itself are 1.45" x 0.09" long, and is located 0.3" from the left edge and 2.2375" from the bottom edge of the page. Any content behind the sequence ID will be covered and obscured by a white box that will be printed to make the ID legible.

Lob will print the actual indicia in the address block area.

Leave enough space near indicia. No need to show the indicia box in artwork submissions, as Lob will print the indicia at the time of printing.

Mailpiece design specs
crop marks
sustainability
Carbon Neutral Mail certification
[email protected]
address block
Intelligent Mail barcode (IMb)
address block
Example artboard: 4"x6" postcard
Example artboard 8.5"x11" letter
Print & Mail edition
sales team
set up an Automated campaign
here

Klayvio

Overview

Klaviyo is a popular marketing automation software tool. It frequently uses integrations like Shopify to external systems like Lob. In early 2022, Klaviyo added webhook functionality, enabling a direct connection to Lob (prior to this, data had to be extracted from Klaviyo and passed to Lob via a separate system). Klaviyo’s webhooks can be used to automatically trigger a mailpiece to be sent, via Lob, within a user Flow.

Getting started

Getting your data ready

Klaviyo’s webhook functionality within their flows interface provides an easy connection point to trigger automated, personalized Direct Mail.

We’ll assume you have a Klaviyo account and you have already registered with Lob (for your API Keys and the like) to follow along.

In order to send mail from Klaviyo, Lob requires a mailing address to be stored for each profile. Klaviyo does not require mailing addresses by default, so before attempting to send mail, ensure that your recipient profiles contain properties for:

  • Address

  • City

  • State

  • Zip Code

If you are importing new profiles to Klaviyo, simply ensure that you have CSV columns for each of those properties. An example CSV to import Profiles is linked here.

Creating a Flow

In the Klaviyo dashboard’s left-hand panel, click on Flows. Then click to Create Flow, then select a predefined goal, or click Create From Scratch and give your flow a name. Then choose a Trigger Setup option in the left panel.

For this example, we will be selecting List, and choosing a list from the resulting drop-down to trigger the flow.

Creating a Webhook

Once you have configured your trigger, an actions menu will appear on the left panel. Select Webhook, and drag it into your flow beneath the trigger.

Select the Webhook in your Flow, and the configuration panel will appear on the left side. You can configure it as follows:

Destination URL

This is where you will enter the Lob API URL for the mail format you would like to trigger.

Example: https://api.lob.com/v1/postcards. Note that Lob has separate endpoints for various mail formats.

Headers

This is where you will enter the headers Lob requires in order to correctly process and authenticate the incoming requests.

You will be required to enter at least two headers: Content-Type and Authorization. Click Add Header.

For the Content-Type header, enter the following:

  • Key: Content-Type

  • Value: application/json

For the Authorization header, you will need your API keys.

Add Your API Keys

For the Authorization header, you will need to have your Base64-encoded Lob API key ready to enter, so Lob can associate the request with your account. You can find your API key in your Lob account settings, and you can use a Base64 Encoder tool to encode it.

Ensure you are using your Test API key, not Live API key.

For example, if your API key was test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc, you would enter test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: into a Base64 Encoder tool, the result of which would be something like dGVzdF8wZGM4ZDUxZTBhY2ZmY2IxODgwZTBmMTljNzliMmY1YjBjYzo=.

Note that we added a colon (:) to the end of the API key before encoding it, you are recommended to do the same.

Once you’ve encoded your API key, add the Authorization Header and use the encoded key as the value. For example:

  • Key: Authorization

  • Value: Basic dGVzdF8wZGM4ZDUxZTBhY2ZmY2IxODgwZTBmMTljNzliMmY1YjBjYzo=

JSON body

This is where you will pass Lob the information that informs the mailpiece. The field names (name, address_line1, etc) represent the information that Lob’s API will require. The values on the right represent what you will pass to Lob to populate the given field.

The values can be mapped to attributes from Klaviyo profiles by using Klaviyo’s Profile Variables. You can find the Profile variables for each attribute by taking the following steps:

An example of a populated JSON body could look something like the following. You can find more information on each of these fields in our API documentation.

Note that if you are copying the below example, you will want to replace the values being passed for ‘front’ and ‘back’ with your own Lob template IDs or linked creative.

{
    "description":"Demo Postcard job",
    "to":{
        "name":"{{ person.first_name|default:'' }} {{ person.last_name|default:'' }}",
        "address_line1":"{{ person|lookup:'$address1'|default:'' }}",
        "address_line2":"{{ person|lookup:'$address2'|default:'' }}",
        "address_city":"{{ person|lookup:'$city'|default:'' }}",
        "address_state":"{{ person|lookup:'$region'|default:'' }}",
        "address_zip":"{{ person|lookup:'$zip'|default:'' }}"
    },
    "from":"adr_51c8197241ae440c",
    "front":"tmpl_7597eab53f11931",
    "back":"tmpl_2d83381e5658852",
    "size": "6x9",
    "mail_type": "usps_first_class",
    "metadata":{
        "source": "Klaviyo"
    }
}

Update Creative

You will want to replace the values being passed for ‘front’ and ‘back’ with your own Lob template IDs or linked creative. For example:

"front": “https://s3.us-west-2.amazonaws.com/public.lob.com/lobcom/template_gallery/gtmpl_524eb6ff6c6998_Increase_Customer_Loyalty_Postcard_4x6_front.html"

"back": "https://s3.us-west-2.amazonaws.com/public.lob.com/lobcom/template_gallery/gtmpl_524eb6ff6c6998_Increase_Customer_Loyalty_Postcard_4x6_back.html"

For more about designing/formatting creative for Lob, go here.

Testing

You can test that your webhook is configured correctly by clicking on ‘Preview Webhook’.

The resulting panel will show an example of the data being passed to Lob for a specific Profile. You can look at the JSON to verify that the Klaviyo Profile Variables are being correctly replaced. For example, instead of {{ person|lookup:'$address1'|default:'' }} you will see an address, such as ‘185 Berry St.’

If this all looks correct, double-check that you used your Test API Key (rather than your Live API Key), then click on Send Test Request. If it was configured correctly, you will see the message: "Successfully sent webhook."

You can then log into your Lob account to verify that your postcard was generated. (The below is the result of the example creative.)

Go time!

You will need to add payment information to your Lob account should you actually wish to print and send mailpieces. When you are ready, you can replace your Test API key with your Live API key. If you are using other test resources like address IDs or template IDs, those will also need to be transferred to your live environment.

Note: the "testing" functionality in Klayvio is sending a one-off request to Lob, this means if you have your LIVE API key in the template, it will create mail and if you have your TEST key it will not.

Make sure when you are testing that your cancellation windows are set to an ample time (2 hours is recommended) to make sure you can always cancel mail if you make a mistake.

Common errors

  1. 401 Unauthorized

    • If you receive this error message, your API key is incorrect.

    • Make sure you have the header Authorization and that you are encoding your secret API key as explained above

  2. 422 Unprocessable Entity (Invalid request payload JSON format)

    • If you receive this error, it is likely that your payload is not formatted correctly. It needs to match JSON formatting.

    • Generally speaking, the rules that are often broken are:

      1. All keys and values are enclosed in double quotes (").

      2. Commas after every key-value pair except for the last one.

      3. No newline characters in any values and no extra spaces between fields.

  3. 422 Unprocessable Entity (Other)

    • Other than JSON errors, you can receive 422 errors in the payload sent to Lob does not match our requirements.

    • For example, if you are missing address_line1 in the payload you will get an error saying that is needed. For these errors, you can make the appropriate adjustments and retry your requests.

International mail

This page is regarding mail that originates in the US and is mailed abroad by the USPS. If you have further questions about sending mail internationally, contact us.

General considerations

Mail formats

  • Postcards and letters created using the individual mail creation endpoints can be sent internationally, Campaigns UI (non-custom formats) and Campaigns API (non-custom formats); see below for format-specific considerations

  • No checks can be sent (or cashed) abroad

Mailing class

  • Only USPS First Class Mail is available for international delivery

  • Expect international mail to take an additional 5-7 business days

  • Registered Mail is not supported internationally

  • Certified Mail is not supported internationally

  • Standard class (Bulk/Marketing Mail), Nonprofit stamps, or First Class Presort are not permitted in international mail and will be returned to sender

Destination address

  • Lob follows USPS standards for sending international mail

  • International address data is available in over 240 countries, and the complete list of countries and territories can be found in our global address coverage page

  • To pass country codes in the API, use the specific two-letter convention identified by the ISO 3166-1 alpha-2 convention (e.g., ‘US’ for United States of America, or ‘CA’ for Canada)

  • Lob follows USPS’s guidance on international service disruptions that affect First Class Mail delivery abroad

    • Our Print & Mail API will be periodically updated to exclude country-specific mail delivery suspensions. If you attempt to send mail to a suspended destination, you will receive a 422 error.

    • We will lift service restrictions in accordance with any USPS-provided guidance.

    • Temporary service disruptions (due to conditions like wildfires or COVID-19 for example) are subject to change.

Non-Latin/non-standard character support

For the address box:

  • Name and company will remain as-is within their respective character sets

  • If our Address Verification can validate and translate the address portion, it will return the address in English

  • All international mail will not receive CASS processing beyond US borders by default, so be sure to have accurate addresses if sending with your respective character set

For the content of the HTML body:

  • Must be using a typeface (font) that supports the character set

  • Must include meta element with utf-8 charset: <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

  • Example:

<html>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<body>
<b>Chinese characters in UTF-8</b><br/>
Simplified characters: 简体中文网页<br/>
Traditional characters: 繁體中文網頁<br/>
Korean characters: 빠른 갈색 여우가 게으른 개를 뛰어 넘다<br/>
Arabic characters: الثعلب البني السريع يقفز فوق الكلب <br/>
Vietnamese characters: Ăă
</body>
</html>

Return address

  • US-based return addresses are required on all outbound international mail, regardless of the mail service used

  • All outbound mail pieces (“to” address is international) must bear a complete return address in the country of origin (e.g. where you pay postage)

  • Since Lob mail is originated in the US, the return must have a US-based address

Mail tracking

  • For international mailings originated in the US, tracking events will not appear and tracking data cannot be accessed via the USPS’s website beyond the final scan in the US, "International Exit"

    • Note: USPS does not appear to scan the majority of their international mail, which means this "International Exit" event is unreliable and thus infrequently surfaced

  • On rare occasion, international mailings may receive an "In Transit" or "Process for Delivery" scan, indicating that the mail piece has been processed at the entry/origin facility outside of the US

    • However, because delivery occurs in a foreign country outside the control of the USPS, international mailings do not receive scans beyond that, and cannot be tracked through the mailstream

  • In short, Lob is unable to provide reliable scans for international mail, especially beyond US borders

Format-specific considerations

Postcards

  • Per USPS, only 4x6" size postcards can be sent internationally via First Class Mail

Letters

  • File limit is 6 sheets single-sided or 12 pages double-sided (totaling 6 sheets)

    • PDFs that surpass the file limit will error

    • HTML that renders more pages than the file limit will be trimmed

  • While Registered Mail International service items also cannot be tracked, it does provide delivery status or attempted delivery information which can be obtained through USPS in three ways:

    • Go to www.usps.com. Select "USPS Tracking." By entering the tracking number shown on the mailing receipt into the lookup field, you can view the delivery status of the article

    • By calling the USPS Tracking telephone number found at Contact USPS

    • By bulk electronic file transfer for mailers who provide an electronic manifest to the United States Postal Service

Checks

  • Checks cannot be sent internationally, and the API will return an error if address_country is not the US.

Campaigns UI specific considerations

  • Start your campaign and choose "Includes International" on the first step. This tells the system you want to follow international mailing rules.

  • The Campaigns UI will then guide you through the USPS requirements. This ensures your maipiece is properly formatted and is set up for successful delivery.

Booklets

Overview

Booklets are a unique way to promote your products, services, or brand to potential and existing customers. Smaller than a typical magazine, our digest booklets are a snackable, tangible tool for storytelling.

Check out the following resources to get started with booklets:

  • Lob dashboard: Booklets section or Campaigns

  • API documentation

  • Template Gallery for sample design inspiration and template

Booklets are exclusive to Enterprise edition customers. Upgrade your Print & Mail edition to gain access to this mail format, or reach out to our sales team to learn more.

Booklet formats

9x6” booklet

  • Like all other mail formats at Lob, this is digitally printed, which allows for dynamic personalization.

  • Available in 8, 12, or 16 pages.

  • There is a minimum order size of 5,000.

  • Booklets have a 4-day production SLA

8.375x5.375” booklet [offset]

  • Utilizes offset printing, a more traditional method of production for direct mail. Offset does not allow for dynamic personalization, but can allow for a higher page count at a lower cost than its digital counterpart.

  • There is a minimum order size of 10,000.

  • Booklets have a 4-day production SLA

Dimensions & specs

Layout dimensions

Booklet sheets are folded horizontally resulting in side-by-side panels to be read left to right, like a book.

Artwork should be submitted (and will preview) as a printer’s spread. Each of our layout templates include page numbers to guide you.

What is a "printer's spread"?

This layout is not in consecutive page order. Instead, pages are paired so that only after the booklet is printed, assembled, and folded, all the pages appear in the correct numerical order for the reader.

  • From the front cover (page 1), follow a zigzag pattern to the left page of the next spread (page 2)

  • Keep this zigzag numbering pattern until you get to the bottom. Then go directly across from left to right

  • Return back up the page in a similar zigzag "ladder" until you get back to the top with your last page

Please refer to our layout templates for where to place your design elements; pay close attention to address/postage block and safe zones.

9x6" layout templates

  • 9x6” 8 PAGE

  • 9x6” 12 PAGE

  • 9x6” 16 PAGE

8.375x5.375" layout templates

The 8.375x5.375 booklet is produced on an offset printer & mailpieces cannot be personalized.

This booklet size is available in 8, 12, 16, 20, 24, 28, or 32 pages.

  • 8.375x5.375” 8 PAGE

  • 8.375x5.375” 12 PAGE

  • 8.375x5.375” 16 PAGE

  • 8.375x5.375” 20 PAGE

  • 8.375x5.375” 24 PAGE

  • 8.375x5.375” 28 PAGE

  • 8.375x5.375” 32 PAGE

Artwork considerations

  • Booklet sheets are printed double-sided in black and white or color.

  • Note zone around binding is 0.125” from either side of the midline/fold (.25” total). Artwork may be placed here, but note it will be impacted by the fold.

  • Minimum booklet size: 8 pages (2 sheets of paper, with 2 panels printed on the front and back of each).

    • Page count must increase by 4 pages (1 sheet of paper) at a time.

  • Maximum booklet size:

    • 9x6”: 16 pages (4 sheets of paper)

    • 8.375x5.375” [OFFSET]: 32 Pages (8 sheets of paper)

Ink-free zone dimensions

9x6” digest booklet

  • W x H: 4 x 2.375"

  • 0.15" from the center fold line

  • 0.125" from the top edge (including bleed)

  • Placement: Left panel outside back

8.375x5.375” booklet [offset]

  • W x H: 4 x 2.375"

  • 0.15" from the center fold line

  • 0.125" from the top edge (including bleed)

  • Placement: Left panel outside back

Paper specs

We use a few pre-approved papers across our commercial printer network. In ensuring uniform quality and consistency across all of our mail pieces, each paper source specification must fall within a small range.

9x6” digest booklet

  • Basis Weight: 80# Text

  • Full Bleed

8.375x5.375” booklet [offset]

  • Basis Weight: 60# Gloss Text

  • Full Bleed

Binding & Closure

For artwork, regardless of booklet size, note zone around the binding: 0.15” from either side of the midline/fold (.3” total). Artwork may be placed here, but it will be impacted by the fold.

All booklets, regardless of page count, will be saddle-stitched with two staples.

  • In saddle stitching, folded sheets of paper are nested in one another, then stacks are draped over a holding device (the paper hangs over each side like legs on a saddle). Then, long wire staples are threaded, or “stitched” through the paper; two staples is the standard.

All booklets, regardless of page count, will have a three-tab closure (wafer seals) for postal regulations.

  • Wafer seals are self-adhesive paper disks used to prepare self-mailing materials for delivery or to seal envelopes securely without glue.

Booklet best practices

Ensure your booklets get to their final destination by following these guidelines:

  • The "from" field is required for all booklets, regardless of the destination

  • Booklets should not contain any PII outside of the no-ink zone

  • HIPAA-compliant booklets are not offered at this time, as booklets are not placed in envelopes

  • Avoid any prohibited artwork to ensure your mail does not get rejected by USPS

  • Mailing Class options may differ based on destination and use type (e.g. promotional vs non-promotional)

Coming soon: Up next on our roadmap is a 9x6" digitally printed booklet offering full personalization via merge variables. Talk to your Account Manager for more information.

Informed Delivery

As USPS’ Mail Service Provider of the year, Lob works in lockstep with the postal service to bring you solutions to optimize your direct mail performance.

What is Informed Delivery?

Informed Delivery by USPS enhances the mail experience by providing subscribers a daily email with a digital preview of incoming mail.

The preview may be a representative image or an actual scan of the mailpiece. The email includes a "ride-along" image: a small, full-color, interactive image that redirects to a target URL. This supplemental content is meant to enhance the customer call-to-action and reinforce the messaging and objective of the mailpiece.

Image source:

You can review the USPS's 2024 Informed Delivery Guidebook here.

Access to this feature is exclusive to Enterprise plan customers, and by request only. Upgrade to the appropriate Print & Mail Edition to gain access.

Why should mailers use Informed Delivery?

Direct mail helps your brand increase awareness, connect with potential customers, and drive conversions. However, combining this marketing method with digital technologies can lead to even more successful results. Using Informed Delivery is one of the best ways to do this.

While there is no guarantee everyone in your audience has opted into the Informed Delivery program, the list continues to grow. Per USPS, as of March of this year, the Informed Delivery user base has grown to 62.4M active users!

  • Increased Customer Engagement: Integrates physical mail with digital campaigns.

  • Additional Digital Footprint: Extends marketing reach at no additional cost.

  • Attribution Data: Provides additional insights into mail campaign performance.

Cost Savings: 3-4% postage discount for approved campaigns during the USPS promotional period, August 1-December 31, 2024. Reach out to your Account Manager to learn more.

Step 1: Sign up for Informed Delivery Promotion

This process is necessary regardless of how a user will execute the campaign.

  1. Log into the Lob Dashboard; navigate to Billing > Promotions. Click on "Create an Informed Delivery Promotion."

  1. Indicate the Promotion Name

  2. Input the Promotion URL

  3. Upload your Ride-along image

    Ride-along image specifications: Must be full color, JPG, 200x300px, max file size of 200KB.

  1. Click "Create an Informed Delivery Promotion" to send your promotion application to USPS for approval.

  2. You will receive an email notification once your promotion is approved. (Please allow for 3-5 days approval time.)

Step 2: Send an Informed Delivery campaign

Once approved, you can send an Informed Delivery campaign with postcards, letters, self-mailers, and checks.

Send via API

  1. Use the Lob API to POST informed_delivery_campaign and get a campaign_id.

  • Include required fields: Ride-Along Image, URL, Campaign Size.

    Ride-along image specifications: Must be full color, JPG, 200x300px, max file size of 200KB.

  • Optionally, include

    • Brand Name: If you do not pass a brand name, it will auto-populate in the Informed Delivery email as the Company name in Lob's system.

    • Representative image: A sample image of your mailpiece. This photo should represent all mailers in the Informed Delivery Campaign, and will be sent to all Informed Delivery subscribers; avoid using any PII. Campaigns with no representative image will display a USPS scan of the mailpiece.

      Representative image specifications: JPG, 500x780px, max file size of 200KB.

  1. On successful POST, receive a campaign_id and validation if it qualifies for an existing promotion.

  2. Once validated, send your mail as usual, including the usps_campaign_id in your submission.

Send via Campaigns

  1. Begin your campaign setup as usual in Lob Campaigns.

  2. When prompted, select the option to use Informed Delivery.

  3. Choose from available approved Informed Delivery Promotions (Procured in Step 1).

  4. Fill out required information:

  • Promotional URL

  • Upload the Ride-Along Image

    Ride-along image specifications: JPG, 500x780px, max file size of 200KB.

  1. Optionally, input:

  • Brand Name: This populates in the Informed Delivery email sent to the end user; if you do not update this field, it will default to your company name in the Lob database.

  • Representative image: Upload a sample image of your mailpiece. This photo should represent all mailers in the Informed Delivery campaign, and will be sent to all Informed Delivery subscribers; avoid using any PII. Campaigns with no representative image will display a USPS scan of the mailpiece.

Representative image specifications: JPG, 500x780px, max file size of 200KB.

  1. Please look over the uploaded images and make sure all information is correct.

  1. Click "Next Step" to proceed with the Campaigns worklflow.

  2. Click "Place Order" as you normally would to finalize the campaign.

Informed Delivery engagement metrics

Engagement metrics for Informed Delivery campaigns will be visible in the Mail Analytics in the dashboard, under the Engagement tab. Learn more about Mail Analytics here. Below is a breakdown of the engagement metrics:

Metric

Description

Mail Pieces

Total number of mail pieces sent as part of your Informed Delivery Campaign.

Emails

The number of recipients signed up for Informed Delivery who received an Informed Delivery email.

Emails Opened

The number of emails that were opened. Note: This number can exceed 100% as multiple people within the same household may receive and open their Informed Delivery email.

Click Through

The total number of times the link in your Informed Delivery campaign was clicked.

Informed Delivery FAQs

What makes a great ride-along image?

Note your image must be in full-color; the USPS has provided more helpful guidelines here: https://www.usps.com/business/pdf/informed-delivery-campaign-elements-guide.pdf

How can I take advantage of the Informed Delivery promotion period August 1- December 31, 2024?

Reach out to your Account Manager today!

Can I use Informed Delivery for an Automated Campaign?

Not yet; this is on our roadmap.

How long can an Informed Delivery campaign run for?

45 days.

Customer.io

Incorporating Intelligent Mail into Customer.io Workflows

Overview

is a popular messaging automation platform that empowers its customers to create personalized message flows to engage their audience. Traditionally these have been channels like email and SMS. However, with Lob, you can bring Intelligent Mail into your omnichannel customer journey and manage it just as easily as your digital channels.

Getting Started

  1. Log into your . To start you’ll need your . It is highly recommended that you use your (secret) test API key first for testing.

  2. Have a (HTML template) ready to use.

  3. Sign in to your

Create a Campaign in Customer.io

We will be bringing Lob into Customer.io within the Workflow step of a Campaign. In order to set up a Workflow, you will need to first create the Campaign within Customer.io and configure your Trigger, Settings, and Goal & Exit steps. Complete instructions on this can be found in

Setting up your Workflow

  1. Once you reach the workflow screen, you can begin crafting your customer journey by creating the event path your users will follow. Below is a standard example of an event trigger (User Purchase) followed by a standard Welcome Email.

  1. We can incorporate Intelligent Mail into this Workflow in a similar manner to email by adding a Webhook node. We can do this by dragging in a Send And Receive Data tile from the left-side menu.

Configuring Your Webhook

  1. Now you will have an empty webhook, which you can configure by clicking to open it. This will open an edit screen in the left panel. You can find

  1. You can configure it as follows:

  • Webhook Name: The Description of your Mail Event

  • Add Request: This is where we will add the Lob Endpoint URL and the JSON code that will format the information being passed from Customer.io to Lob. More details on this below in

  • Sending Behavior: Send automatically

Configuring Your Webhook Request

  1. Click on Add Request to begin the setup process.

  1. Next to POST, you will construct the Lob endpoint URL for the type of resource you are trying to create.

  • The format is as follows: https://+[YOUR LOB API KEY][email protected]/v1/[RESOURCE TYPE]

  • Your API key will be either your Test or Live , which you can find in your Lob dashboard under Settings. It is strongly recommended that you begin with your Test API Key to ensure it is working, before switching to your Live API Key.

  • The Resource Type will depend on the mail format you are trying to send. For example, postcards, letters, or self_mailers. You can find all of the available resource types in .

  1. In the black box, you will construct your JSON to pass the required information to Lob’s API to generate a mailpiece. For example, see

  2. You will pass in the Customer attributes to populate this by using .

This will enable to you not only pass in the recipient’s name and address, but also personalize your mailpiece by using Liquid to populate dynamic merge variables. (.)

Sample JSON

Below is sample JSON you can test within your Customer.io webhook.

Before testing this, replace the front and back with template IDs from your own Lob account.

Testing

Once your webhook has been configured, you will want to test it.

Remember that you should be using your Test API Key for this, as you will otherwise generate live mail.

  1. You can send a test by opening up the Request and clicking on Send Test in the top right corner.

  1. Once you confirm and send, you will want to see a 200 OK response in your Test Results. This will indicate that the request has successfully reached Lob.

  1. You can also check the Test Results to ensure the request fields were correctly populated by the Liquid Statements.

  2. You can then log into your Lob account to verify that the mailipiece was successfully generated. Preview it to make sure all of the details are correct. If so, then you have successfully set up your Customer.io to Lob integration, and are ready to send Live Intelligent Mail.

Ingesting Mail Tracking Events from Lob into Customer.io

You can set up Webhooks within Lob to pass mail events (for example, Postcard Delivered) from Lob into Customer.io by using .

  1. Start by creating a new Campaign within Customer.io and select: Create Your Own Trigger From A Webhook as the trigger.

  1. This will generate a URL to catch the webhook. Copy that to use within Lob in the next step.

  1. Navigate to to set up the webhook event you want to capture.

  2. Under Create A New Webhook, enter a webhook description and paste in the URL generated by Customer.io.

  3. Finally, select the event you want to capture in Customer.io.

  1. From here you can use the data on the incoming webhook to track as events or update attributes for users within Customer.io. This also enables you to trigger subsequent events—for example, you can imagine an omnichannel customer journey in which a customer receives a Lob postcard, and that automatically triggers an email to that same customer telling them to check their mailbox for a great offer.

Once you have incorporated both sending Lob mail and capturing Lob events within Customer.io, you will have truly automated direct mail, and integrated within your broader digital customer journeys.

{
    "description": "Customer.IO to Lob Postcard Creation",
    "to": {
        "name": "{{ customer.name}}",
        "address_line1": "{{ customer.address_line1 }}",
        "address_line2": " ",
        "address_city": "{{ customer.address_city }}",
        "address_state": "{{ customer.address_state }}",
        "address_zip": "{{ customer.address_zip }}",
        "address_country": "US"
    },
    "from": {
        "name": "Lob Solutions",
        "address_line1": "210 King St",
        "address_line2": "3rd Floor",
        "address_city": "San Francisco",
        "address_state": "CA",
        "address_zip": "94107",
        "address_country": "US"
    },
    "front": "tmpl_xxxxxxxxxxxx",
    "back": "tmpl_xxxxxxxxxxxx",
    "size": "6x9",
    "merge_variables": {
        "name": "{{ customer.first_name }}"
    },
    "metadata": {
        "source": "Customer.IO"
    }
}
Customer.io
Lob account
API keys
creative file
Customer.io account.
Customer.io’s documentation here.
Customer.io documentation on webhook setup here.
Configuring Your Webhook Request.
API key
Lob’s API documentation
Postcard > Create in Lob’s API documentation.
Liquid Statements
More information on creating personalized HTML templates
See here for more info on using Webhooks with Lob.
Customer.io’s Webhook Triggered Campaigns
Webhooks within the Lob dashboard
example
Screen_Shot_2021-03-12_at_12.15.18_PM.png
2024 Informed Delivery Guidebook

Make

Make, previously known as Integromat

Overview

Make (formerly known as Integromat) is a free online automation tool that connects apps and automates manual workflows by using an easy to use, no-code, visual builder. With Make, you can quickly connect your favorite apps, services, and devices with each other to automate your custom workflows and save time - without needing to know how to code or hire a developer.

  • Create Scenarios (no-code workflows) that connect Lob with hundreds of popular apps & services

  • Allows you to create your own custom app through the Developer Platform

  • Supports functions in the same manner as Excel

  • Choose whether to retrieve data from the past or dynamically after activation to inform your Scenarios

  • Best fit for teams that are sending small - medium sized mail campaigns (<1,500 per run)

  • Sign up for a free Make account to create custom workflows or use prebuilt Scenarios

Integration directions

Make's platform allows users to build Scenarios by connecting Modules. By linking together multiples Modules of your favorite apps/services, you can easily create a Scenario that will automate data transfers between apps and subsequent workflows.

Integration occurs in three easy steps:

  1. Sign up for Lob and Make

  2. Connect Lob to Make

  3. Create custom workflows, or use prebuilt ones

Sign up for Make

  1. Navigate to Make's website at https://www.make.com/en/

  2. Create an account by clicking on the Sign Up button on the top right of the screen

  3. Start with a free developer’s account, or sign up for a subscription level that suits your needs

Connecting Lob to Make

  1. Log in to your Lob and Make accounts

  2. In the Make dashboard, click on "+ Create a new Scenario" button at the top right corner of the home screen

  3. Search for "Lob" in the app directory and hit "Continue"

  4. In the visual Scenario builder, click on the Lob icon and select the action you’d like to take from the drop down menu

    • Example actions: Send a letter or postcard, verify an address, make an API call

  5. In the dropdown, click on “Add” to name your connection, add your Lob API keys, and click “Continue”

    • Use your Test Lob API Key initially to ensure that everything is working as expected, then switch to your Live API Key later to send live mail

  6. Once the connection is completed, finish building your Scenario or browse pre-built Scenarios to leverage

  7. Once you've tested your first Scenario, switch the API key to the Live key and begin sending physical mail!

Use pre-built Lob modules

Here are six popular Modules (functionality clusters) to automate your Lob Print & Mail and Address Verification workflows:

  • Create a Letter: Takes your API key, to/from address data, creative data (HTML or PDF), and Mail Class

  • Create a Postcard: Takes your API key, to/from address data, creative data (HTML or PDF), and Mail Class

  • Create a Self-mailer: Takes your API key, to/from address data, creative data (HTML or PDF), and Mail Class

  • Verify a US Address: Takes your API key and address data

  • Verify an International Address: Takes your API key and address data

  • Send a Generic API Request to Lob: Takes your API request payload

Connecting Lob with other services

If you are using online apps like Google Drive or other app/services to store your customer data and would like to import them into Lob to automate your mail sends, Make can connect your online apps to Lob.

For example, to connect Google Drive to Make:

  1. Create a Make account

  2. Using the Google Developers Console, create a new project.

  3. Create credentials for the new project, adding Make to the project’s Scope and allowing external users

  4. Create the application

  5. Retrieve Client ID and Secret

  6. Use ID and Secret to establish Make connection

You can find more information about connecting Make to Google Services in this Make tutorial.

Creating Scenarios

Building Scenarios

Watch how you can easily connect addresses stored in Google Sheets to Lob with Make to send a simple postcard in three steps:

For more information on how to build custom Scenarios or create Connections, visit Make's Help Center.

Using pre-built Lob Scenarios is typically an easier place to start than building one from scratch:‍

  • Send postcards from Google Sheets

  • ‍Send postcards from Airtable

  • Clean up Invalid Addresses

Sharing Scenarios

Blueprints are detailed plans for how a Scenario (low-code workflow) is set up and how it will work. This allows other stakeholders to understand the composition of your automation in detail, share it with other teammates, and troubleshoot when necessary.

Export a Make blueprint

  1. From your scenario builder screen in Make, navigate and click on the “More” button (see below box with an ellipsis). Click “Export Blueprint.”

  2. The ‘blueprint.json’ file will then be downloaded to your device’s folder.

Download/Import a Make blueprint

  1. In the scenario builder screen, click on the “More” button (same box as above). Click “Import Blueprint.”

  2. When the Import Blueprint menu is launched, click on “Choose Files” and select blueprint.json from your files. →

  3. Once the file has been submitted to your Import Blueprint builder click on the “Save” button.

  4. Once complete, you will receive a confirmation banner along the bottom right side of your scenario builder screen.

Troubleshooting

I don't see how to input the merge fields for my template

To integrate merge variables on Integromat, you need to paste the full HTML string directly into the text box, then use the built-in merge functionality from Integromat to insert variable content.

This is an example of how that might look:

Note: PDFs do not support merge variables. HTML in Integromat is limited to 10,000 characters.

How do I connect a Google Sheets account to Make?

If you are using Google Sheets or any other app/service to store your customer data and would like to import them into Lob to automate your mail sends, Make (fka Integromat) can help connect your online apps to Lob with zero coding.

In order to use Make, connect Google Sheets (or any other app that holds your data) to Make, then connect Lob to Make using the instructions above. Here are instructions for connecting Google Sheets:

  1. Sign up for a Make account. On Make’s dashboard landing page, click on the “+Create a new scenario” button on the top right-hand corner of the screen.

  2. Search for the app/service you’d like to connect that stores your customer data, “Google Sheets” and select the resulting icon at the bottom of the page

  3. Click on the continue button on the top right side of the page.

  4. When you enter your scenario builder screen, you will see a blank module. Click on the module and select the “Google Sheets” option.

  5. In the Connection menu that follows, click on the “Add” button. In the new window, enter a name for the connection (eg. a personal Google Sheets). Once you have your name, select the “Continue” button.

  6. Make should now integrated with Google Sheets. You can continue to build out your module by completing the scenario with your new Sheets connection.

  7. You will then be prompted to select your Google account to grant access to Make.

You can find more general information about creating Connections in Make here. If you want to create a connection with Lob and Integromat, see here.

Support information

Feel free to contact Make’s support team via their support form for issues on the Make side, or email [email protected] for Lob-specific debugging!

Campaign audience guide

Overview

The foundation of any effective marketing campaign strategy is to have a specific and defined audience of contacts. Creating a targeted audience list by utilizing important customer data, such as past purchase history, product engagement or site interaction, or loyalty or subscription data, can be an effective way to test your marketing performance.

As you export your campaign audience list to bring it into Lob, keep the following guidelines in mind when using the feature, either in the or the .

Step 1: Build your audience file

File formatting

All CSVs, or comma-separated values, are required to contain recipient address data. If you are using HTML templates with merge variables for your creative, your CSV must also include merge variable data.

Files must have a .csv filename extension and must not exceed 5GB. Also note, though this is typically already the default, UTF-8 encoding is required for CSV files.

Formatting field & record values

CSV output will always start with the first row returning the column field names. Then the data itself will follow as CSV records.

Whitespace characters (spaces, pilcrows, and carriage returns) will be trimmed at the start and end of each value to ensure we can process the CSV. For example, " John Doe " will be trimmed to "John Doe". Any whitespace characters inside the value will not be trimmed.

You are not required to name your columns to Lob's naming convention, as you can easily map them in the Dashboard. However, any fields that use Lob's naming convention will be automatically mapped. The Lob naming convention for CSV column headers are indicated below in bold.

Required columns

  • name: Recipient name must be 40 characters or less

    • Note the name as it appears in this column will appear in the "To" field in the address block on your mail piece

    • If more than 40 characters are needed, you can also utilize the (optional) companyfield; when both are provided, they will be printed on two separate lines above the rest of the address.

  • address_line1: Must be 64 characters or less

  • address_city: Must be 200 characters or less

  • address_state: (e.g. CA for California)

  • address_zip: Must follow the ZIP format of 12345 or ZIP+4 format of 12345-1234

    • Lookout! MS Excel and Google Sheets may attempt to drop leading zero.

  • Any merge variable data

    • When using merge variables that point to a URL, like images or custom fonts, ensure the link is public and can be accessed by Lob

Optional columns

  • address_line2: Must be 64 characters or less

  • company: Must be 40 characters or less

  • address_country: Must be in convention (e.g. US for the United States of America)

Metadata columns

Tagging your mailpieces with can help identify and group your mail sent in any given campaign for easier reporting and attribution. While optional, if you choose to add metadata tags, you cannot add more than 20 Key-Value pairs. Keys can be at most 40 characters and values must be at most 500 characters.

  • Recipient metadata: is passed in the CSV and applies to each individual row, or recipient. Recipient metadata is great for tags that are specific to each recipient of mail, like state:NC or first_name:John.

    Recipient metadata can be passed in the CSV one of two ways:

    1. As regular column data: You can use any number of the CSV columns as metadata for your mailpieces such as “name”, “address_line1”, etc. The values for this column for each row should be regular text and not JSON formatted. See our on how to use more than one column from your CSV file as metadata. Example: If you have a column header in your CSV file called “recipient” and the value of the cell for this column in the first row is “john_smith”, then the metadata that gets attached to your mailpiece for this row will be “recipient: john_smith”

    2. In multiple columns, prefixed with metadata_. For example, your file could have metadata_key1 and metadata_key2 columns, and then the values that correspond to each mailpiece in each row.

  • This is different than Campaign Metadata

    • It is configured on the POST /v1/campaigns or in the Lob dashboard, on the Campaigns screen in Step 1 at the bottom in the “Add campaign-level metadata tags” section.

      • Note: Campaign metadata is not configurable within your CSV

    • Each individual mailpiece created through the campaign will inherit Campaign metadata. This is ideal for tags you’d like to apply to an entire campaign and can be set in Step 1.

Only 1 of the above methods can be used at once. If you have a column name prefixed with metadata_ in your CSV file but you’ve also selected a regular column to be used as metadata for your mailpiece, then the the values from the metadata_ prefixed column will NOT be used. We prioritize the manually selected columns to be attached as metadata.

If you have not manually selected any column from your CSV file to be used as metadata and the CSV file contains a metadata_ prefixed column, then the data from the metadata_ prefixed columns will be used as metadata for each mailpiece automatically.

Column names prefixed with metadata_ DO NOT need to be manually selected as metadata. They are automatically applied. If you would like to manually select this column, then simply remove the metadata_ prefix from the column name.

See to learn more about how this powerful feature can help parse your mail.

Step 2: Map your data to your campaign

If a merge variable has the same "name" as a "key" in the requiredAddressColumnMapping or optionalAddressColumnMapping objects, then they CANNOT have a different value in this object. If a different value is provided, then when the campaign is processing it will get overwritten with the mapped value present in the requiredAddressColumnMapping or optionalAddressColumnMapping objects. The redirect URLs for QR codes can also be customized using this mapping. If the URL has a variable and the variable mapping existsing here, then data from the respective column in the audience file will be merged into the URL template.

Dashboard

Upload your CSV file in > Step 2: Add Audience.

Campaigns API

When the POST or PATCH request to the /v1/uploads endpoint, you will need to pass in an array of key-value pairs in the requiredAddressColumnMapping property. The keys will be the Lob-required field names, and the values will be the column headers in your CSV.

For the other properties that you can pass in the payload, refer to our .

Example: POST /v1/uploads

Step 3: Add your return address (if applicable)

Within campaigns, you're able to choose if you'd like to have a single return address or a personalized return address for your recipients. A return address is optional depending on the form factor (e.g. Postcards), but required for other form factors (e.g. Letters).

Single Return Address

A single return address allows you to select a return address that you have created within Lob, to use across all of your recipients in your campaign. In this case, every recipient will have the same return address on their mail piece.

Personalized Return Address

A personalized return address allows you to have a unique return address for each recipient within a Campaign.

Within the campaign flow, in Step 2: Add Audience, a block will appear to set up your return address after you have added your audience to the campaign. The default option is to use a Single Return Address, or you can select Personalized Return Address.

When you select Personalized Return Address and new mapping fields to map the return address values will appear if you have already uploaded your audience file. Similar to the address mapping for a recipient delivery address, the return address mapping connects to the CSV file uploaded in one-time campaigns and the integration table for automated campaigns.

If you have Personalized return address selected, then the fields below will be required in order for you to submit the campaign:

  1. Default return address

    1. If there is any data field missing in your audience file for a particular recipient, the default return address will be used as a fallback option to still produce a valid return address on your mail piece.

  2. Return_address_name

    1. The name (first/last) for the return address

  3. Return_address_line1

  4. Return_address_city

  5. Return_address_state

  6. Return_address_zip

Optional return address fields can be added to the return address, but are not required to be filled in to submit the campaign:

  1. Return_address_line2

  2. Return_address_company

  3. Return_address_country

Required fields are denoted in the UI with a red exclamation icon, whereas the optional fields show a gray exclamation icon.

Similar to the recipient delivery address mapping, if your audience file includes the column headings that match the return address variables above, then we will auto-map these variables together. If we can’t detect which column to auto-map to, then you will need to manually map these fields together to properly connect.

You cannot use the same return address column data as used in a recipient address delivery field. For example, if you have an “address_line_1” column in your audience file and you map that to the recipient address line 1 field, you can’t also use that same address_line_1 field for the return address line 1. In this case, if you have already used that field in another mapping, then when you go to select that column in the return address mapping it would say “already mapped”. There's handling in place that prevents a user from mapping the same address to a recipient to the return address so that a customer doesn't go around the return address in a way they aren't supposed to. When you have all of the mapping implemented correctly you should see a green success indicator for each return address field and no more red exclamation icons.

After you have successfully added and mapped your return address fields on step 2 of campaigns, you will see a confirmation of the field mapping on step 4 of campaigns. Verify the information in step 4 for your return address is correct. If you haven’t done so already, we recommend you generate a creative proof to have a full preview with the address data inserted on the address block for the return address.

After you submit the campaign, in the campaign details page, select the details tab to view the return address details that were submitted with the campaign. At this point, each mail piece created from the campaign will be using a return address based on the mapping you had outlined.

Step 4: Map merge variable data (if applicable) to your creative

Dashboard

Merge variable data (if applicable) is mapped in > Step 3: Choose Creative

Campaigns API

This can either be in Step 2 during the initial POST request or updated using a PATCH. When sending the request, pass in an array of key-value pairs in the mergeVariableColumnMapping property. The keys will be the merge variable names defined in your HTML template and the values will be the column headers in your CSV.

Example: POST /v1/uploads

Troubleshooting common issues

When uploading your CSV audience file, ensure the filetype is correct.

  • To ensure compatibility, ensure your CSV is UTF-8 encoded (Unicode).

  • Your file should have an extension that ends in .csv.

  • In rare cases, your file type might appear to have a .csv extension but actually be saved in a different, unsupported format.

Avoid opening up your audience CSV in a spreadsheet program like Excel if possible.

  • If you do need to open the file, avoid saving the file or making updates. These programs will automatically make changes to your file when saved, which could potentially cause issues on upload.

  • Stripped leading zeros for zip codes are the most common issue. For example, the program turns Zip Code 07751 into 7751. Zip codes that begin with “0” are in the Northeast, specifically CT, MA, ME, VT, NH, NJ, RI.

Avoid line breaks in your audience file to prevent your CSV from being rejected.

  • If you need line breaks as part of a merge variable, consider using two merge variables at this time.

Avoid commas in your audience file to prevent your CSV from being rejected.

  • Check if your CSV file has commas that are separating values that belong in unique columns per the specifications above.

Checks

Checks overview

To get started with sending checks, you'll need to to originate checks from. You will also identify which and you want associated with the account, then Lob will . This process is outlined below.

Just looking for check specs? Skip ahead to here.

More resources: Once you have setup your Bank Account, visit our , , or our for ideas on how to get started.

Create a new Bank Account

In the dashboard, see the Bank Accounts section (under Print & Mail):

You can also add a bank account but note you are unable to upload a signatory image via this method.

Check templates

In the “Bank Accounts” section of your dashboard (under Print & Mail) you will select which template you would like to associate with your bank under the “Check Template Type”.

We offer two options when it comes to check templates:

Common Check: This is the universal check we have offered that is accepted at the majority of banks across the US.

JPM Check: This is the JPM check template that is approved by JP Morgan Chase and utilizes Positive Pay.

If you are using the JPM Check template, you will need to add additional information (Bank City, State, Zip, and Fractional Routing Number).

Check with your bank

Check with your bank to make sure that the check will be accepted. A new check template or different signatory can cause the bank to flag your account. The best way to avoid this happening is to let your bank know that the checks are valid.

Your money is not transferred to Lob. When the payee deposits the check that was sent through Lob's Checks API, it will pull money directly from the specified bank account into the recipient's bank account.

Uploading a signature for checks

One of the options for associating a custom signature to a bank account, so that it can be printed on checks, is uploading an image file when you create a Bank Account in the Lob dashboard.

Signature image file

The uploaded signature will be printed on all Lob checks originating from that specific bank account. Make sure to download the digital signature and authorize its use with your bank once your bank account is created.

If you would like to upload a new custom image file as a signature anytime after the initial creation of the bank account, you must reach out to with:

  • The bank_account_id of the bank account that corresponds with the signature

  • A PNG of the signature (the background of the image must be transparent)

When an image for the signature isn’t provided, we implement a cursive font rendering of the signatory’s name instead.

Below are the guidelines to adhere to when prepping your image so that the signature can best be extracted and processed.

Image format

The image must be in either a JPEG or PNG format (.jpg, .jpeg, .png). The background of the image must be transparent.

Dimensions

The image must be at least 330px x 105px. The image may be larger but we recommend a width to height ratio of approximately 3:1 for best results.

Color and size

The signature must be written in black or dark ink on a white or light background. The signature should be centered and should occupy most of the image.

Things to avoid

Here are a few of the most common mistakes that we recommend you avoid when preparing a signature image.

DON'T: Have the signature too small in your uploaded image.

Make sure to center your signature and crop your image as needed so that the signature takes up a majority of the space.

DON'T: Write your signature on ruled or patterned paper.

Write your signature on a white or light-colored background to ensure proper signature processing. Using ruled or patterned paper will likely result in unintended artifacts.

DON'T: Include other objects or artifacts in your image other than the signature.

If you are taking a photo of your signature rather than using a scanned image, make sure to prepare your photo so that all artifacts and non-signature objects (e.g. tables, pens, dark shadows) are cropped out.

Verifying your bank account

Lob will send two micro-deposits, ranging from 1 - 100 cents, to the specified bank account in order to verify the account. You'll be asked to enter them in the dashboard or submit them through the API before you can send out any checks.

This is especially important if you are sending checks on behalf of your customers. You must verify all your customers' bank accounts before sending checks from them. This is most easily done through the API.

Lob's Check service only works with US banks, based on US banking standards and formats. We do not support foreign bank accounts at this time.

Fraudulent activity

Our security team continuously reviews newly-created accounts. New accounts that trigger a flag will be immediately suspended and required to provide additional verification.

Limitations

If you send a high volume of checks, send checks in very high dollar amounts, or you are sending HIPPA data, you may need to upgrade your to gain access to this form factor, or reach out to our to learn more.

If you have any questions or concerns about the safe-guards we have in place around the use of checks, please .

Check dimensions & specs

The specifications for Lob's check product are as follows:

  • Measures 8.5 x 3.625" in size

  • Contains warning bands, void indication, and security weaver on backer

  • is perforated with the bottom ⅔ of the page available for the sender to customize with artwork

  • Uses fugitive ink to provide additional protection against duplication of the document

  • Includes a prismatic multicolored background with subtle graduations to make copying and reproducing difficult

  • Produced with controlled stock, which ensures the security of the mail piece at every stage of production. The Padlock Icon printed on the checks ensures that the product meets or exceeds industry guidelines

  • Mailed in a #10 white outer envelope (double-windowed)

Note that logos and branding can be added to checks via an , but cannot be added through the dashboard. For more details on the space your logo can take up, visit our .

Check front
Check back

Customizing check pages

You can choose to leverage the blank space at the bottom of the check by using check_bottom to add any branded artwork or personalization, even if these check pages themselves do not require any artwork in order to be sendable.

It is also possible to send a letter as an attachment with your check (but not the other way around) by using the attachment string.

If you choose to customize this optional bottom section of the check, be sure to follow the provided template and leave room for the actual check itself; otherwise you risk invalidating the check. You may also add up to 5 sheets (10 double-sided pages) of optional attachment pages.

See our for more details on the check_bottom and attachment parameters, or see the for design inspiration.

  • (optional)

  • (optional)

Check bottoms and check attachments will always be printed in black and white.

Check bottom template
Customized check example

Mailing checks

Ensure your checks get to their final destination by following these guidelines:

  • The from field is required for all checks, regardless of the destination

  • Checks can only be mailed using (takes 4 to 6 business days)

  • USPS Mail (Marketing Mail) and are not available for checks

  • Overnight mailing options are not available for checks

Launch your first campaign

...with our Campaigns builder in the Lob dashboard

This guide below will walk you through how to launch a campaign from the Lob dashboard, using our Campaigns tool. Here is a preview of the 4-step process:

Before you get started

You'll need three things at the ready to create your Campaign:

  1. (including send and delivery strategies)

  2. (.csv format)

  3. (front & back), as static PDFs or as HTML templates for dynamic creatives. (HTML templates will need to be loaded into the dashboard prior to use in Campaigns).

Send campaigns in the dashboard

First, head over to the in your dashboard, and click the Create Campaign button at the top right. Select One-time to start building your campaign. Any campaign you build in the Live environment will be saved into your Drafts until you place an order.

If you would like to set up and send individual mailpieces based on triggers from your customer data, learn more about here.

Step 1: Configure settings

Note: fields marked with * are required; all others are optional features.

  1. *Add campaign name: To begin, give your campaign a unique name and description to reference in the future. Give it a name that is distinguishable and easily identified when you have numerous campaigns in your dashboard.

  2. Add billing group: Certain Lob customers can optionally choose a specific billing group to allocate their campaign to on their invoice. You can learn more about this functionality .

  3. Select campaign type*: Select what will your campaign have: are you sending out a marketing campaign or using this for operational (non-promotional) purposes?

  4. Select mail type & settings*: Select what mail type and size you’ll be sending. Currently, you can choose from high-quality postcards, self-mailers, or letters sealed inside envelopes.

    • Postcards and self-mailers will show available size options

    • Letters will show optional add-ons, such as cards, envelopes, and buckslips

  5. Send options: ASAP or schedule a future date up to 180 days

  6. Postage preferences:

    • Add the return address you’d like to appear on the mailpiece

    • Select the * that you’d like to apply to your campaign; note this will have pricing implications

    • Select an amount of time for your campaign , which is the amount of time you are allowed to quickly edit and QA your mailings after submission, but before they are sent to print production

  7. Add campaign-level tags: Add any custom you'd like to apply to your campaign. Tags enable you to easily filter and sort your campaigns for future reporting.

Step 2: Add audience

  1. Upload your target audience*: Select your segment via

  2. Map required address fields*: Lob automatically maps and formats your address to meet USPS requirements, but you can review and adjust the mapping if necessary

  3. Map optional address fields: These fields will be added to your recipient address block if mapped

  4. Add recipient-level tags: Add any custom you'd like to apply to your campaign-specific recipients. Tags enable you to easily filter and sort your campaigns for future reporting.

Step 3: Choose creative

  1. Upload your creative assets* (Example, front and back of postcard)

    • Make sure you are following the specific to your mail format

    • You can utilize or ; learn more about here. (If using HTML, the template will first need to be loaded into the dashboard as a Live .)

    • If sending a letter campaign, upload your add-on creative assets as well

    • When your creative is uploaded, you will be shown a basic preview; a true creative proof is available in later step

You can to your mailpieces after you upload your creative.

  1. Connect your creative to your audience*

  • Select your merge variable strictness: Choose whether you'd like your mailpieces to be sent even if it contains

  • Map merge variables in your creative: If using an HTML template to build a dynamic creative, if you've named your csv column headers exactly to match the merge variable names in the HTML template, then Lob should automatically map these. For example, if a merge variable in a template is {{promo_code}} and there is a CSV column header titled “promo_code” then Lob auto-maps this for the user.

Please note auto-mapping is case-sensitive.

Step 4: Proof & Review

  1. Creative proof: The Creative proof includes merge variables, address block, Lob carbon-neutral logo, and indicia, plus return address and QR codes if included. You can View Mail Proof to see (or share) the PDF, or you can Delete Proof and go back.

  1. Campaign settings: Review the campaign send details

  2. Audience: Review the target audience list

  3. Creative: Preview a mailpiece to ensure the campaign will render correctly

  4. Cost: An estimated campaign cost based on cost per mailpiece (learn more about )

Please review carefully before you Place Order. You can back up to previous steps to make changes as needed. Should you need to exit the UI, your Campaign will be saved as a Draft.

  1. Place order! Once your campaign is submitted it will be sent to the printer in the submission window selected before being dropped to USPS for delivery.

You will receive confirmation, then be directed to the detail or status page for the Campaign.

Campaign status

After you place an order you will be directed to that campaign's status or details page. You can also access this at any time by clicking on any individual (Live) Campaign from the Campaigns dashboard.

Here you can Cancel a One-time campaign (if applicable), or Pause/Resume an Automated campaign.

In the kabob menu, you can find the campaign ID, export undeliverables ("Export Failures") and export mailpiece data.

Cancel a campaign

Did you place your order and then suddenly realize there was a mistake or last-minute change? You can cancel a Campaign if you are within the .

  1. After placing an order, you will be directed to that campaign's detail page. Alternatively, from the (Live) Campaigns view, click on any campaign to navigate to the campaign's detail page.

  2. If applicable, click the Cancel Campaign button.

  3. You will be asked to confirm; your Campaign will go back into Draft state.

  4. Your Campaign will be canceled; you can return the dashboard or edit the Campaign.

  5. You will also receive an email confirmation.

Campaign Analytics

After you place an order you will be directed to a detailed view of your campaign. You can return here at any time by clicking into any individual campaign from the Campaigns section in the dashboard.

In the section of the dashboard you will find data for all mail you have sent with Lob across any number of campaigns within a time period. But you can click into any Live campaign to see laser-focused insights that are campaign-specific.

Our campaign analytics are designed to help you ensure that every campaign you run is more informed than the last.

Campaign summary: Get the birds-eye view of each campaign with stats including total orders, estimated cost, delivered and undeliverable mailers.

Tracking events for all mail pieces in the campaign provide full visibility as your mailpiece move through the mailstream.

QR code engagement: Understand how recipients interact with your Lob-generated QR codes, including frequency and timing of scans.

Delivery speed: Track how quickly your mail moves from being sent to marked as processed for delivery, pinpointing efficiency and flagging any delays. Reserved for Enterprise users only.

Delivery distribution: Analyze where your mail is going and how fast it gets there with a breakdown of mail pieces by state, helping you optimize your future send strategies. Reserved for Enterprise users only.

Failed mail pieces

After you place your order and it has fully processed, any number of mail pieces that failed rendering (and will not be sent to print) will be shown in red under View Failed Mail Pieces. Read more about and .

Short URLs

Lob’s Short URLs allow you to take a long URL from your website or landing page and create a personalized, shortened, and trackable URL to display on your direct mail creative. For example, if you have a landing page destination URL for your mail campaign like:

using Lob's URL Shortener, you can transform this URL to a custom short URL of your choosing like . The shortened URL will still point the end user to that full destination URL above, but will make it easier for a user to digest and type in their browser when receiving the direct mail piece.

Lob’s Short URLs can be accessed and created in both the Dashboard and within the campaigns flow directly.

In the dashboard, navigate to the “Creative” navigation item, then click Short URLs. Here you will see all Short URLs you have created with Lob.

To create a new short URL, click the Create button at the top right of the page.

Within the Short URL creation flow, you’ll see:

  1. Title

    1. The title you can give your Short URL to easily find and select in the future. E.g. You’ll see this title to select in the campaign flow if you want to use the short URL in a campaign.

    2. There are no character limits for the title

  2. Destination

    1. This is the full URL that you want to send users to that should be shortened. In the example above, this is where you would put a URL such as

    2. There are no character limits for the destination URL

  3. Shortened Display URL

    1. Domain

      1. The default domain uses Lob’s built in subdomain “lob.st” which allows you to simplify create a short URL off of as long as that URL is available and not being used by others.

      2. To customize and personalize this subdomain, you can click to Manage Domains from the Short URLs main page above and create a custom domain to then select and use in this URL creation flow.

    2. Back-half

      1. This is the path that you would like users to see on their mail creative, which then would redirect to the full destination URL above. Using the above example again, this is where you would have . In this case, would be what you add on your direct mail creative copy to then be printed. When users type in their web browser, it would then redirect to the full destination URL.

      2. There are no character limits for the back-half URL

  4. Metadata

    1. For future analytics and easier searchability, we allow you to add metadata to your Short URLs. If you want to categorize your Short URLs in any way to then access more easily at a later point in time, metadata allows you to add multiple a tag names and values.

Manage custom Short URL domains

Within the Short URL main page, click the Manage Domains button at the top to enter the Short URL domain details page.

Here you will see all of the custom short URL domains you have created and linked to Lob.

To create a new custom Short URL domain, click the Add a New Domain button at the top.

To link a domain, add your primary or subdomain in the Domain field in this modal. If there’s ever a time when the subdomain, for example, becomes inaccessible or deprecated, you can enter an Error Redirect URL. The Error Redirect URL should point to a domain that will be more stable such as your primary home page, so if a user in the future types the URL in a browser they’ll be redirect to your home page.

When you create your custom domain, the status of the domain will be Inactive by default. To set as active, you’ll need to look your domain provider to Lob by following the steps below. Please note: once a domain is added, it can only be deleted via API request at this point in time.

Activating your new custom domain

When you create a new domain in the Lob dashboard with the steps above, you’ll need to configure your DNS settings so that it works with our platform. Follow this simple guide to ensure your domain is set up correctly.

Configuring your new domain

This is for when your domain is not being used for any purpose other than for short links.

1. Sign in to your domain registrar's website (e.g. Cloudflare, GoDaddy, etc.)

2. Locate your DNS settings.

  • Find the DNS settings or DNS management section within your account. See the documentation below for your registrar if you need help.

3. Create an A Record.

  • Add a new DNS record with the following details:

    • Host: @

    • Type: A

    • Value: 207.174.61.1

    • TTL: You can leave this at the default setting. Common defaults are 3600 seconds or automatic.

  • Note: Some domain registrars do not allow `@` as a value for the host. If so, leave the field blank.

4. Save your changes

  • Ensure all changes are saved to make your DNS record active.

5. Wait for domain activation.

  • Domain activation can take a few hours. Once the status changes to “Active,” your domain is ready to use for shortening links.

Configuring subdomains

Note: If your main domain is already in use for hosting a website, directly pointing it to our service could result in unwanted behavior, such as users being redirected unexpectedly from your main site. To avoid this, set up a subdomain dedicated to short links.

If you already own a domain and don’t want to register a new one, you can create a subdomain and use that to shorten links. A subdomain setup allows you to maintain brand consistency and save on registration costs. Here’s how to configure a subdomain:

  1. Sign in to your domain registrar's website.

    1. Use the same steps as above to locate the DNS settings for your domain.

  2. Create a CNAME record for your subdomain.

    1. Add a new CNAME record with the following details:

      1. Host: Your desired subdomain. For example, if you want your short links to use `links.example.com`, enter `links` as the host.

      2. Type: CNAME

      3. Data/Points to: cname.short.io

      4. TTL: You can leave this at the default setting. Common defaults are 3600 seconds or automatic.

  3. Save your changes.

    1. Ensure all changes are saved to make your DNS record active.

  4. Wait for activation.

    1. Just like a regular domain, your subdomain will be ready to use after a few hours.

Managing DNS records with specific hosting providers

If you need detailed steps on how to edit or add DNS records with your domain registrar, here are links to their official documentation for DNS management:

Troubleshooting

Domain propagation (the process of DNS records updating across global servers) can take up to 24 hours, though it typically happens within a few hours. If you are not seeing the status of your domain update to Active within the Lob dashboard, see the following troubleshooting steps:

  • Incorrect DNS Records: Ensure that you’ve correctly added the necessary A or CNAME records and removed extra or conflicting records.

  • Remove extra or conflicting DNS records: Delete any DNS records that might interfere with the proper setup of your domain/subdomain.

  • Domain Forwarding Issues: For some registrars like Namecheap or GoDaddy, you may need to disable domain forwarding.

If your domain is not active after 24 hours, please reach out to our support team.

Using Short URLS in your mail campaigns

Within Campaigns, you can add one short URL to your campaign. The short URL added to a campaign does not have to be unique to the creative and you may use the same short URL across multiple campaigns or creative. Note when doing this approach though, visits on that URL would be looked at in aggregate across all of the campaigns/creative. So if you would like to specify which campaign had visits, we recommend creating a short URL specific to that campaign.

Tag your campaign with a static short URL

Static short URLs can be added to a campaign to simply track URL visits for that campaign. Most commonly used with PDF creatives, static short URLs allow you to attach a trackable short URL to a campaign, so if the end recipient visits the URL that’s placed on your mail creative, the campaign will be associated with a visitor to that URL link. Note that for this functionality to work, the short URL tagged in the campaign must match the short URL on your mail piece’s creative.

To add a static short URL to your campaign, create a new URL in the or directly within the campaign flow on the Creative step. For any previously created short URL, you can select to add an existing short URL previously created within the Creative step of the campaign flow as well.

Map your short URL to a merge variable on your HTML creative

Lob can insert a shortened URL onto your html template using merge variables if you don’t want to add the shortened URL to your creative at the time of designing your creative. To insert and map your shortened URL to the html template variable, add your creative with merge variables in the Creative step of campaigns. Add your desired shortened URL to the campaign, and within the creative merge variable mapping section, select the merge variable where you would like the URL applied to. The shortened URL title should show at the bottom of the mapping variable dropdown field to select. We recommend creating a proof within your campaign before submitting to confirm the short URL applies in the correct spot on your creative and looks as expected before sending to print.

Short URL Analytics

Currently short URLs are tracked at the campaign level, not at the recipient level. This means you will be able to see that your “Summer 2024” campaign had 100 URL visits, but you won’t be able to know “John Smith” is one of the recipients who visited that URL.

You can view analytics for your short URLs in two ways: in the engagement tab within the mail analytics page of the dashboard, or within a campaign details page analytics. Both URL charts will show how many mail pieces were sent with a Lob short URL attached to it, and if a user visited that URL it will then show the total number of visit to that URL. The mail analytics page on the dashboard will allow you to see all short URL sends and visits in aggregate, with the ability to filter by various aspects like date range or metadata. The short URL chart within a campaign details page will only show the URL sends and visits within that campaign specifically, taking into account the date from when the campaign was sent to today. If no short URL was added to your campaign, you will see a placeholder showing no short URL was added instead of seeing the URL chart.

Mail analytics

Overview

Our feature in the Dashboard provides insights to empower you to fine-tune targeting, enhance engagement, and optimize the overall effectiveness of your direct mail campaigns. You can slice and dice your data by certain filters to view a full deliverability report, all directly from your Dashboard.

To access this feature, sign in to your Dashboard and click the "" tab in the left navigation bar.

We also offer . Similar to the metrics below, these are visible from any Live campaign's details page.

Tracking events

Lob is the only intelligent platform that tracks each piece of mail as it moves through the USPS delivery process. This section gives you full visibility into where all the mail you've sent in any given time period sits in the mail stream. As you send higher volumes of mail with Lob, you may need to analyze the status and deliverability of your mail on a more aggregate basis.

The Tracking Events tab displays a visual breakdown of all tracking events applicable to the mail pieces within the filter parameters.

You can export all tracking events data into a CSV file;

Tracking event stepper

The tracking stepper at the top of the dashboard displays the different stages in your mail's delivery process:

  • Sent: This is a count of non-deleted mailings that you have sent to Lob in the specified time frame based on the date for which a piece was scheduled (the piece's send_date), not the date the API request was made.

  • In production: Mail piece instructions were dispatched to Lob's printer network and the request is now being printed/cut, soon to be handed off to the USPS for fulfillment.

  • Mailed*: This bucket is a count of all pieces that have received a event, which represents handoff to USPS. Access to "Mailed" Events is exclusive to certain customers. Upgrade to the appropriate to gain access.

  • In Mailstream: This bucket is an aggregate of two tracking events, In Transit and In Local Area. These are the first two scans that a piece will receive—representing that it's in the mailstream and on the way to its destination.

  • Processed for Delivery: This bucket is represents pieces that have received a Processed for Delivery scan. This scan means that the piece has been approved for delivery at the destination's nearest postal facility and will likely be delivered in 1-2 business days.

  • Delivered: This bucket represents pieces that have received a Delivered scan, meaning they were delivered to the end recipient. The final scan is generated when the mail carrier's GPS unit leaves the delivery area.

  • Re-Routed: If a piece is re-routed due to recipient change of address, address errors, or USPS relabeling of barcode/ID tag area, it will receive this scan.

  • Returned to Sender: A piece will receive a Returned to Sender scan if delivery was attempted, but failed due to barcode, ID tag area, or address errors.

Each mail piece will be counted once in each bucket for which it receives a scan. For example, if a letter has these tracking events:

  • "In Transit"

  • "In Local Area"

  • "Processed for Delivery"

Then it will be counted once in the "Sent", "In Mailstream", and "Processed for Delivery" buckets.

Reading the graph

Under the Tracking Event statistics on the dashboard, we also provide a graph that provides an even further breakdown of your mail by day, week, or month. Time periods are grouped by the date a piece was sent, not by the date of the API request. As with all other dates within the Lob system, the UTC time zone is used.

Hover over a specific column to view a full tracking breakdown for that time period. Use this breakdown to narrow down your data for even further analysis.

Benchmarks

Over time, you can expect to see tracking events for 98-100% of your mailings. The numbers below are benchmarks for when you should start seeing scans. Keep in mind that these timings and percentages may vary based on the volume of mail you've sent, where you're sending to, and the quality of your address set.

For First Class mail, you'll start to see mailings reach the "In Mailstream" bucket in 2-3 business days and the "Processed for Delivery" bucket 1 business day afterward. After about 4 business days total, you should expect almost all of your mailings to be in the "In Mailstream" state. After about 5 business days total, almost all of your mailings should be in the "Processed for Delivery" state.

For Standard Class mail, which is inherently slower, the timing is a bit different. You'll start to see mailings reach the "In Mailstream" bucket in 4-5 business days and the "Processed for Delivery" bucket 2 business days afterward. After about 10-11 business days total, you should expect almost all of your mailings to be in the "In Mailstream" state. After about 12-13 business days total, almost all of your mailings should be in the "Processed for Delivery" state.

Certified and Registered letters and Overnight checks are excluded from this dashboard because they are with USPS.

The tracking data in my mail analytics dashboard doesn't seem right, what can I do?

Tracking Events: If you notice that the tracking events on your mail analytics dashboard are missing or not up to date, it is because USPS didn't scan the mailpieces. However, note that if USPS doesn't scan the mailpiece in the first place, then there is no way for Lob, to recover the tracking events to display on the dashboard as we receive this tracking information from USPS.

No 'Mailed' Event: (Note, event is an Enterprise feature only). It could be that these mail pieces were sent out as metered mail by USPS, which makes it unmeasurable in our system even though the mailpiece is en route to its destination.

Ingestion Issue: Delay in receiving Tracking events data from USPS cause the tracking events data to not be reflected on the mail analytics dashboard. In these cases, once we receive the data from USPS we will backfill these events.

Certified Letters: Only mail sent through First Class or Standard class mail will be displayed on the Dashboard. To see the current status of the letter, you would have to click on the USPS Tracking Number that USPS provides.

Engagement

QR Code Engagement

If you have sent any mail containing QR Codes, the next step is learning the engagement rates associated with these mailpieces. The will track how all mailpieces you’ve sent with QR Codes are performing over a selected period of time. (You can see QR engagement analytics for any on that campaign's detail/ status page.)

In this tab you can:

  • Filter by a date range and form factor

  • See the number of mailpieces sent with QR Codes during that time period

  • See the number of QR Codes that have been scanned during that time period

  • See a graph of QR Code scans over a selected date range

  • Filter for more specific subsets of your mail by leveraging .

To receive more detailed analytics, such as time of scan, IP Address, etc, reference in our API documentation.

Informed Delivery

We offer engagement metrics for each Informed Delivery campaign. It's important to remember not every member of your audience may be subscribed to Informed Delivery daily emails. As such, here you will see how many emails were sent for your campaign, and the engagement rate.

  • Mail pieces sent

  • Emails Sent

  • Open Rate

  • Click Through Rate

Mail speed

Access to this feature is exclusive to Enterprise plan customers. Upgrade to the appropriate to gain access.

Track how quickly your mail moves from being sent to marked as processed for delivery, pinpointing efficiency and flagging any delays.

The Mail Speed tab shows the number of business days it took from a mail piece's send_date to the date the mail piece was marked as processed_for_delivery by the USPS.

The Mail Speed graph respects all applied filters and shows the average and median mail speed for all the mail pieces that fall within the filter. Mail pieces that have yet to receive a processed_for_delivery tracking event are not counted in the metrics above the graph.

Please note, the graph is for US mail only.

Mail distribution

Access to this feature is exclusive to Enterprise plan customers. Upgrade to the appropriate to gain access.

Analyze where your mail is going and how fast it gets there with a breakdown of mail pieces by state, helping you optimize your future send strategies.

The Mail Distribution tab shows the number of mail pieces sent to each US state (and Washington D.C., but excludes US territories). A state's color corresponds to how many mail pieces have been sent to that state.

Hovering over a state will provide more details like how many mail pieces have received a processed_for_delivery tracking event, as well as average and median mail speeds (calculated the same way as the tab).

You can also view the data in a table format. The table shows the same data as the map, where each state's data corresponds to a row. Clicking on a column header will sort the values in that column. To search by state name, click on the search icon and input a value to filter the table.

Filtering

On your Mail Analytics Dashboard, you can slice-and-dice your data by various other aspects of your mailings, including: product type, recipient ZIP code, template used, and more. You can use these filters to compare deliverability between your different campaigns, recipients, and more.

Be sure to leverage Lob's more deeply tag your Lob mailings with any internal data you may have, such as a customer ID or campaign ID. Then, you can easily filter by that metadata within the Analytics Dashboard to view different deliverability reports based on those factors.

For mail sent to , we only expect to get either "In Transit" or "In Local Area" scans. For this reason, we've added a top level filter where you can compare US and international mailings, with the last three tracking buckets disabled for international mail.

You can export analytics data (svg, png, csv) by clicking the hamburger menu located at the top right of the graph.

{
   "campaignId": "{{campaign_id}}",
   "requiredAddressColumnMapping": {
       "name": "recipient",
       "address_line1": "primary line",
       "address_zip": "zip_code",
       "address_state": "state",
       "address_city": "city"
   }
}
{
   "campaignId": "{{campaign_id}}",
   "mergeVariableColumnMapping": {
       "mergeVariable1": "dog",
       "mergeVariable2": "cat",
   }
}
Campaigns
Dashboard
API
2-letter US state short-name code
ISO 3166-1 alpha-2
metadata
API documentation
API call
Configure Settings
Using Metadata
Campaigns
sending
API documentation
Campaigns
configured

create a bank account
check template
signature image
verify your account
Check dimensions & specs
Checks API documentation
GitHub library
Template Gallery
via our Bank Accounts API
[email protected]
Print & Mail edition
sales team
contact us
Paper
API request
API documentation
Checks API documentation
Template Gallery
Check bottom
Check attachment
First Class Mail
Standard Class
Certified Mail
Common check
JPM check
Campaign strategy
Audience file
Design assets
Campaigns tab
Lob integrations
here
use case
postage and mailing class
cancellation window
tags
CSV
tags
design guidelines
PDF
HTML
Creative formatting
HTML Template
add a QR code
missing values in your merge variable fields
Estimated Campaign Cost
cancellation window
Mail Analytics
rendering best practices
rendering errors
https://www.lob.com/product/integrate-target?utm_source=direct-mail&utm_medium=summer-2024&utm_campaign=promo
lob.st/mail
https://www.lob.com/product/integrate-target?utm_source=direct-mail&utm_medium=summer-2024&utm_campaign=promo
lob.st/mail
lob.st/mail
lob.st/mail
Ionos
Cloudflare
DreamHost
Freenom
Gandi.net
GoDaddy
Hostgator
Hostinger
Name.com
Namecheap
Namsilo
Porkbun
Spaceship
Squarespace
dashboard
Mail Analytics
Mail Analytics
campaign-specific analytics
see more details on exporting mail data here.
Mailed
Print & Mail Edition
tracked via their own external tracking numbers
Mailed
Engagement tab
specific campaign
metadata
QR Analytics endpoint
Print & Mail Edition
Print & Mail Edition
Mail Speed
metadata feature
international destinations
For more details on exporting mail data see here.
Tracking stepper (Mail Analytics -> Tracking Events)

AV Elements

How to get started

Registration

Create an account at Lob.com to obtain a Live Public API Key. The key is available in the API Keys tab of the Lob Dashboard Settings and uses the format, live_pub_*

Usage

Address Elements works by targeting the input elements of your address form and using their values with Lob's verification and autocomplete functionality. Include the AV Elements script tag immediately before the closing <body> tag

Code demo:

<script src="https://cdn.lob.com/lob-address-elements/2.2.1/lob-address-elements.min.merged.js"
  data-lob-key="live_pub_xxx"
></script>

Sandbox:

>>

Shopify users

AV elements works great with e-commerce platforms because they use predictable element names. For example, Shopify users can simply paste the following preconfigured script at the bottom of their Shopify Plus template.

Remember to replace live_pub_xxx with your Lob public key

<script src="https://cdn.lob.com/lob-address-elements/2.2.1/lob-address-elements.min.merged.js"
    data-lob-key="live_pub_xxx"
    data-lob-verify-value="strict"
    data-lob-primary-value="false"
    data-lob-err-bgcolor="#006eff"
    data-lob-err-color="#ffffff"></script>

Many E-commerce platforms have strict content security policies that prevent scripts from loading additional content. Embed the merged build of Address Elements to handle these situations as shown in the example above (lob-address-elements.min.merged.js). This ensures all dependencies are included in the download.

Attribute reference cheatsheet

The Address Verification script has many attributes to give you complete control over its appearance and behavior. They generally go by the following pattern:

data-lob-*-id
data-lob-*-value

These attributes are used to identify an element on your web page. Their values should be the elements ID and correspond to the components of an address: primary line, secondary line, city, state, and zip.

Example: data-lob-primary-id="address1"

These attributes modify the behavior of autocomplete and verification. Their values are either true, false, or a string from a list of options

Example: data-lob-verify-value="passthrough"

Form detection attributes

With version 2, AV Elements can detect address form inputs automatically. We can improve performance by skipping the form detection process when these attributes are provided. Set them to the IDs for each field to target.

  • data-lob-primary-id

  • data-lob-secondary-id

  • data-lob-city-id

  • data-lob-state-id

  • data-lob-zip-id

  • data-lob-country-id

Form functionality attributes

These attributes modify the behavior of AV Elements

Attribute name
Attribute value(s)

data-lob-verify-value

  • strict

  • normal

  • relaxed

  • passthrough

  • false

Controls the strictness level when verifying an address. If the strictness criteria is not met, we block the form submission and prompt the user to correct the address. Set to passthrough to submit the form regardless of the verification result. Set to false to disable verification altogether.

Default: relaxed

data-lob-primary-value

Enables or disables address autocompletion.

Default: true

data-lob-secondary-value

When set to false, force the suite or unit number to render on the primary address line during address verification.

Default: true

Custom error handling

data-lob-*-message-id Identifies the element containing the error message at the input level. Lob will update the text content for this element and toggle its display.

  • data-lob-primary-message-id

  • data-lob-secondary-message-id

  • data-lob-city-message-id

  • data-lob-city-message-id

  • data-lob-zip-message-id

  • data-lob-country-message-id

Example: data-lob-primary-message-id points to the element below the input for Address 1. Any errors related to the primary line will be inserted inside this element.

data-lob-err-*-value Overrides the default error message when a value is missing or specific Lob verification error messages

  • data-lob-err-primary-line-value

  • data-lob-err-city-state-zip-value

  • data-lob-err-zip-value

  • data-lob-err-undeliverable-value

  • data-lob-err-missing-unit-value

  • data-lob-err-unnecessary-unit-value

  • data-lob-err-incorrect-unit-value

  • data-lob-err-confirm-value

  • data-lob-err-default-value

data-lob-anchor-id This optional attribute will place the general error message before the element with the id provided. An alternative attribute is data-lob-anchor-class which will search for the target element by class name.

Usage with React & Vue

Modern web frameworks like React and Vue boost developer productivity without sacrificing control. Add IDs to the components of your address inputs (they will be included in the compiled HTML at runtime) then include these IDs in the form detection attributes of the AV elements script.

If your component has many layers, you must ensure that the ID is propagated down to the root html components being used.

React example

React demo

>>

In this demo we use React out of the box and create an address form. The AV elements script is added in public/index.html before the closing body tag. This demo also overrides some styles to keep the verification message centered in the form and to undo the styles applied to our primary address by our dependency algolia (for autocompletion).

Vue example

Vue 3 demo

>>

Similarly, the AV elements script is also placed in public/index.html before the closing body tag.

A note about component libraries

The AV elements script searches for key form elements like the form tag and <input type="submit" />. When building your form with component libraries such as Material-UI or Ant Design, check for the following:

  • An ID can be propagate down to the root html elements used by the component.

  • The components render the appropriate html elements for their behavior - they are materially honest (e.g. not styling links as buttons or using hidden elements to work correctly)

Case #1 may be the more common scenario you'll come across. If this happens, you will need to fallback to writing the component yourself in place of using the library's component.

International support

International address verification is enabled when there is a country input present and it is set outside the United States. Form detection is relaxed on international forms since different countries may require different sets of address components.

Autocomplete is disabled for international addresses.

Troubleshooting

AV Elements employs multiple strategies to detect your address form. If none of them work, we display an error message to help fix this. Those messages are shown below:

Missing or duplicate form elements

Problem: These errors arise in the form detection process:

Either we are unable to find the input for a given address component, or we detected multiple inputs that may correspond to the same address component. There could be various causes for these errors including the input not existing, a label we're not familiar with, or a problem with the component's implementation from an external library.

Solution: Add the attribute(s) mentioned in the error to the AV elements script. The value should be an element id. For example, with the message above we must add the attribute data-lob-state-id.

<script src="https://cdn.lob.com/lob-address-elements/2.2.1/lob-address-elements.min.merged.js"
data-lob-key="live_pub_xxx"
data-lob-state-id="id_of_state_input"
></script>pick

Segment

Overview

is a platform that captures and stores all first-party customer data regarding your product or service in a centralized place. More specifically, Segment collects events from your interfaces (websites, web apps, etc.), and from that information, helps you create more personalized customer experiences across various channels.

We will plug Lob into our Segment flow by making a custom destination function. Destinations are business tools or apps to which you can send the data you collect in Segment. Depending on which mailpiece form factor you want to send (postcard, letter, etc.), building a destination function that sends it merely involves reading the data and calling Lob’s API. These steps are outlined below.

Getting Started

  • Make sure you have a and your . It is highly recommended that you use your (secret) test API key first

  • Have a ready to use (hosted PDF file or HTML template)

  • Have your ready

Connect Segment to Lob using Destination Functions:

Learn more about destination functions API at

  1. In the sidebar, navigate to “Connections” -> “Catalog,” and then click the Functions tab:

  1. Click the “New Function” button:

  1. Under “Select Function Type,” click “Destination,” and then click “Build”:

  1. Enter your Javascript code in the editor on the left, and test your function on the right; refer to on form factors for details. Click “Configure” when done:

  1. Give the function a name (required), description, and logo, and click “Create Function” to save:

Segment Events by Mail Form Factor

The following are sample functions to send a Lob mailpiece from a given Segment event, organized by mailpiece. Segment provides six different event types that destination functions can operate on:

  • : who is the customer?

  • : what are they doing?

  • : what web page are they on?

  • : what app screen are they on?

  • : what account or organization are they part of?

  • : what was their past identity?

The following sample code translates Track events into Lob mailpieces by defining an onTrack function. (For other functionalities, just define a similarly named function, e.g., onPage for Page events.)

Postcards

Letters
Self Mailers
Checks

Remember to test your mail sent through Segment by using your test API key first. Once you do, plug in your live key, and enjoy sending intelligent, automated mail pieces with Lob and Segment!

Conclusion

Given how useful Segment is for integrating multiple different interfaces for collecting and operating on customer data, this tutorial gives us the ability to add Lob as one of many possible powerful tools for accomplishing data-driven, instantaneous operations on that data. Luckily, plugging Lob into Segment is as easy as making a destination function and using it in your workflows.

Resources

Here are two other resources that might help with crafting your workflow:

/**
* @param {SpecTrack} event The track event
* @param {Object.<string, any>} settings Custom settings
* @return any
*/
async function onTrack(event, settings) {
 const body = {
   description: 'Description of the card,'
   to: {
     name: event.properties.name,
     address_line1: event.properties.address.line1,
     address_line2: event.properties.address.line2,
     address_city: event.properties.address.city,
     address_state: event.properties.address.state,
     address_zip: event.properties.address.zip
   },
   front:
     "<html style='padding: 1in; font-size: 50;'>Front side for {{name}}</html>",
   back: "<html style='padding: 1in; font-size: 20;'>Back side for {{name}}</html>",
   merge_variables: {
     name: event.properties.name
   }
 };


 const response = await fetch('https://api.lob.com/v1/postcards', {
   method: 'POST',
   headers: {
     Authorization: `Basic ${btoa(settings.apiKey + ':')}`,
     'Content-Type': 'application/json'
   },
   body: JSON.stringify(body)
 });


 return response.json();
}
/**
* Handle track event
* @param  {SegmentTrackEvent} event
* @param  {FunctionSettings} settings
*/
async function onTrack(event, settings) {
 const body = {
   description: 'Description of the letter',
   to: {
     name: event.properties.name,
     address_line1: event.properties.address.line1,
     address_line2: event.properties.address.line2,
     address_city: event.properties.address.city,
     address_state: event.properties.address.state,
     address_zip: event.properties.address.zip
   },
   from: {
     name: event.properties.return_addr.name,
     address_line1: event.properties.return_addr.line1,
     address_line2: event.properties.return_addr.line2,
     address_city: event.properties.return_addr.city,
     address_state: event.properties.return_addr.state,
     address_zip: event.properties.return_addr.zip
   },
   file: "<html style='padding: 1in; font-size: 50;'>Front side for {{name}}</html>",
   color: 'false',
   use_type: 'marketing',
   merge_variables: {
     name: event.properties.name
   }
 };


 const response = await fetch('https://api.lob.com/v1/letters', {
   method: 'POST',
   headers: {
     Authorization: `Basic ${btoa(settings.apiKey + ':')}`,
     'Content-Type': 'application/json'
   },
   body: JSON.stringify(body)
 });


 return response.json();
}
/**
* Handle track event
* @param  {SegmentTrackEvent} event
* @param  {FunctionSettings} settings
*/
async function onTrack(event, settings) {
 const body = {
   description: 'Description of the self-mailer',
   to: {
     name: event.properties.name,
     address_line1: event.properties.address.line1,
     address_line2: event.properties.address.line2,
     address_city: event.properties.address.city,
     address_state: event.properties.address.state,
     address_zip: event.properties.address.zip
   },
   inside:
     "<html style='padding: 1in; font-size: 50;'>Inside side for {{name}}</html>",
   outside:
     "<html style='padding: 1in; font-size: 20;'>Outside side for {{name}}</html>",
   use_type: 'marketing',
   merge_variables: {
     name: event.properties.name
   }
 };


 const response = await fetch('https://api.lob.com/v1/self_mailers', {
   method: 'POST',
   headers: {
     Authorization: `Basic ${btoa(settings.apiKey + ':')}`,
     'Content-Type': 'application/json'
   },
   body: JSON.stringify(body)
 });


 return response.json();
}
/**
* Handle track event
* @param  {SegmentTrackEvent} event
* @param  {FunctionSettings} settings
*/
async function onTrack(event, settings) {
 const body = {
   description: 'Description of the check',
   to: {
     name: event.properties.name,
     address_line1: event.properties.address.line1,
     address_line2: event.properties.address.line2,
     address_city: event.properties.address.city,
     address_state: event.properties.address.state,
     address_zip: event.properties.address.zip
   },
   from: {
     name: event.properties.return_addr.name,
     address_line1: event.properties.return_addr.line1,
     address_line2: event.properties.return_addr.line2,
     address_city: event.properties.return_addr.city,
     address_state: event.properties.return_addr.state,
     address_zip: event.properties.return_addr.zip
   },
   bank_account: 'bank_a4fc08e61e12c6c',
   message: 'INSERT MESSAGE HERE',
   amount: 0, //Insert an amount here
   use_type: 'marketing',
   merge_variables: {
     name: event.properties.name
   }
 };


 const response = await fetch('https://api.lob.com/v1/checks', {
   method: 'POST',
   headers: {
     Authorization: `Basic ${btoa(settings.apiKey + ':')}`,
     'Content-Type': 'application/json'
   },
   body: JSON.stringify(body)
 });


 return response.json();
}
Segment
Lob account
API keys
creative file
Segment account
https://segment.com/docs/connections/destinations/destination-functions
the following section
Identify
Track
Page
Screen
Group
Alias
Segment's docs on connections, the meat and potatoes of making workflows
Learn more about Lob's strictness setting‍
Click here to open sandbox environment
Click here to open sandbox environment
Click here to open sandbox environment

Zapier

Overview

Zapier gives you the ability to connect Lob to thousands of other business tools - like Slack, MailChimp, Gmail, and Trello - to automate your tedious workflows. In just minutes, you can set up automated Zaps to correct, standardize, and enrich addresses, as well as send automated letters or postcards using Triggers from pre-built integrations.

  • Zapier integrates Lob with thousands of other business applications

  • Set up automations, called 'Zaps', to automate repetitive tasks

  • No coding required

  • Sign up for a free Zapier account to create automated workflows

  • Zapier integrations are great for sending mail at small scale, instead of manually, but are not a replacement for a proper integration when sending mail in large batches (hundreds/thousands).

  • If you are passing in links to image files for your content, use a high availability service like S3 to avoid issues with timeouts. If we are unable to access your content it will not render properly.

Integrate with Zapier in 4 simple steps:

  1. Sign up for Lob and Zapier accounts

  2. Connect Lob to Zapier, within the Zapier interface

  3. Connect any other apps/services (for example, where you store customer data) to Zapier, in order to then connect them with Lob

  4. Create custom workflows or leverage popular automations with pre-existing Zaps

Every Zap requires one connected app to be used as the Trigger, which is where your information comes from, and this causes one or more Action steps to occur in other apps, which is where your data gets sent to.

Getting started with Lob & Zapier

Sign up for a free Lob account. You can send Test API requests for free to start, or instantly begin sending real mail by simply adding a payment method to your account.

Sign up for a free Zapier account, where you will begin building the automation.

Connecting Lob to Zapier

  • Log in to your Lob Account

  • Log in to your Zapier account

  • Navigate to "Connected Accounts" from the top menu bar in Zapier

  • Now click on "Connect new account" and search for "Lob"

  • Use your Test Lob API Key to connect your Lob account to Zapier

    • Start with your Test API Key so that you can set up and test your Zap without sending live mail initially.

  • Once connected, you can start creating an Automation! Use a pre-made Zap, or create your own with the Zap Editor.

  • Need inspiration? See everything that's possible with Lob and Zapier

  • Once you've tested your first Zap, all that is needed is switch your Lob API key to the Live Key to begin sending actual mail!

Getting started with Zapier

To help you hit the ground running, you can choose from one of many popular pre-made Zaps:

Other popular workflows

Sending postcards with Google Sheets & Zapier

Use Lob’s Zapier integration to automatically send postcards whenever new users are added to your mailing list.

Before starting, make sure to open accounts with Lob + Google + Zapier before starting to create this automation. Here, we will be using a Google Sheets file as our existing mailing list. This kind of setup significantly reduces the amount of manual work needed to send out mail and can be generalized for a number of different situations.

Stage 1: Setting up Google Sheets as your Trigger event in Zapier

  1. From the Zapier home screen, click on a “Make a Zap!” button to get started

  2. Select Google Sheets in the dropdown of available Trigger Apps, then Choose Trigger: “New Spreadsheet Row”

    • This means whenever a new row is created in our Google Sheet, Zapier will take an action on your behalf

  3. Connect your Google account to Zapier and give Zapier access to the account

  4. Once your account is connected, test out the connection using the “Test” option. If the connection works you will see the grey “Test” box turn into a green “Success!” box.

  5. Pick a spreadsheet + worksheet to pull information from

    • As this is the starting point for your automation, make sure that the correct information is being pulled

  6. Once a spreadsheet and a worksheet are selected, Zapier will pick a sample row. If the information accurately reflects what is found on the sheet, select the “Continue” option.

  7. In the next stage, you will configure the action you want Zapier to take after your trigger is initiated.

Stage 2: Setting up your Action

  1. Continue to build your Zap by clicking on the blue “Your Zap currently lacks an Action step. Add one now!” text. Alternatively, you can also click on the “+ Add a Step” button on the left side of your screen.

  2. Select Lob to be your Action App.

  3. Select “Send Postcard” as the action Lob will take after the Zap is initiated by the Trigger.

  4. Connect your Lob account to Zapier and give Zapier access to the account, so it can take action on your behalf.

  5. Once connected, you may receive a pop-up instructing you to verify this request by entering your Lob API key.

    • Use your Lob Test API Key; any requests sent with your Test API key will not cause mail to be sent or charges to be incurred. Once the integration is working, you can return to this step and swap in your Live API Key.

  6. Once the API key is passed, you will have the option to test the connection. If you click the “Test” button on the right and everything is valid, then you will see a green “Success!” button.

  7. Fill in the appropriate information needed to complete your mail. Note that some fields are optional and others are required.

    1. The green “Setup Preview” icon allows you to see an example of what your named variable would look like in your Zap. If you do not enable it you will not see an example.

    2. Be sure to you prepare your content images correctly. For this example, we are inserting HTML of the artwork directly into Zapier for both front and back sides of the postcard.

      • For more information on how to properly set your mail content for Zapier/Lob, see here. Example HTML templates can be found in our Template Gallery.

      • Alternatively, provide a link to a hosted PDF, PNG, or JPG file

    3. Add the address that will receive this postcard.

      • We’re going to use Zapier’s named variables function here; this time on the Address.

      • By using the named variable function, Zapier will pull the corresponding information for me every time a new entry is added to the Google Sheet.

    4. Lob defaults to USPS First Class Mail (a faster option), but Standard Class mail is also an option.

Stage 3: Test the Zap to Confirm

  1. Test the entire Zap (From Trigger to Action) by clicking on the "Send Test to Lob" button.

  2. Zapier will run a test, and once it runs through successfully you will be notified at the top of the page. An additional alert will tell you how long it’s been since the test was successful.

  3. Formally name your Zap and turn it on. If the Zap is not on, then Zapier will not execute against the workflow you set up in Stages 1 + 2).

Setting up webhooks with Zapier

With Lob you are able to track each step of a mailpiece's journey from production through to delivery. In addition to making these metrics available in the platform, Lob offers webhooks for each event, allowing you to listen to these events and pull this event data back into your own systems. With Zapier, the process is as follows:

  • Lob sends out a webhook when the mailing gets created

  • Zapier "catches" the webhook notification

  • Zapier notifies you that the mailer was created, scanned, delivered, etc.

Webhooks by Zapier can be configured if you have a premium subscription with Zapier. There’s no native integration for outgoing webhooks to Zapier, but there’s a way to catch these events using a generic webhook configuration. You can learn more about Webhooks by Zapier integrations and all the apps that are available for use.

In this example, we will set up a Zap to automate the following: every time Lob sends a new event for your mailpieces—and Zapier receives (the Trigger), Zapier will send you an email notification via Gmail (the Action).

  1. Start by clicking “Create Zap” on the homepage.

2. First you will Next, select the option “Webhooks by Zapier.”

3. Under “Choose app & event,” select “Catch Hook” from the “Event” dropdown options and hit continue. This is what starts the Zap.

On the “Set up trigger” screen that follows, hit “Continue.”

4. A URL will be generated, which you will need to configure with Lob.

When an event occurs within Lob architecture and you have a webhook subscribed to that event type in that environment (Test vs. Live), we will attempt to make a POST request with the entire event object to the URL provided.

5. Copy the Webhook URL then login to your Lob dashboard; on the Webhooks page, click “Create a new webhook.” Name your webhook, then paste the URL provided by Zapier into the “URL” field.

Then choose the EVENT TYPES you want sent. Due to the inherent limitations of Zapier, we advise selecting from one form factor (postcards, letters, etc.) per Zapier integration. See here for a full list of all available event types that you can subscribe to.

In Live mode, you can only have as many (non-deleted) webhooks as allotted in your current Print & Mail Edition. There is no limit in Test mode.

6. Now click the “Debugger” button on the top right-hand side corner.

The Debugger allows you to trigger webhook attempts to a specified URL with a generated event body. This should mainly be used to determine JSON structure, as all IDs and URLs within the event bodies sent are not real.

Select one EVENT TYPE from the dropdown options, and click “Send.” You should receive a 200 OK response.

7. Now go back to Zapier. Test the connection by clicking “Test trigger.”

8. You should see your event. Click “Continue.”

9. Now select which integration/app you want to Action on. Here we selected “Gmail” to receive event notifications for each mailpiece via email. Select “Send Email” and hit “Continue” to connect your Google account to Zap.

10. Fill in the required fields, and for the ones you would like to map the Lob webhook events to, click the field, select “Show all Options,” and select the option of your choice.

In this example, we want to receive notifications for the event_ID, date and time when this event gets created, and the sender's information on the postcard. Note this will be redacted as this contains Personal Identifiable Information (PII). You can choose any of the fields from the available options that you would like to receive notifications about based on your preferences.

Fill out the rest of the fields where you’d like to receive these webhook notifications, review the contents, and you’re almost done! Select “Publish Zap.”

You should receive an email with the webhook events that you selected.

The last thing needed is to Name your Zap (if you haven’t done so already) and to “Turn on Zap.” If the Zap is not on, then Zapier will not execute against the workflow you set up (Trigger to Action).

11. If all the steps are set up correctly, then you should receive a green checkmark on both “Trigger” and “Action.”

If Zap failed to create, then you will receive a message on where to fix the issue and an additional message regarding the error. Here’s a link to the HTTP status codes that the API would return in case of an error that may help in troubleshooting.

Adding merge fields

To integrate merge variables on Zapier, you would need to paste the full HTML string directly into the text box, then use the built-in merge functionality from Zapier to insert variable content. This is an example of what that might look like:

Watch the screencast above for more context.

Support information

Feel free to email [email protected] for issues on the Zapier side, or [email protected] for Lob-specific debugging!

Adding QR codes

Overview

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

  • our in the dashboard,

  • our (Print & Mail and Campaigns API), and

  • we also support the use of to generate QR codes.

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 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 to gain access to this feature, or reach out to our 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.

Custom QR codes: Adding a logo

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 object in the transactional API request body while creating , , or . In the Campaigns API (beta), this object can be found in the ) call.

Custom QR codes

These features are available for Enterprise users. Upgrade your to gain access to this feature, or reach out to our 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. Logos can be up to 2MB, but ideally should be optimized to a smaller file size.

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

  • section on URL redirects for how to personalize URLs.

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.

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.

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 }}, 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.

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 ‘’, 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. .

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

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 , or learn more about here in the help center.

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.

PDF preflight checklist

How to check/save files in compliance with Lob’s PDF guidelines

What is preflight?

Preflight is a print industry standard term for checking files for things that might cause issues in the physical output before you start the printing process. It is however NOT a standard set of checks or ways to solve those problems. Every printer has its own flavor of Preflight that does the checks and/or resolution steps in a different order.

Lob’s preflight module requires each file to meet the PDF-X/1a standard. PDF-X/1a is a standard for creating reliable and predictable PDF files for print production. (The "X-1a" part refers to the specific version of the PDF/X standard, which has certain requirements and restrictions to ensure compatibility and consistency.) To render and execute your campaigns quickly, and at scale, our ability to audit every file is limited. We run an automated check—where fixes are automatically applied—but in doing so, it may negatively impact your mailpieces.

To ensure each mailpiece is rendered exactly like you intend, please submit print-ready files by following the preflight checklist below.

Requirements for static PDFs

Must be PDF/X-1a compliant

If you have Adobe Acrobat Pro, you can use the Preflight function to run a report on your PDF which will alert the issues with your PDF file and also allow you to fix/convert the PDF file to PDF/X-1a format.

To perform these actions in Adobe Acrobat, please follow the steps outlined below:

How to review:

1) Open Acrobat and the desired PDF

2) Access the Production tools by clicking on (View > Tools > Print Production) from your window pane. Alternatively, you can locate it on the right-hand side of the screen under search tools by expanding the Print Production tab.

3) Once the Print Production tools are open, click on the Preflight option.

4) In the Preflight window, select the "PDF/X” tab.

5) Choose the option "Convert to PDF/X-1a (Coated GRACoL 2006)”

6) You then have two options:

  • If you want to generate a report detailing errors in your PDF file, click on the “Analyze” button.

  • To analyze and fix any identified issues click the "Analyze and Fix" button. **This option will also save your file in PDF/X-1a format.**

How to Save:

  1. Select the PDF file that you want to convert to PDF/X.

  2. Once the PDF document is open, go to the “File” menu option and choose “Save As”

  1. In the “Save As” dialog box, specify the desired location on your computer to save the converted file. Choose a recognizable name for the converted PDF/X-1a file.

  2. Next, look for a dropdown menu or an option that allows you to select the file format. Click on the PDF/X option.

  1. Next, configure the settings:

  • Select Save as PDF/X-1a

  • Select Convert to PDF/X-1a (Coated GracOL 2006)

  1. Click the “OK” button to initiate the conversion process.

  2. Depending on the size and complexity of the original PDF file, the conversion process may take a few moments or longer. You may see a progress bar indicating the status of the conversion.

  3. Once the conversion is complete, the software will save the PDF/X-1a file to the specified location on your computer.

Flatten transparency

If transparencies are not flattened, overlapping colors may change and objects may disappear completely. To ensure predictable and accurate print results, it is generally recommended to flatten transparencies before submitting the file over to Lob for printing. Flattening eliminates potential issues and helps create a final output that closely matches the intended design.

How to review:

  1. Open the pdf you want to check

  2. Open Print Production tools (View > Tools > Print Production)

  3. Click Preflight

  4. Click the PDF/X tab

  5. Click convert to PDF/X1-a (coated GRACoL 2006)

  6. Click on the Analyze button.

  7. The preflight tool will return information on where transparency was applied.

How to save:

  1. Open PDF file to flatten

  2. Open Print Production > Flattener preview

  3. Select Transparent Objects from the dropdown for highlight, any transparencies will be highlighted in red.

4. If you’re unable to select the Transparent object instead have the option to select None (Color Preview) which means the file doesn’t have any transparencies.

5. Click Apply.

Remove layers

When you create a PDF from layered documents using software, such as Adobe InDesign or Adobe Photoshop, your PDF can contain multiple layers with different content on each one. If you submit the PDF file as is, you will only print the layer that is visible onscreen as opposed to all visual elements from various layers. To avoid this issue, you want to flatten your PDF file for print. Flattening a PDF before print removes transparency information and converts it to a format that the printer can read. Ensure the creative/PDF file you’re submitting over is flat and there is just one single layer prior to submission.

How to review:

  1. Open the PDF file or creative you want to check.

  2. Click on the layers icon on the left panel as shown in the screenshot below.

  3. If there are layers on your file, they will be listed as Layer 1, Layer 2, etc.., under Layers

How to remove

Follow the above three steps, then click on the layer icon and select the Flatten Layers option.

Alternatively, you can flatten the PDF to remove layers and transparencies. Please check - How to Save a File under flattening transparencies.

Fonts must be embedded

Please note the Lob can and cannot support.

Fonts must be outlined (preferred) or Fonts that have not been outlined or embedded might change or render incorrectly, specific letters may be substituted with incorrect glyphs.

How to review:

  1. Go to "File" and choose "Open" to select the PDF file you want to check the fonts.

  2. Click on "File" and then select "Properties" from the dropdown menu.

  3. Access the Fonts tab: In the Properties dialog box, click on the "Fonts" tab.

  4. Check font embedding status: You will see a list of fonts used in the PDF document. Look for fonts that are listed as "Not Embedded" or "Embedded Subset."

If the above is not true for your PDF file, you will have to follow the below instructions on how to embed fonts in PDF.

How to save/embed fonts:

If you are using InDesign, export PDF with PDF/X1a setting and all fonts will be embedded. Likewise, if you are using Microsoft Word, “save as Adobe PDF” (not Microsoft's “save as PDF”) choose the High Quality Print settings, and all fonts will be embedded.

If you no longer have access to the original document and all you have is the PDF file with fonts that aren't embedded, Acrobat does provide a fix for embedding fonts via the Preflight feature. There is a fix for embedding missing fonts. Note that this requires that (1) the missing fonts are actually installed on your system and (2) the fonts themselves do not prohibit embedding in a PDF file.

  1. To embed a new font, go to File > Print and then select Adobe PDF. Click Properties.

  2. Select the Adobe PDF settings tab at the end and then click the EDIT button to the right of the default settings.

  3. Next, a left menu of folders will appear in the pop up window. Click Fonts, then make sure the fonts you need to embed are on the fonts source list. If so, tick the box at the top that says Embed all fonts.

  4. If they are not, then you will need to close the pop up window and either move or duplicate the fonts files from where you have stored them to C:/Windows/Fonts. If you struggle to find this then you can search for the folder in the search bar on the launcher menu.

  5. All fonts you want to embed in the PDF should be in the Fonts source list. You now need to move the desired fonts to the Always Embed box.

  6. Click OK on the pop-up window and you’re done.

Please note that font embedding may increase the file size of the PDF document.

File size under 5MB

Lower file size allows for easier processing at the print level. Large files have a higher potential to fail

How to review:

  1. Open the PDF file that you’re looking to check.

  2. Click File > Properties. Under the Description tab check for "File Size" where you should be able to see the size of the file.

How to compress:

  1. Open the PDF you wish to re-save as a smaller file.

  2. Choose File, "Save as Other," and then "Reduced Size PDF."

Color in CMYK

The color should be CMYK Color Space (SWOP v2 or GRACoL 2006/2013 preferred). By submitting CMYK you will avoid potential conversion errors when Lob changes RGB to CMYK.

How to review:

  1. Open the pdf you want to check the color profile for

  2. Open Print Production tools (View > Tools > Print Production > Output Preview

  3. Under Show > select dropdown CMYK.

  4. This will show the area which is in the CMYK profile.

How to save:

  1. Open the pdf you want to save

  2. Open Print Production tools (View > Tools > Print Production)

  3. Click Preflight

  4. Click the PDF/X tab

  5. Click convert to PDF/X1-a GRACoL 2006)

  6. Click on Analyze and Fix button.

This will save the file in CMYK format.

Image resolution at 300 ppi

Image resolution should be 300 ppi. If the resolution is below 300 ppi, you may see pixelation and incorrect color saturation of your images; if ppi greatly exceeds 300 the file size will be too large and have the potential to fail.

How to review:

To determine the resolution of an image in pixels per inch (PPI) on a Mac, you can use the built-in Preview application. Here's how:

  1. Locate the image file on your Mac and select it.

  2. Right-click (or Control-click) on the image file and select "Open With" from the context menu.

  3. Choose "Preview" from the submenu. The image will open in the Preview application.

  4. In Preview, click on the "Tools" menu at the top and select "Show Inspector". A sidebar with image information will appear.

  5. In the Inspector sidebar, click on the "General" tab. You should see information about the image, including its dimensions, file size, and resolution.

  6. Look for the "Resolution" field, which will display the image's PPI value.

Please note that not all images may contain PPI information. In such cases, you can still determine the image's dimensions in pixels and calculate the PPI manually by dividing the pixel dimensions by the desired print dimensions.

No printer marks

Do not submit printer marks (or trim lines) including, but not limited to crop marks, trim marks, bleed marks, slug lines, registration marks, color bars, page information, etc.

Our production facilities have several QA standards in place to ensure cuts are made appropriately and the color is correct. Any content uploaded is treated as part of the design, and thus the printer marks will cause the dimensions to be larger than the intended image size, resulting in an error. If you are exporting an image for a printing proof the way you usually would when sending images to traditional printers, then the trim lines should be unticked in your settings to ensure a sizing error does not occur.

How to review:

The below marks are referred to as the printer marks. Lob's APIs will not accept printer marks (or trim lines).

How to remove:

Avoid having any printer's marks in your PDF by ensuring your image export settings do not include them. To remove these trim lines and color bars from your PDF, open your file in Adobe Acrobat, go to Settings, and clear the Printer’s Marks checkbox.

Note that whether or not you export with “Bleed” will depend on how you built your template. If you already manually added the bleed (e.g. 4.25" x 6.25" artwork), then you should have that unticked as well.

See also: How to download a profile on Acrobat to remove the printer marks on.

Other considerations
  • Adjust margins and borders to ensure they meet the printer's specifications and accommodate any necessary trimming.

  • Page boxes (ArtBox, CropBox, TrimBox, and MediaBox) should all be consistently sized

  • Set the correct page size and orientation.

  • Bleed: Ensure the document has sufficient bleed (if needed) to avoid any white borders around the printed area.

Page elements

  • Double-check that all text is spelled correctly and positioned correctly on the page.

  • Verify that images, logos, and graphics are in the correct locations and are of high quality.

  • Ensure that important content is not too close to the edge to prevent it from being cut off during trimming or binding.

font types
embedded.
Youtube
 "qr_code": {
    "position": "relative",
    "redirect_url": "https://www.lob.com/?customer_id12345",
    "width": "2",
    "top": "2.25",
    "left": "3.125",
    "pages": "back"
},   
// 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"},

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

{
   “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”
   }
}
{
   "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"
   }
}
QR code
Campaigns tool
APIs
3rd-party APIs or Javascript
engagement analytics
Print & Mail edition
sales team
qr_code
Letters
Postcards
Self-mailers
Creatives (Create
Print & Mail edition
sales team
See below
www.google.com?q={{name
Address Block
Reference the Ink-Free areas for each template here
bleed edge
Mail Analytics
campaign-specific analytics
API documentation
API documentation
using webhooks
UTM parameters
Screen_Shot_2020-11-02_at_6.13.28_PM.png
Screen_Shot_2020-11-04_at_9.41.04_PM.png
Screen_Shot_2020-11-02_at_6.13.18_PM.png

Braze

Overview

Use the following as an addendum to the for using Lob with Braze.

This integration will allow customers to send data from Braze to Lob. A pre-designed webhook can then be used within a campaign to trigger mail to customers. After sending through Braze, the mail data can be accessed from within the Lob dashboard.

Step 1 - Add Custom Attributes

Add Custom Attributes for user mailing address information:

  • address_line1

  • address_line2

  • address_city

  • address_state

  • address_zip

  • address_country

Step 2 - Update user profiles

Update user profiles with mailing addresses.

:

:

Anything highlighted is a custom variable that will need to be updated for each customer or use case.

Step 3 - Create a webhook template

Create a webhook template (). Once this template is made it can be used for your future campaigns as well. In the case that you have different variations of sends, meaning you are going to perform one send with postcards and one with letters it is recommended that you create 2 separate webhook templates in Braze for this.

Additionally, if you are going to be doing small variations such as sending first-class vs standard class depending on the recipient, then you can leverage Braze's . You can build this logic into the template and have one webhook template support multiple variations.

Example postcard

Compose tab:

Webhook URL: https://api.lob.com/v1/postcards

Request body: Raw Text

Braze's default webhook template does not include the opening and closing {} brackets, so ensure those have been added before saving.

Example letter

Compose tab:

Webhook URL: https://api.lob.com/v1/letters

Request body: Raw Text

Example self-mailer

Compose tab:

Webhook URL: https://api.lob.com/v1/self_mailers

Request body: Raw Text

Settings tab

Be sure to leave the : after the Lob API key you paste in between the apostrophes.

REQUEST HEADERS:

  • Authorization: Basic {{ 'YOUR_LOB_API_KEY:' | base64_encode }}

  • Content-Type: application/json

  • Idempotency-Key: {{${user_id}}}

    • It is recommended that you leverage idempotency keys to prevent duplication of mail being sent. It can be any value you seem fit but often it is userID or a combination of userID and campaign name.

  • HTTP METHOD: POST

Step 4 - Test your new webhook

Test your new webhook template and check your Lob dashboard to ensure desired results. It is recommended to run a one-off test in Braze to see if the request format is set up appropriately and then run a full end-to-end test where you send an entire campaign through your test environment.

Running a one-off test

When running a one-off test it is useful to have test users in your system who have the correct data needed to send mail and validate your creatives. Here is an example of a test we would perform.

Common errors

  1. 401 Unauthorized

    • If you receive this error message, your API key is incorrect.

    • Make sure you have the header Authorization and that you are encoding your secret API key with a colon after the key like this Basic {{ 'YOUR_LOB_API_KEY:' | base64_encode }}

  2. 422 Unprocessable Entity (Invalid request payload JSON format)

    • If you receive this error, it is likely that your payload is not formatted correctly. It needs to match JSON formatting.

    • Generally speaking, the rules that are often broken are:

      1. All keys and values are enclosed in double quotes (").

      2. Commas after every key-value pair except for the last one.

      3. No newline characters in any values and no extra spaces between fields.

  3. 422 Unprocessable Entity (Other)

    • Other than JSON errors, you can receive 422 errors in the payload sent to Lob does not match our requirements.

    • For example, if you are missing address_line1 in the payload you will get an error saying that is needed. For these errors, you can make the appropriate adjustments and retry your requests.

The "testing" functionality in Braze is sending a one-off request to Lob, this means if you have your LIVE API key in the template it will create mail and if you have your test key it will not.

Make sure when you are testing that your cancellation windows are set to an ample time (2 hours is recommended) to make sure you can always cancel mail if you make a mistake.

FAQs

How do I use merge variables from Braze?

To leverage merge variables, in Braze you will reference the merge variable in your HTML file as the Key and the user attribute as the value.

For example, if you had a merge variable called f_name in your HTML, then in the section of your payload called merge_variables you would have a key of f_name and a value of the user attribute in Braze. Here is an example of what that would look like in Braze

What do I use for the file parameter for letters? What do I use for the front and back parameters for postcards?

See more information on file format types

Essentially you can either host your HTML in the Lob platform where you can then reference the template ID that is created for you, or you can leverage Braze’s where you will be provided with a URL that can be used as the value for these parameters.

Here is an example of what you could see in Braze:

Capturing Lob webhook data in Braze

Braze’s Data Transformation tool enables you to capture webhook events from Lob, and use them to either update Attributes or create Events within Braze.

Steps:

  1. Set up a Data Transformation in Braze. This will generate a Webhook URL you can use to pass events into Braze.

    • See

  2. Create for the events you want to track, using the Braze-provided URL

  3. Set up the Transformation Code in Braze to listen for the event. You can use this to either update an Attribute or generate an Event.

    • See Example 1 below for a 'Letter Viewed' example, in which it both updates an attribute within Braze and creates an Event.

  4. Send a Test webhook and check the resulting Output to ensure the data is successfully being captured, and the subsequent attribute/event updates are occurring within Braze

Example 1: Braze Transformation Code for Letter Viewed, which updates the attribute 'external_id' and generates an Event named 'Letter Viewed' when the webhook from Lob is received:

Example 2: Braze transformation output after webhook received, showing the updated attribute 'external_id' and creating the Event 'Letter Viewed'.

Other Resources

Advanced logic

  • String manipulation, date formatting, etc. See Braze’s .

Idempotent requests

  • See Managing mail settings >

Rate limiting

  • By default, all accounts and their corresponding Test and Live API Keys have a rate limit of 150 requests per 5 seconds per endpoint

curl -X POST \
  https://rest.iad-01.braze.com/users/track \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "Braze_API_Key",
    "attributes": [
      {
          "external_id" : "10142019",
          "address_line1" : "185 BERRY ST STE 6100",
          "address_line2" : null,
          "address_city" : "SAN FRANCISCO",
          "address_state" : "CA",
          "address_zip" : "94107-1741",
          "address_country" : "UNITED STATES"
      }
     ]
   }'
{
    "description" : "{{campaign.${name}}}",
    "metadata" : {
        "campaign" : "{{campaign.${name}}}"
    },
    "to" : {
        "name" : "{{${first_name}}} {{${last_name}}}",
        "address_line1" : "{{custom_attribute.${address_line1}}}",
        "address_line2" : "{{custom_attribute.${address_line2}}}",
        "address_city" : "{{custom_attribute.${address_city}}}",
        "address_state" : "{{custom_attribute.${address_state}}}",
        "address_zip" : "{{custom_attribute.${address_zip}}}"
    },
    "from" : "adr_2066448bdef840f1",
    "front" : "tmpl_8b3b1249ede0406",
    "back" : "tmpl_d69077c7be7bd09",
    "merge_variables" : {
        "name" : "{{${first_name}}}"
    }
}
{
    "description" : "{{campaign.${name}}}",
    "to" : {
        "name" : "{{${first_name}}} {{${last_name}}}",
        "address_line1" : "{{custom_attribute.${address_line1}}}",
        "address_line2" : "{{custom_attribute.${address_line2}}}",
        "address_city" : "{{custom_attribute.${address_city}}}",
        "address_state" : "{{custom_attribute.${address_state}}}",
        "address_zip" : "{{custom_attribute.${address_zip}}}"
    },
    "from" : "adr_2066448bdef840f1",
    "file" : "tmpl_d69077c7be7bd09",
    "color" : "true",
    "merge_variables" : {
        "name" : "{{${first_name}}}"
    },
    "metadata" :
        "campaign" : "{{campaign.${name}}}",
        "zip" : "{{custom_attribute.${address_zip}}}"
    },
    "mail_type" : "usps_first_class",
    "double_sided": false,
    "address_placement": "top_first_page",
    "mail_type": "usps_first_class",
    "return_envelope": true,
    "perforated_page": 1,
    "extra_service": "registered",
    "custom_envelope": null,
    "billing_group_id" : ""
}
{
    "description" : "{{campaign.${name}}}",
    "size" : "6x18_bifold",
    "to" : {
        "name" : "{{${first_name}}} {{${last_name}}}",
        "address_line1" : "{{custom_attribute.${address_line1}}}",
        "address_line2" : "{{custom_attribute.${address_line2}}}",
        "address_city" : "{{custom_attribute.${address_city}}}",
        "address_state" : "{{custom_attribute.${address_state}}}",
        "address_zip" : "{{custom_attribute.${address_zip}}}"
    },
    "from" : "adr_2066448bdef840f1",
    "inside" : "tmpl_8b3b1249ede0406",
    "outside" : "tmpl_d69077c7be7bd09",
    "merge_variables" : {
        "name" : "{{${first_name}}}"
    },
    "metadata" :
        "campaign" : "{{campaign.${name}}}",
        "zip" : "{{custom_attribute.${address_zip}}}"
    },
    "mail_type" : "usps_first_class",
    "billing_group_id" : ""
}
"merge_variables" : {
    "f_name" : "{{${first_name}}}"
}
"file" : "tmpl_3v234vl23hj5v"
"file" : "https://braze-images.com/appboy/communication/assets/image_assets/images/25660da30cdc28a314/original.jpg?1637006884"
let brazecall = {
 "attributes": [
   {
     "external_id": payload.body.metadata.external_id,
     "_update_existing_only": true
   }
 ],
 "events": [
   {
     "external_id": payload.body.metadata.external_id,
     "_update_existing_only": true,
     "name": "Letter Viewed",
     "campaign": payload.body.description,
     "time": new Date().toISOString(),
     "properties": {
       "property_1": payload.event_type
     }
   }
 ]
};
{
  "attributes": [
    {
      "external_id": "123456789",
      "_update_existing_only": true
    }
  ],
  "events": [
    {
      "external_id": "123456789",
      "_update_existing_only": true,
      "name": "Letter Viewed",
      "campaign": "Lob Braze Webhook Demo",
      "time": "2023-10-05T23:14:58.073Z",
      "properties": {
        "property_1": {
          "enabled_for_test": true,
          "id": "letter.viewed",
          "object": "event_type",
          "resource": "letters"
        }
      }
    }
  ]
}
Success. Output is a valid /users/track request.
Details:
{
  "attributes_validated": 1,
  "events_validated": 1,
  "message": "success"
}
Braze integration documentation
Import CSV
API call
Braze Documentation
conditional logic
here
Media Library
Braze’s documentation on utilizing Data Transformations
Lob Webhook
Liquid documentation
Idempotent requests
Lob API docs: Rate Limiting
Braze user guide: Rate limiting
Screen_Shot_2022-03-28_at_2.57.49_PM.png

Tracking your mail

One of the most powerful advantages of using Lob is that you can have visibility of any individual mail piece as it moves across the entire print production and delivery process. Gain complete transparency into your mail’s journey from print production to final delivery, ensuring you stay informed every step of the way.

Lob will surface notable actions or events within the Lob architecture. Examples include when a mailpiece is created, fails the rendering process, or when a Lob QR code is scanned.

Additionally, each U.S. mail piece is printed with a unique Intelligent Mail Barcode (IMb), similar to a package tracking number. For USPS First or Standard Class mail, Lob processes data from our commercial printers and mail partners, along with USPS scan events, to surface tracking events as your mail moves through the delivery process.

You can access this data in the Lob dashboard at the individual mailpiece, campaign, or aggregate level. You can also subscribe to webhooks in the Lob Dashboard or via the API to get proactive notifications. See the full list of (including tracking events) you can access in our API documentation.

Tracking events

Note that any mail pieces sent in the Test Environment will not receive tracking events.

Tracking events are a subset of all Events; below is a list of each tracking event label and description, as recorded by Lob:

  • Received - The API call for the mail piece was made and received by Lob. (Event will be displayed in dashboard at individual mailpiece level; no webhook available.)

  • In production - Mail piece instructions were dispatched to Lob's printer network and the request is now being printed/cut, soon to be handed off to the USPS for fulfillment. (Event will be displayed in dashboard at individual mailpiece level; no webhook available.)

  • Mailed - Confirmation that mail has been handed off to Lob's mail carrying partner from our printers.

    • This feature exclusive to Enterprise edition customers. For non-Enterprise customers, the Mailed event in your dashboard view of tracking events will be greyed out in the tracking event stepper.

    • The ability to accurately surface the "Mailed" tracking event is a unique feature to Lob, and can be utilized to monitor Lob’s SLA adherence as well as provide auditable proof for time of mailing.

    • The “Mailed” tracking event appears at earliest two business days after sending your Lob API request. In some instances, it can take longer for this “Mailed” event to become visible, but when surfaced, it will accurately reflect the actual date of mail handoff from our printers.

  • In Transit - The mail piece is being processed at the USPS entry/origin facility or commingler.

  • In Local Area - The mail piece is being processed at the USPS destination facility.

  • International Exit - The mail piece has been processed to ship to a destination abroad. This is typically the last scan a US-originated international mail piece will receive from the USPS. Note this scan is historically inconsistent, but if it occurs, Lob will surface.

  • Processed for Delivery - The mail piece has been greenlit for delivery at the recipient's nearest USPS postal facility. The mail piece should reach the mailbox within 1 business day of this tracking event.

  • Delivered - The mail piece has been delivered to the recipient’s address. This event is generated when the mail carrier's GPS unit leaves the delivery area. USPS does not guarantee every event for each mail piece, thus Processed for Delivery is more reliable.

  • Re-routed - The mail piece is re-routed due to recipient change of address, address errors, or USPS relabeling of barcode/ID tag area.

  • Returned to Sender (RTS) - The mail piece is being returned to sender due to barcode, ID tag area, or address errors.

Scanned events

Following production, all mail pieces will be handed off from our printers to USPS and will enter the USPS mail stream. All subsequent events are subject to USPS accurately scanning the mail piece as it travels to its destination in the mail stream, hence called "scanned" events.

For tracking events from USPS (i.e., all events listed after the "Mailed" event), expect to start seeing your first tracking event appear within:

  • 3 business days after your Send Date for First Class Mail

  • 4-5 business days after your Send Date for Standard Class Mail

In addition to accessing this mail tracking data via our API or Dashboard, you can receive real-time notifications by using webhooks.

Missing or out-of-sequence scans

All USPS scan events are dependent on the local postal offices and how they process/sort mail. Similarly, the delivery of those mail pieces is also under the full control of the local post office.

We do not have added visibility or control over the actual mail pieces once they are handed off to USPS—we can only monitor their progress by surfacing mail tracking events that are visible on your dashboard.

Lob does not have any control over the accuracy of scans, nor can Lob go back and reconcile scan events as it is purely a USPS-owned process.

While scans are not guaranteed by USPS, we do see scans on over 99% of our mailings. If more than 5 business days have passed and you don't have any tracking events, send an email to [email protected] and our team will be able to confirm whether the mail piece has been mailed.

Tracking for special mail types

Reminder that mail pieces sent in the Test Environment will not receive a tracking events.

Metered Mail

The minimum volume to qualify for Presort mail is 200 pieces (or 50 lbs) of Marketing Mail or 500 pieces of First Class mail, which is a USPS requirement. Some mail is sent out metered if that day's volume from one of Lob’s production partners does not meet the minimum volume per mail type, as required by USPS. This means the mail pieces are not able to be batched with the other mail pieces and have to be mailed separately.

Historically these mailpieces have been difficult to track without a batch ID. But beginning July 12, 2023, the “Mailed” event for Metered mail is available in our webhooks for tracking events and included in mail counts within the Mail Analytics Dashboard.

Please note we would not expect to populate any other tracking events for Metered mail.

PO Box Mail

While we typically see all scans for the majority of our mailings, it is not unusual to see mail sent to a PO box with tracking that ends at the “In Local Area” scan event, even though the recipient has physically received the piece.

“In Local Area” scan indicates receipt and processing by the post office most local to the final delivery point. Typically the next scan would be “Processed for Delivery,” to indicate a mailpiece has been cleared for a final delivery attempt (and is likely loaded directly onto the mail delivery vehicle). However, a PO box does not need to be loaded onto a vehicle for the final delivery, as the PO box itself is located at the post office already. In this case, postal workers can simply hand-deliver the mailpiece to its final destination—so there will be no "Processed for Delivery" scan.

Unique ZIP codes

This is a ZIP Code that belongs to some entity (for example, a university, a government agency, etc) which is responsible for sorting its own mail. These ZIP codes are classified by the USPS as a “Unique” ZIP Code (code U1), and we often do not see delivery scan events for these ZIP codes. This is because the entity itself is responsible for the final stage of delivery of their mail, rather than USPS.

Registered & Certified Mail

Letters sent as Registered do not receive the same scan events as regular First or Standard Class mail. Registered Mail will instead receive a carrier tracking number and link, which is an add-on that will be available three (3) business days following the mailer’s send_date. This tracking number can be used to track the mailer via the carrier’s website.

If you decide to send Certified Mail through Lob, you will receive a carrier tracking number and tracking link retrievable via your Lob dashboard, which can be used to track the mail piece via USPS’s website. You can also track the mail via scan events within your Lob dashboard. Sometimes certified mail tracking will be available immediately, or as late as 3 days after sending the mail piece.

See here for more details on tracking for Certified or Registered Mail.

Return envelope tracking for Reply Mail

Enterprise edition customers can now access return envelope tracking for USPS Courtesy Reply Mail (for letters only). Once the returned mail piece enters the mailstream, the customer can start receiving notifications to tracking events via our webhooks.

For more information, see how to enable return envelope tracking, and how to view return envelope tracking events via webhooks.

How to confirm USPS received your mail

Using webhooks, a user can confirm USPS possession for the majority of First Class/Standard mail pieces. (If proof of USPS possession is crucial to your organization, Lob offers Registered and Certified Mail.)

  1. The following mailpiece webhooks indicate USPS possession:

  • xxx.delivered

  • xxx.in_local_area

  • xxx.in_transit

  • xxx.processed_for_delivery

  • xxx.re-routed

  • xxx.returned_to_sender

Also applies to self-mailers
  1. USPS may not consistently scan all mail pieces at every stage; Lob is only able to capture and surface scans received from USPS itself. (Lob sees USPS scans for the majority of mail pieces; that is, a very small percentage of mail pieces receive no scans at all.)

  2. ​​Lob will send webhook events as soon as they become available. However, users should not assume all webhooks will be sent in real-time, and may occasionally experience some delays; they may also be received out of order.

  3. That said, receipt of any of the events noted above confirms that a mail piece is in USPS possession.

  • The inverse is not necessarily true; i.e., NOT receiving any of these events is not a guarantee that the piece is NOT in the mainstream.

  1. Although events may not be sent in real-time, for tracking events you can get the USPS timestamp of the event under tracking_events[].time.

  • The earliest time stamp of any of these events would equate to the earliest (recorded) possession by USPS.

See our technical use case ingesting tracking events with webhooks for a deep dive on how to ingest events for a specific mail piece, run a monthly data pull from Lob's system for mail pieces that don't have a certain event, or get real-time updates as your mail piece goes through the mail stream.

How to know if your mail was delivered

For First and Standard Class mailings, "Delivered" is typically the last event that USPS provides. When your mail piece receives this event, this means that a USPS courier has delivered the mail piece.

The "Delivered" event is generated when the mail carrier's GPS unit leaves the delivery area; it is not guaranteed by the USPS. If a “Delivered” event hasn’t yet surfaced for your mail piece, but you have received a “Processed for Delivery” scan, this indicates that USPS is expected to attempt delivery within one business day.

For international mailings originating in the US, see International Mail for details on tracking mail pieces abroad.

Delivery timelines & delayed pieces

Delivery times for mail will vary depending on mail class and destination:

  • First Class Mail: US domestic mail delivery typically takes 5-7 business days, and international mailings take an additional 7-9 business days.

  • Standard Class Mail: Delivery times can take anywhere from 7-21 business days. USPS does not provide delivery time guarantees for Standard Mail.

Delivery times quoted are estimates; Lob uses USPS as our primary carrier and USPS experiences delays from time to time. To see the most up-to-date status of your mailing, check the tracking information of your particular mailing.

Re-routed mail

If you receive a "Re-routed" scan, this indicates that USPS attempted delivery at the original address, but re-routed it because your recipient no longer resides at that address. In these cases, USPS will attempt to deliver to your recipient at their new address (if they filed a National Change of Address).

Undeliverable mail / Return to Sender (RTS)

If you received a "Return to Sender (RTS)" event scan, this indicates that USPS attempted delivery of the mail piece at the original address, was unsuccessful, and the mail is being re-routed back to the return address after being deemed undeliverable or misdeliverable as originally addressed.

This results in a yellow sticker being affixed to the mailing by USPS for tracking purposes called a NIXIE label. The NIXIE label is affixed by the USPS if they are unable to complete delivery. (In rare cases, RTS without a NIXIE label is possible due to either the neglect of the USPS agent, or because the recipient had chosen to return it themselves.)

Example of a USPS Return to Sender sticker (NIXIE label)
Common RTS reasoning codes on NIXIE label
  • Attempted Not Known (ANK): Delivery attempted, addressee not known at place of address

  • Deceased (DEC): Used only when the addressee is deceased and mail is not properly deliverable to another person

  • In Dispute (DIS): Cannot be determined which disputing party has better right to mail

  • Insufficient Address (IA): Necessary address details are omitted and the correct address not known

  • Illegible (ILL): Address not readable

  • No Mail Receptacle (NMR): Addressee failed to provide a receptacle for receipt of mail

  • No Such Number (NSN): Addressed to nonexistent number and correct number not known

  • No Such Street (NSS): Addressed to nonexistent street and correct street not known

  • Refused (REF): Addressee refused to accept mail or pay postage charges

  • Unclaimed (UNC): Addressee abandoned or failed to call for mail

  • Not Deliverable As Addressed - Unable to Forward (UTF): Mail undeliverable at the address given; no change-of-address order on file; forwarding order expired

  • Vacant (VAC): House, apartment, office, or building not occupied

After the RTS event scan, the mail piece is then treated as a new letter that is going to a new destination and will be tracked to the reroute location. This may be why the same mail piece may receive new scans after receiving the RTS event.

A multi-delivery attempt is translated into scans in “Delivery Attempt 1 and 2” below, compared to a standard delivery where the mail piece makes it to its final destination in a single attempt (Col 1):

Standard Delivery Process

Delivery Attempt 1

Re-Routed Attempt 2

Received

Received

-

In Production

In Production

-

Mailed

Mailed

-

In Transit

In Transit

-

Processed for Delivery

Return to Sender -->

In Transit [+Yellow Sticker]

Delivered

-

Processed for Delivery

-

Delivered

USPS may not consistently scan all mail pieces at every stage; Lob is only able to capture and surface scans received from USPS itself.

Because RTS scans are not necessarily an 'end-state scan', you should not track whether it was the last scan received when trying to calculate the percentage of RTS mail, as it may have been marked as such and still received additional scan events. Instead, you should try calculating the percentage based on whether the RTS scan event was ever received, regardless of its place in the sequence of scan events.

Furthermore, we recommend you confirm the updated address with the intended recipient and submitting a new request to have it printed and mailed. There is currently no way to re-initiate an existing request in Lob.

Visibility of tracking events

You can export all tracking events data into a CSV file; see more details on exporting mail data here.

Where can I see mail piece tracking?

You can see tracking events under the detailed pages within Print & Mail and/or Campaigns in the dashboard.

Additionally, under Mail Analytics (accessed via the left navigation bar in the dashboard), the Tracking Events tab displays a visual breakdown of all tracking events applicable to the mail pieces within the filter parameters.

How can I get notified of events?

Real-time progress of mail pieces can be accessed by using webhooks, an easy way to get notifications on events happening asynchronously on Lob's side. Once webhooks are successfully set up on the dashboard, Lob will "push" you notifications when mail pieces are created, when they receive USPS scans such as "In Local Area" or "Processed for Delivery", or any other event you subscribe to.

Enterprise edition customers can also access return envelope tracking for USPS Courtesy Reply Mail (for letters only). Once the returned mailpiece enters the mailstream, the customer can start receiving notifications to tracking events via our webhooks.

The full list of event types available for subscription can be found here.

What should I do if my mail piece does not receive a tracking event?

If your mail piece doesn’t have a tracking event, first check to see how much time has elapsed between your mail piece Send Date and the current date. Typically, it’ll take 3 business days (for First Class Mail), or 4-5 business days (for Standard Class Mail) from the time of your Send Date for USPS tracking events to appear.

If more than 5 business days have elapsed since your Send Date and you don’t have any tracking events, send an email to [email protected]. Our team will be able to confirm whether the mail piece has been mailed.

Note: If it has been more than 30 days, Lob will not have access to the API logs which track mailpiece tracking events, but you should be able to see the date when the mail piece was scanned by clicking on 'View details' in your dashboard.

Screen_Shot_2022-03-28_at_3.00.36_PM.png

Dynamic personalization

Personalize your creatives with HTML

Personalized messaging is a core component of all modern marketing channels and a key driver of user engagement. Lob brings the power of personalization at scale to direct mail, enabling you to improve the performance of this key channel and improve your return on investment.

Lob makes this possible by supporting HTML creatives with merge variables. This empowers you to leverage your customer data to individually cater your messaging to each recipient in a way that will maximize the impact of a mail piece. You can now design your direct mail similar to how you would an email or other digital channels, leveraging dynamic personalization to drive conversions.

Some best practices that leverage dynamic personalization include:

  • Capture 1-to-1 attribution: Use dynamic landing pages, QR codes, and unique URLs/promo codes to understand audience response at the individual level

  • Repurpose digital campaign assets: Orchestrate an omnichannel campaign with cohesive messaging and branding through online and offline channels

  • Experimentation: Easily execute A/B and multivariate tests by combining audience targeting with dynamic creation of multiple creative permutations. Test the efficacy of different images, layouts, CTA copy, promotions, and more.

  • Integrate into the customer journey: Automatically send mail at any point in the customer journey by creating automated direct mail triggers at key actions and milestones

Below is an overview of how to leverage personalization within Lob.

HTML templates

Lob's HTML Templates support the inclusion of dynamic fields, called merge variables‍, which can be populated individually for each mail piece. These merge variables can be mapped to attribute values in your customer records or audience segments. For example, the value for your customer attribute "First Name" can be passed into a merge variable field in your creative called {{Name}} to dynamically include each recipient's own name in the content of the mail piece they receive. You can create and name your own merge variables within your template, giving you the flexibility to personalize nearly any aspect of your creative.

To utilize an HTML within the Campaigns builder in the dashboard, you must first create a Live template in Lob.

Creating a template

You can create, view, edit, and manage your HTML templates for any mail format by saving them within Lob's system. You can create a template by sending HTML directly to Lob's Templates API endpoint or HTML templates can be created within your Lob dashboard underHTML Templates.

  • While it is optional, we highly recommend adding a description so you can easily identify your template within Lob.

  • In the dashboard, you must indicate the Mail Format and Size order to save a template.

  • Both the description and your HTML can be edited after saving.

Test vs Live

  • Like all Lob mail pieces, you can create HTML templates in both your Test and Live Environments.

  • Templates created in the Test Environment will only be available for mail pieces created in the Test Environment, while templates created in the Live Environment will only be available for mail pieces created in the Live Environment.

  • While you can move templates from one environment to the other, make sure you are working in the correct environment (don't move a Live template!).

  • In Live mode, you can only have as many templates as allotted in your current Print & Mail edition. There is no limit in Test mode.

To utilize an HTML template within the Campaigns builder in the dashboard, you must first create a Live template in Lob.

Template design

As for the HTML design, you can start off with a pre-designed template from our gallery (or see these examples in GitHub). Our templates are compatible with merge variables‍, which enable dynamic content.

  • If you have limited access to designers and developers, consider using our Figma-to-Lob plugin. This plugin will take any creative designed in Figma and convert it into a HTML template with merge variables.

  • When designing content with HTML, use inline styles or an internal stylesheet. Do not use an external stylesheet.

  • If you are linking to images, please ensure that they are at least 300 dpi (but there is no need to go higher than 300 dpi). Because the content is only being designed for a single size, we recommend using absolute positioning (code snippet shown below).

All URLs must be accessible. For example, broken links, missing files, and incorrect permissions will all cause mail pieces to fail before they are sent to print. See here if you are experiencing rendering errors.

body {
  width: 6.25in;
  height: 4.25in;
  margin: 0;
  padding: 0;
  background-image: url(https://s3-us-west-2.amazonaws.com/public.lob.com/assets/beach.jpg);
  background-size: 6.25in 4.25in;
  background-repeat: no-repeat;
}


#safe-area {
  position: absolute;
  width: 5.875in;
  height: 3.875in;
  left: 0.1875in;
  top: 0.1875in;
  background-color: rgba(255,255,255,0.5);
}

Viewing a template

Once you've created an HTML template, you'll be able to view it on your dashboard under HTML Templates. Clicking any template will bring you to the Template Details page.

From the menu, you can edit the template, view a large print preview of the template, or delete the template (from the meatball menu).

Also the this page you can:

  • See a small preview of the template

  • View the Template ID (completely unique to this particular template)

  • View the Version ID

  • View the template's metadata

  • View the HTML for the template

  • See previous versions of the template

Print Preview

When you select View Print Preview, a pop-up will display and auto-populate any merge variables‍ we find in your template, which are dictated by {{double_curly_braces}}. After you've filled out these fields (sample data is fine), you'll be able to preview your template as a PDF, which will open in a new tab. You may need to unblock pop-ups in the browser of your choice.

A JSON editor will be required if you need to use loops, conditionals, or objects. We will not auto-populate any merge variables‍ we find in your template when using the JSON editor.

You won't be able to see any specific proofing elements such as address information, barcodes, or cropping which occur when actually creating a mail piece. The best way to test these elements of your template will be to send it to yourself as a live mail piece.

Editing a template

You can edit a template's description as well as its HTML from the Dashboard as well. When you edit a template's HTML, a new published version of that template will be created. Those changes will go into effect immediately. Any subsequent mail piece integration referencing that template ID will reflect the updated changes as soon as they are submitted.

If a template is no longer of use to you, you can delete it from Lob. Once you delete a template, it will no longer be usable for any postcard, self-mailer, letter, or check requests. Before deleting, ensure that the template is not being actively used in any integrations.

Template versions

The published version of a template will be the first version featured on the page. This is the version that will be used when that template is referenced in a mail piece request. Prior versions of the template can be viewed within the page, along with a unique ID and browser preview for each. This can be helpful for reconciling edits made in the past, or copying a prior template and saving it again in order to revert to it.

Using HTML and merge variables

Merge variables make it easy to personalize your mail pieces with whatever custom information you'd like to include. Common use cases for merge variables include:

  • Personalized customer information (name, city, etc)

  • Date

  • Invoice line items

  • Custom copy or images

  • CTAs (URLs, coupon code, phone numbers)

Usage

Merge variables only work if you use HTML to generate your mail piece. To make use of a merge variable, insert {{tag_name}} (with double curly braces) into the HTML template. You can define the merge variable name, and you can enter it into any section of your HTML.

<html style="padding: 1in; font-size: {{fontsize}}; color: {{color}}">
  <p>Hi {{name}}, how are you?</p>
  <img src="{{img}}" style="width: 1in">
</html>

If the HTML above were used with the information below:

name
fontsize
color
img

Harry

20px

red

Ami

30px

green

Then the final two postcards would be rendered like so:

Use this feature to your advantage to create dynamic creatives for your recipients, without having to generate PDFs on your side.

All URLs must be accessible. For example, broken links, missing files, and incorrect permissions will all cause mail pieces to fail before they are sent to print. See here if you are experiencing rendering errors.

Advanced functions

Objects, conditionals, loops

You have the ability to access merge variables at any depth within your JSON. For instance, you can have an object created with multiple attributes:

{
  "user": {
    "name": "Ami",
    "location": "San Francisco"
  }
}

To access these within your template you can do the following:

Name is: {{user.name}}
Location is: {{user.location}}

This renders the following template:

Name is: Ami
Location is: San Francisco

You can also create a "section" which will change the context of the variables you are accessing. For instance:

{{#user}}
  Name is: {{name}}
  Location is: {{location}}
{{/user}}

This renders the same HTML as above, since you changed the context to the "user" temporarily. This is done by the {{#user}} and {{/user}} syntax. Everything inside that "section" tries to access a property on the "user" object.

Conditionals allow you to conditionally render content in a mail piece. An example use case could be including additional text for any user who has purchased over 1,000 products. To do that would require the following:

Merge variables:

{
  "bought_a_lot": true
}

Template:

<html>
{{#bought_a_lot}}
Thank you for being a loyal customer!
{{/bought_a_lot}}
</html>

This renders:

Thank you for being a loyal customer!

If you want to render content if a condition does not pass, simply use ^: {{^condition}}{{/condition}}.

For example:

Merge variables:

{
  "bought_a_lot": false
}

Template:

<html>
{{^bought_a_lot}}
Buy more products!
{{/bought_a_lot}}
</html>
Buy more products!

Loops allow you to display content multiple times for multiple objects. The following is an example of how to use loops:

Merge variables:

{
  "users": [{"name": "Nathan"}, {"name": "Ami"}]
}

Template:

<html>
  List of top users:
  <ul>
  {{#users}}
    <li>{{name}}</li>
  {{/users}}
  </ul>
</html>

This renders:

<html>
  List of top users:
  <ul>
    <li>Nathan</li>
    <li>Ami</li>
  </ul>
</html>

Javascript usage

While JavaScript can unlock all kinds of new functionality in your Lob templates, it comes with the important caveat that not all client-side JavaScript can be rendered by Lob. Additionally, it is possible that any included JavaScript will not fully execute prior to PDF generation. You are thus strongly encouraged to test all JavaScript prior to utilizing in live mail templates. Test your entire HTML template containing the JavaScript (rather than just the JavaScript snippet itself) using your Test API key before using the template in any live mail API requests.

For even more flexibility we recommend using the Handlebars templating engine.

Merge variable strictness

Lob offers a merge variable strictness setting that dictates how we treat merge variables in your HTML templates, and whether to send out any mail pieces that are missing their merge variable input values. This is a setting that can be set at the account or campaign-level, and is critical to use when handling dynamic creatives. See Merge variable strictness settings for more information.

Using HTML and fonts

You can incorporate any font into your Lob HTML Templates by using one of the options below. Links to fonts must be accessible by Lob or they will not render successfully.

Using Google web fonts

Using Google Web Fonts is a simple way to import and use a wide variety of fonts within your Lob HTML without having to download or upload any assets.

Once you've identified your font within Google, just include a link to the font in the <head></head> tag of your HTML:

<head>
  <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
</head>

Then reference the font in your <style></style> tag or inline:

body {
  font-family: 'Roboto';
}

Using custom fonts

You are also free to use any custom font that is accessibly hosted. Upload your font files to a performant file hosting platform (such as Amazon S3) and use CSS @font-face declaration to load them into your design.

For example, in the <style></style> tag of your HTML, add the rule like so:

@font-face {
  font-family: 'My Font Name';
  font-style: normal;
  src: url('https://link-to-your-font/my_font_name.ttf') format('truetype');
}

And then reference the font in your <style></style> tag or inline:

body {
  font-family: 'My Font Name';
}

Page breaks in HTML

When creating HTML letters within Lob, you may find it necessary to create page breaks in order to split up your content by page. This is easy to do using CSS's page-break-after property.

For example, create a page class in your HTML and apply these styles:

.page {
  page-break-after: always;
  position: relative;
  width: 8.5in;
  height: 11in;
}

And then, divide the pages of content in your HTML by this page class:

<div class="page">
  Page 1
</div>
<div class="page">
  Page 2
</div>

Template storage

Templates can be viewed in the Lob dashboard, where they can be created, managed, and stored.

The total number of templates available is dependent on the Platform Edition; if you need more HTML templates than what is available in your current edition of Lob, we encourage you to upgrade to a higher tier edition. You may also delete any HTML templates you no longer need to make room for new ones.

General template best practices

Although anyone versed in HTML/CSS will find the process of creating templates familiar, we recommend these practices.

If you need a place to start, we highly recommend working off an example from our Template Gallery.

See it before you ink it!

For the closest visual analog to our own rendering technology, we suggest viewing your template in the Safari browser. This also means that usage of CSS stylings unsupported by the Webkit (Safari) engine may not render correctly. We recommend working at a 300dpi resolution, any higher resolution would be lost once the mail piece is printed.

Be sure to make use of the "Print Preview" option with your HTML templates, whether in Live or in Test mode, to get a basic digital proof of your mail piece. (Keep in mind that templates created in the Test Environment will need to be recreated in the Live Environment before they can be used with Live mail pieces.)

In the Campaigns builder, most mail formats will also display a Creative Proof; this will display merge variables, address block, Lob carbon-neutral logo, and indicia, plus return address and QR codes if included.

Where possible, we always recommend sending yourself a printed mailpiece.

RGB vs CMYK

As it stands today, our rendering engine does not support the CMYK color profile in HTML templates, though we are slated to resolve this in the near future. As such, colors provided in HTML templates will need to undergo a transition from RGB to CMYK which may affect the hue and saturation. This is true even when assets are provided in CMYK. We advise our customers keep this in mind when requesting to print brand logos or skin tones. If preferred, we support CMYK for static (PDF) formats.

Please avoid the following:

For a successful template creation experience, abstain from the following:

  • using the object-set property

  • images img with opacity properties

  • images using background-image, border-radius, and border properties in unison

  • gradients using transparency

  • background-size: contain

    • in these cases, also include background-repeat: no-repeat;

  • JPEG images with EXIF orientations set to non-zero values; workarounds include:

    • using a JPEG header manipulation utility such as jhead to correct the rotation value

      • Example: jhead -autorot myfile.jpg

    • using a PNG instead

  • CSS references that are not utilized in the final HTML template

Using a template in Campaigns

In the Campaigns tool, Step 3: Choose creative, you will select an HTML template, and then choose from the drop down options. An HTML template must exist in the Live environment for the Campaigns tool to reference.

Using a template in a mail creation API request

To test and use your HTML template, you'll need to create a mail piece. For parameter details, see the respective documentation for each single endpoint in our API documentation.

For this example, we'll create a postcard. Don't forget to add merge variables‍ to your HTML template for any dynamic fields. Also, remember that the published version of the template is the version that will be used for the request.

curl https://api.lob.com/v1/postcards \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Postcard job" \
  -d "to=adr_78c304d54912c502" \
  -d "from=adr_61a0865c8c573139" \
  --data-urlencode "front=tmpl_d2ef51761865901" \
  --data-urlencode "back=tmpl_7c9c41753dfea20" \
  -d "merge_variables[name]=Harry" \
  -d "merge_variables[code]=5dks92"

After sending this request, a successful response will include a signed URL to a digital copy of the created postcard. You will also be able to view this in the Lob dashboard, under Print & Mail then the corresponding mail format (in this case, Postcards).

For any mail piece that use templates, the Template IDs and Version IDs used will be retrievable from the API (see the respective documentation for each endpoint), as well as viewable on the dashboard under HTML Templates listing and each Template Details page.

Using webhooks

Overview

Webhooks are a way for one service to send real-time updates or data to another service automatically, without any need for the user to check for new information manually. They work like a notification system, instantly alerting the receiving system when something happens in the sending system.

Webhooks are an easy way to get proactive alerts or notifications on events that are happening within Lob, including the tracking events we receive from the USPS. (.) Some common use cases for integrating webhooks are:

  • Receiving notification of improperly submitted mailpieces that fail to be rendered by Lob.

  • Downloading PDF previews or thumbnails automatically once they are rendered

  • Sending end-users notifications about mail traveling through the postal stream as a part of an omnichannel approach

  • Triggering specific downstream workflows and actions based on the final receipt confirmation of mail with the "Delivered" event

  • Receiving notifications about erroneous scan events, such as "Re-Routed" or "Returned to Sender"

  • Internal logging and reconciliation

When an occurs within our architecture and you have a webhook subscribed to that event type in that environment (Test vs. Live), we will attempt to make a POST request with the to the URL provided.

Subscribing to a webhook in the Lob dashboard

  1. Select Webhooks from the left navigation bar.

  2. Choose Test or Live environment and click 'Create.'

In Live mode, you can only have as many non-deleted webhooks as allotted in your current . There is no limit in Test mode.

  1. Add the webhook name in the ‘Description’ field.

  2. Indicate the URL of the web server that will .

  3. Edit your as applicable.

  4. Select your event type. (See for a full list of all available event types.)

  • For example, if you are setting up a webhook to be notified any time a postcard gets re-routed in the delivery process, then select the “postcard.re-routed” event type from the Postcards section.

  1. Save the webhook by clicking on the 'Create' button.

Once created you can click on any webhook in your menu to access Webhook Details page to view summary information and webhook attempts. Here you can also replay events, debug, edit, or delete the webhook.

Receiving a webhook

To receive webhooks from Lob, you need to create another endpoint on your web server that will accept a POST request with a content type of application/json. Keep in mind that it will need to be accessible by Lob, so if there's anything that could prevent Lob from access, it should be disabled for this endpoint. See our recommendations on below.

To confirm delivery of the webhook, Lob expects a 2xx status code returned in a timely manner. We will consider any other status code (or lack of status code) to be erroneous and attempt to retry the delivery. If your webhook endpoint has any additional complex logic to perform, we recommend immediately returning a 2xx to let Lob know that you do not want to receive this event again, and then performing that logic afterwards. This should aid in preventing unwanted retry attempts caused by unexpected network timeouts.

Any other information sent back to Lob in the response will be captured and stored (regardless of status code) for you to view on your Dashboard, though we won't perform any processing on it. Therefore, we recommend responding with any information that you may find useful for debugging purposes. While you can return anything (including HTML), we've found it most helpful to return a concise JSON object with anything that could be relevant.

Lob will send webhook events as soon as they become available. However, customers should not assume all webhooks will be sent in real-time, and may occasionally experience some delays.

For example when subscribing to the postcard.processed_for_delivery event, you will receive a response with the previous tracking events such as postcard.in_local_area, postcard.in_transit, postcard.mailed.

Although events may not be sent in real-time, for tracking events you can get the USPS timestamp of the event under tracking_events[].time.

Webhooks JSON schema

Our mailpiece creation API responses contain unredacted information about your mailpiece. With each webhook sent for a given mailpiece, Lob redacts fields that could potentially contain Personally Identifiable Information (PII) or Protected Health Information (PHI). Fields that will be redacted include:

For all mail formats:

  • “From” address for all form factors & events

  • “To” address for all form factors & events

  • Mailpiece URLs

  • Metadata

  • Description

  • Merge variables

For Checks only:

  • “Memo” field

  • Everything in the “Bank Account” property (routing, account number, bank name, etc)

To preview what a sample redacted payload will look like, select “Webhooks” from the left-hand navigation menu in the dashboard, then select the “Debugger” button on the Webhook dashboard or individual webhook subscription page.

You can then select the “Event Object” tab at the bottom of the screen to see what information will be redacted.

Below is an example webhook response:

Fields that may contain any sensitive PII/PHI information will be redacted by default. However, you may adjust your redaction settings in your in the Lob dashboard under Account > "Webhooks Payload."

Lob is unable to retrieve any payload information retroactively during the time when this Webhooks Payload account setting is marked "Redacted."

Test vs Live environment

Events are created in both your Test and Live Environment, and webhooks can also be created in both.

  • Webhooks created in the Test Environment will be triggered off events from your Test API Key

Because only exist in the Live Environment, these event types cannot be subscribed to in the Test Environment. If you are looking to debug these types of events, you can trigger a mock event to your server by using our tool.

  • Webhooks created in the Live Environment will be triggered off events from your Live API Key.

Integration tips

When first starting out, we recommend using our . This allows you to trigger a generated event body to your specified URL on command. This should mainly be used to determine JSON structure when integrating. Since the event bodies sent are fake, all IDs and URLs within them are inaccessible and do not map to real resources in your account.

Once you've started local development of the web server that will be handling these requests, we recommend using a tool that provides local tunneling, such as . This allows you to expose your locally running server to the Internet so we can access it without you needing to deploy your application.

Webhook rate limits

If your server or gateway has an associated rate limit, or if you would like to control the speed at which Lob sends you webhooks for any other reason, you can configure the rate limit for each webhook subscription.

To do this, Account Administrators can go to the and either: (1) enter the rate limit when or (2) select an existing webhook subscription to modify the rate limit. Click the “Edit” button on the right-hand side of the screen, and enter your desired rate limit (per 5-second interval) and click “Update.” This change will take effect immediately.

Replaying webhooks

Sometimes, a change or issue in your internal environment may cause a webhook subscription to begin failing. Once the issue is resolved, you can replay failed webhooks easily through the dashboard.

To replay events, account admins can select a webhook subscription on the to modify. Select the “Replay Events” button on the right-hand side of the screen. Enter a start date and click “Replay Events.” All non-2XX events will be queued to replay between the date selected and now.

Retry policy

When webhook attempts executed by Lob do not succeed (e.g. do not receive a 2xx status code, hit a SSL/TLS error, DNS issue, etc), we will continue to try to deliver the same event according to a schedule with an increasing backoff. This policy is meant to give you time to rectify the issue without losing any events.

We will reattempt at the following intervals until we either receive a 2xx status code or all attempts below have been executed:

Attempt #
Time since last attempt
Time since first attempt
Example

After the 8th attempt, we will not attempt to deliver the webhook again. If all of your webhooks for a single subscription fail for 5 consecutive days, the subscription will be disabled.

Disabling policy

If your webhook endpoint does not consistently respond with a 2xx status code, we will automatically disable the webhook and stop sending events to the endpoint. Webhooks are automatically disabled after 5 consecutive days of failures. The “clock” starts after the first failure and a single successful webhook to a given endpoint will reset the clock. You will receive an email notification when the webhook has been disabled.

Disabled webhooks can be re-enabled in the by editing the webhook.

Security

We understand that security is an important concern when granting external access. You need to make sure that Lob is able to reach your endpoint without incurring the risk of accessibility to bad actors, so there are certain features that you can enable on your end to ensure this is possible.

TLS

We enforce HTTPS for all webhook URLs. Securing your endpoint with TLS ensures all data being sent to and from your server is encrypted. Make sure that you're using a fully-chained certificate, or else the request will never make it to your server and the attempt will fail. To make sure they are fully-chained, you should use the and see if the request successfully goes through.

Webhook signatures

Lob webhooks include a signature to allow you to verify their authenticity. Verifying this signature within your webhook endpoints allows you to ensure that the webhooks originate from Lob and not from a third party.

Webhooks include Lob-Signature and Lob-Signature-Timestamp headers. Lob-Signature is generated by computing HMAC-SHA256 on a signature input and a secret. The signature input is generated by concatenating Lob-Signature-Timestamp (as a string), the . character, and the webhook request's JSON payload (as a string). The secret is unique for each webhook and can be found in the details page for the respective webhook in the dashboard.

A static, fixed secret is used for webhooks for requests sent out using the webhook debugger. In these cases, the secret used in generating the signature is the string secret.

When using Lob's webhook debugger and validating the Lob Signature for events sent via the debugger do not use the uniquely generated secret. Instead use the word "secret" as your secret.

The addition of the Lob-Signature-Timestamp in the headers and as the input to HMAC-SHA256 allows you to prevent users from performing replay attacks. In a replay attack, an attacker intercepts webhooks and retransmits them. By verifying that the signature is valid and the timestamp is within some tolerance (we recommend 5 minutes), you can ensure that the request is not an older request being duplicated by an attacker.

In order to verify the Lob-Signature and Lob-Signature-Timestamp headers, follow the steps below.

  1. Step 1: Prepare the signature input Concatenate the Lob-Signature-Timestamp (as a string), the . character, and the raw request body (as a string). Note: any parsing/stringification done to the request body could potentially alter the original string, so it is recommended to always use the raw request body as-is.

  2. Step 2: Generate the expected signature Compute the HMAC with SHA-256 using the webhook secret from the dashboard as the key and the signature input as the message. Convert to a string in base-16, hexidecimal format.

  3. Step 3: Compare signatures Compare the expected signature with the Lob-Signature header. If the strings are equal, then the webhook is valid.

  4. Step 4: [Optional] Check the timestamp If you are concerned about replay-attacks, check that Lob-Signature-Timestamp is not older than your tolerance.

Basic authentication

You can also use Basic Authentication to guard your endpoint from public access. This can be used in addition to or instead of webhook signature verification. For the best level of security, we highly recommend verifying webhook signatures, rather than relying solely on HTTP Basic Authentication.

When creating your webhook, insert the username and password to the URL using the following format: https://username:[email protected]/webhooks. This will be converted on our end to the appropriate Authorization header when we make the request.

CSRF

A common feature that is enabled by default for some frameworks is . This is a valuable security measure to ensure that authenticated users aren't performing actions that aren't intended. However, having it enabled on your webhook endpoint could prevent our events from being processed. Instead of disabling it completely, you should just exempt this endpoint from CSRF validation.

API versions

We will always send events based on the at the time of event creation. If your account is set to an older API version but a request is sent with a , the Event generated will still be based on the API Version on your account at that time. Event objects in the past will not be updated if you upgrade your API Version - only subsequent events will follow the new Version's structure.

Return envelope tracking

For Enterprise edition customers, Lob offers access to return envelope tracking via webhooks for USPS Courtesy Reply Mail.

For enabled, once the envelope enters the mailstream and is scanned by the USPS, the customer can start receiving notifications to mail tracking events, which will be surfaced via webhooks.

The following is a list of mail tracking event labels and descriptions available:

  • Created: Return envelope is first created (should be simultaneous with Letter creation)

  • In transit: Return envelope is being processed at the entry/origin facility

  • In local area: Return envelope is being processed at the destination facility

  • Processed for delivery: Return envelope is greenlit for delivery at the end recipient's nearest postal facility. The mailpiece should reach the mailbox within 1 business day of this tracking event.

  • Re-routed: Return envelope is re-routed due to recipient change of address, address errors, or USPS relabeling of barcode/ID tag area

  • Returned to sender: Return envelope is undeliverable and is being returned to sender due to barcode, ID tag area, or address errors.

Return envelope tracking is currently only accessible via Lob webhooks, and the Event Logs node in the Lob dashboard. Tracking events will appear in the Letters Events portion of the original individual mail piece in the dashboard as soon as they become available, or can be downloaded using the “Export” button that’s located at the top of the Letters section in the dashboard.

View tracking events for return envelopes

Enterprise edition customers can now access for USPS Courtesy Reply Mail (for letters only). Once the returned mail piece enters the mailstream, the customer can start receiving notifications to tracking events via our webhooks.

You can view your return envelope tracking events by setting up your webhooks:

  1. Log into your

  2. Filter to via API Requests > Event Logs tab

  3. Select the tracking event of interest for return envelopes

    1. Click on Filters at the left top

    2. Select Letters under Resources dropdown

    3. Select the event types you'd like to view (starts with letter.return_envelope) and hit Apply

    4. Select a return envelope tracking event to reveal more details about associated mail piece

Letter add-ons

Letter add-ons are features exclusive to our Enterprise tier customers. Upgrade to the appropriate to gain access, or contact our to learn more.

Add-on: Custom Envelopes

Letter envelopes can be customized with branding, artwork, or messaging to communicate vital information to your recipients even before they open the envelope. Lob offers limited customization for some envelopes, including standard #10 outer envelopes (single-windowed) and #9 return envelopes (no window / single-windowed options).

For more details, see .

Add-on: Cards

Paper cards can now be affixed to letters, providing a compelling method to direct customers to special promotions and drive engagement, both online and in-store. Having “faux” cards can serve as a tangible and memorable reminder for any upcoming marketing promotion.

To get started with letters with card affix, check out our or visit our for inspiration.

Card dimensions & design specs

Layout templates

Paper cards can only be affixed horizontally to the top fold of a tri-folded letter, and to the face letter on the first page.

Reference our layout templates on where to place your design elements on the card, and the location of where the card will be affixed to any given letter.

Card specs
  • 2.125” x 3.375”, with 0.125” rounded corners

  • 18-24pt thickness, depending on paper availability

  • Coated 2 sides (gloss varnish) + full bleed

  • Affixing adhesive: medium tack fugitive glue

Card design & guidelines

Artwork can be featured on both sides of the card. In general, any critical design elements or text should be 0.125" away from the final trim line due to movement at press. There are also no color limitations for cards. Other considerations are:

  • Double-check that all images are embedded into your document

  • Ensure all rasterized artwork (images, effects, copy, etc.) is created and saved at or above 300 dpi

  • Thin, small fonts with over 3 colors may fill in slightly or appear “fuzzy”

  • Line weights of 0.5 pt or more assure optimum print results

  • Any barcodes/QR codes provided need to be print-ready

  • CMYK document

Refer to our for more details on image prepping.

Card ordering

Cards must be created, ordered, and printed, and available in your inventory before they can be utilized.

Upload your front and back designs to create a new card, then order inventory for your card. Cards can be purchased as a one-off order or through auto-reordering.

  • Allow an estimated 20 business days for cards to be available for use in your Lob dashboard.

  • The minimum order quantity is 10,000 cards per artwork design submitted.

  • Spoilage is an industry norm that occurs during print set-up and processing. Based on the industry average, we recommend adding 2-3% to account for spoilage.

Order cards via the Lob dashboard
  • Go to the in the Lob dashboard and hit the Create button

  • Upload a front and back design, and hit Create

  • Once card details show, select the Order button at the bottom

  • Add the desired number of cards and hit Order

Order cards via the Cards API

Send a request to the /v1/cards with the following fields:

  • Description (Required, string): A name to identify your card

  • Front (Required, string): A locally hosted PDF or hosted PDF URL for the front card artwork

  • Back (Optional, string): A locally hosted PDF or hosted PDF URL for the back card artwork

Send a request to the /v1/cards/{id}/orders with the following field:

  • Quantity (Required, number): Number of cards you would like to order

Order & inventory management

See for letter add-ons

Timing and delivery is dependent on order size and complexity, and may be additionally delayed by forces outside of Lob's control (e.g. USPS delays, printer site shutdowns due to Covid, paper shortages, extreme weather events).

Affixing cards to letters

Once cards are ordered, they cannot be sent with letters until your Lob dashboard indicates they are fully stocked and available in your inventory. An email will notify you once your cards are in stock and are ready to be sent with letter campaigns.

The minimum send quantity is 5,000 cards per letter campaign. If a letter campaign is created with a specified card ID that is not in stock, the request will be rejected. Affixing charges will be billed with each Letter API call made, which is separate from the initial card order.

Special considerations when sending card-affixed letters:

  • Letters with card affix are limited to a single sheet at max (can be double-sided)

  • Cards can only be affixed horizontally to the top fold of a tri-folded letter, and to the face letter on the first page

  • Card-affixed letters will be sent in a standard #10 double-windowed envelope

  • Card-affixed letters cannot be sent with custom envelopes or buckslips at this time

  • Card-affixed letters cannot be used with Certified or Registered Mail at this time

Affix cards via the Campaigns dashboard

In “Configure Settings” Step 1 of the Letter creation flow, choose “Card” as your add-on

In “Choose Creative” Step 3 of your Campaign, select the card design that you’d like to use in your Letter campaign.

  • You cannot send cards if you have an insufficient amount in your inventory, as your campaign request will be rejected

  • You cannot pair cards with other letter add-ons at this time

Affix cards via the Campaigns API

Adding cards to letters can be done via the :

  • When loading your creative assets, set the details[cards][0] parameter in your POST call to https://api.lob.com/v1/creatives to the desired card_id. The cards parameter is an array which accepts a single card_id.

  • In the future, we may begin accepting multiple card_ids, hence the array data type.

Additionally, you can find all cards in your account by sending a GET call to https://api.lob.com/v1/cards

Affix cards via the Letters API

Affixing cards to letters can be done via the , similar to Custom Envelopes

  • Set the cards parameter in your POST call to https://api.lob.com/v1/letters to the desired card ID, which is found in your Lob dashboard

  • Additionally, you can find all cards in your account by sending a GET call to https://api.lob.com/v1/cards

When using the Letters API single endpoint (https://api.lob.com/v1/letters), cards must be sent in groups of at least 5,000 card-affix letter API requests during any 24-hour print-day period from 10AM PT to 10AM PT. If you do not, you may incur setup costs of $250/day on your monthly usage invoice. Reach out to your dedicated Customer Success Manager if you have questions.

Card affix offering & variations

Currently we do provide the following card affix offering:

  • Cards affixed to letters (one sheet total, front-side only)

  • Static, non-personalized artwork designs for paper cards

  • Horizontal card orientation in a single size

  • Cards affixed to the top fold of a trifold letter towards the right

  • Letters sent in standard #10 outer envelopes

We do not support the following offerings:

  • Cards affixed to any other mail format (e.g. self-mailers)

  • Cards affixed to letters that totals more than a single page, or on the back-side

  • Dynamic, personalized artwork designs that are unique to the recipient

  • Plastic cards (e.g. credit or loyalty cards)

  • Vertical card orientation or different card sizes

  • Cards affixed to any desired location on a letter

  • Letters sent in customized #10 outer envelopes

  • Card affix for Registered or Certified letters

Add-on: Buckslips

Buckslips are small mail inserts that can be sent with letters to improve your ROI on marketing campaigns. These attention-grabbers can add pops of color in an otherwise plain-looking letter, and combined with compelling promotions, can be a very cost-effective solution to boost your response rates.

Buckslips can be sent through or the , but NOT through the single-endpoint Letter API.

Anything sent with Buckslips will have a 4-day SLA.

Getting started with Buckslips

Check out our:

  • Lob Dashboard: buckslips, or send with a

  • API documentation for , buckslips, or with buckslips

  • for design inspiration

  • Or watch a quick demo of ordering buckslips and sending them with letters via the dashboard

Buckslip dimensions & design specs

Layout templates
Buckslip paper specs
  • 8.5” x 3.5” size

  • 80 lb. Text, Gloss or Matte finish

  • Double-sided, full bleed

Buckslip design & guidelines

Artwork can be featured on both sides of the buckslip. In general, any critical design elements or text should be 0.125" away from the final trim line due to movement at press. There are also no color limitations for buckslips.

Other considerations are:

  • Double-check that all images are embedded into your document

  • Ensure all rasterized artwork (images, effects, copy, etc.) is created and saved at or above 300 dpi

  • Thin, small fonts with over 3 colors may fill in slightly or appear “fuzzy”

  • Line weights of 0.5 pt or more assure optimum print results

  • Any barcodes/QR codes provided need to be print-ready

Refer to our for more details on image prepping.

Buckslip ordering

Buckslips must be created, ordered, and printed, and available in your inventory before they can be utilized.

Upload your front and back designs to create a new buckslip, then order your inventory. . Buckslips can be purchased as an one-off order or through auto-reordering.

  • The minimum order quantity is 10,000 buckslips per artwork design submitted

  • Allow an estimated 10 business days for buckslips to be available for use in your Lob dashboard.

  • Spoilage is an industry norm that occurs during print set-up and processing. Based on the industry average, we recommend adding 2-3% to account for spoilage.

Order buckslips via the Lob dashboard
  • Go to the section in the Lob dashboard, and hit the Create button

  • Upload a front and back design, and hit Create

  • Once buckslip details show, select the Order button at the bottom

  • Add the desired number of buckslips and hit Order

Order buckslips via the Buckslips API

Send a request to the /v1/buckslips with the following fields:

  • Description (Required, string): A name to identify your buckslip

  • Front (Required, string): A locally hosted PDF or hosted PDF URL for the front buckslip artwork

  • Back (Optional, string): A locally hosted PDF or hosted PDF URL for the back buckslip artwork

Send a request to the /v1/buckslips/{buckslip_id}/orders with the following field:

  • Quantity (Required, number): Number of buckslips you would like to order

Order & inventory management

See for letter add-ons

Sending letters with buckslips

Once buckslips are ordered, they cannot be sent with letters until your Lob dashboard reflects they are fully stocked and available in your inventory. An email will notify you once your buckslips are in stock and are ready to be sent with letter campaigns.

The minimum send quantity is 5,000 buckslips per letter campaign. If a letter campaign is created with a specified buckslip ID that is not in stock, the campaign request will fail.

Special considerations for sending letters with buckslips:

  • Only 1 buckslip max per letter request

  • Buckslips counts as one sheet in a letter

  • Any letter including a buckslip can have a maximum total of 6 sheets (5 letter sheets + 1 buckslip) to fit in a #10 standard envelope

    • Said another way, a buckslip cannot be inserted in letters over 6 sheets, as it cannot be inserted in a flat envelope at this time

  • Custom envelopes (outer & return envelopes) are supported for letters with buckslips

  • Buckslips cannot be sent with card-affixed letters at this time

  • Buckslips cannot be used with Certified or Registered Mail at this time

  • Buckslips cannot be sent using the single endpoint Letters API at this time

Send buckslips via the Campaigns dashboard
  • In “Configure Settings” Step 1 of the Letter creation flow, choose “Buckslip” as your add-on

  • In “Choose Creative” Step 3 of your Campaign, select the buckslip design that you’d like to use in your Letter campaign.

    • You cannot send buckslips if you have an insufficient amount in your inventory, as your campaign request will be rejected

Send buckslips via the Campaigns API

Adding buckslips to letters can be done via the :

  • When loading your creative assets, set the details[buckslips][0] parameter in your POST call to https://api.lob.com/v1/creatives to the desired buckslip_id

    • The buckslips parameter is an array which accepts a single buckslip_id

    • In the future, we may begin accepting multiple buckslip_id’s, hence the array data type

  • Additionally, you can find all buckslips in your account by sending a GET call to https://api.lob.com/v1/buckslips

Inventory management for letter add-ons

For any letter add-on items (including buckslips, cards, or envelopes), you will have the ability to view existing orders and manage your own inventory for any designs that have been submitted. Go to your Lob dashboard and go to the section for , , or .

Item details

Depending on the custom mail type selected, you will see some of the following details of your ordered design:

  • Design

  • Size

  • Type

  • Finish

Inventory

View the number of remaining custom items in your inventory and the number of orders that are still outstanding or fulfilled. Inventory statuses include:

  • Available: Inventory currently in stock and ready to use

  • Reserved: Inventory allocated for scheduled campaigns

  • Remaining: Inventory available, less reserved inventory

Inventory for custom items will decrement as you send letters with the add-on item of a specific design, and increment if you cancel a letter request. It may take a few minutes for the inventory quantity to update after any action.

Alternatively, use a GET call to the item endpoint to return a list of all items on your account, and any available and pending inventory.

  • Buckslips: https://api.lob.com/v1/buckslips

  • Cards: https://api.lob.com/v1/cards

  • Envelopes: https://api.lob.com/v1/envelopes

Spoilage

Accurate inventory management is essential for ensuring that we have the right products available to meet our customers' needs. Lob has automated tools and physical audits in place for regularly reconciling inventory, but we need to account for product spoilage.

We are focused on addressing routine product spoilage that occurs during print set-up and assembly: Mailpieces generated during setup and testing are discarded along with any misprints or damaged pieces. For items printed on demand, this is not an issue, but for orders using pre-printed custom inventory, this ultimately impacts the accuracy of Lob's reported inventory.

By addressing this issue and accounting for spoilage at the time of processing, we can improve the timeliness and accuracy of our inventory, to the benefit of your mail campaigns.

  • An auto-triggered overnight job will calculate spoilage from the previous production day and Lob will decrement it from your inventory accordingly.

  • As a proactive measure, based on the industry average, we recommend adding 2-3% to account for spoilage when ordering custom inventory (custom envelopes, cards, buckslips).

By addressing this issue and accounting for spoilage, we can improve the timeliness and accuracy of our inventory, to the benefit of your mail campaigns.

Auto-reordering

Given add-on items require additional lead times for printing and stocking in inventory, we recommend enabling auto-reordering for any items that will be continuously utilized to ensure there will be no risk of running out. When reordering is turned on, a new order will be submitted whenever the remaining inventory quantity falls below 20%. A confirmation will show the reorder quantity and price that will be charged.

  • To turn on auto-reordering:

    • Select the design you would like to auto-reorder

    • Go to the Auto-Reorder Settings section, click Set Up, set auto-reorder to on, and hit Save

    • Add a reorder quantity, the number of items to be ordered when your most recent order falls below 20% of the original order quantity, and hit Save

  • To turn off auto-reordering:

    • Go into the same Auto-Reorder Settings

    • Set the auto-reorder button to off, and hit Save

Order history

Order details for any particular item design will be populated in the order history window once submitted, including order date, item ID, order quantity, inventory status, and expected availability date.

  • Order status: Provides current item status

    • Pending: Lob is reviewing the order submission

    • In Production: The order is being fulfilled

    • Available: Item is available in inventory and ready for use

    • Expired: For envelopes only; indicates if envelopes expired (after 6mo)

    • Canceled: Customer canceled order while status was pending

  • Estimated date: Lob’s rough estimation of when items may be available in your inventory. However, an email confirmation will be sent when they are actually ready for use.

  • Expand details: Each order under a specific design can be expanded by clicking on the ‘+’ sign to the right in each row, where the expiration date (envelopes only), unit price, and total order cost will become visible

{
  "event_type": {
    "resource": "self mailers",
    "enabled_for_test": true,
    "id": "self_mailer.rendered_thumbnails",
    "object": "event_type"
  },
  "reference_id": "sfm_c29bbbca5f7bd489",
  "date_created": "2021-12-16T01:34:18.159Z",
  "id": "evt_d47ff1b815373f67",
  "body": {
    "id": "sfm_c29bbbca5f7bd489",
    "description": "self mailer create",
    "metadata": {
      "secretId": "REDACTED",
      "subObject": {
        "subId": "REDACTED"
      }
    },
    "to": {
      "id": "REDACTED",
      "description": "REDACTED",
      "name": "REDACTED",
      "company": "REDACTED",
      "phone": "REDACTED",
      "email": "REDACTED",
      "address_line1": "REDACTED",
      "address_line2": "REDACTED",
      "address_city": "REDACTED",
      "address_state": "REDACTED",
      "address_zip": "REDACTED",
      "address_country": "REDACTED",
      "metadata": {
        "arrayTest": [
          "REDACTED",
          {
            "keyInArray": "REDACTED",
            "key2": "REDACTED"
          },
          {
            "keyInArray2": "REDACTED"
          }
        ]
      },
      "date_created": "REDACTED",
      "date_modified": "REDACTED",
      "deleted": "REDACTED",
      "object": "REDACTED"
    },
    "from": {
      "id": "REDACTED",
      "description": "REDACTED",
      "name": "REDACTED",
      "company": "REDACTED",
      "phone": "REDACTED",
      "email": "REDACTED",
      "address_line1": "REDACTED",
      "address_line2": "REDACTED",
      "address_city": "REDACTED",
      "address_state": "REDACTED",
      "address_zip": "REDACTED",
      "address_country": "REDACTED",
      "metadata": {},
      "date_created": "REDACTED",
      "date_modified": "REDACTED",
      "deleted": "REDACTED",
      "object": "REDACTED"
    },
    "url": "REDACTED",
    "outside_template_id": null,
    "inside_template_id": null,
    "inside_template_version_id": null,
    "outside_template_version_id": null,
    "carrier": "USPS",
    "tracking_events": [],
    "thumbnails": [
      {
        "small": "REDACTED",
        "medium": "REDACTED",
        "large": "REDACTED"
      },
      {
        "small": "REDACTED",
        "medium": "REDACTED",
        "large": "REDACTED"
      }
    ],
    "merge_variables": "REDACTED",
    "size": "6x18_bifold",
    "mail_type": "usps_first_class",
    "expected_delivery_date": "2021-12-27",
    "target_delivery_date": null,
    "date_created": "2021-12-16T01:34:12.087Z",
    "date_modified": "2021-12-16T01:34:14.469Z",
    "send_date": "2021-12-16T01:39:12.078Z",
    "object": "self_mailer"
  },
  "object": "event"
}

1

Immediately

0 min

2022-01-01T00:00:00Z

2

5 sec

5 sec

2022-01-01T00:00:05Z

3

5 min

~5 min

2022-01-01T00:05:05Z

4

30 min

~35 min

2022-01-01T00:35:05Z

5

2 hr

~2 hr 35 min

2022-01-01T02:35:05Z

6

5 hr

~7 hr 35 min

2022-01-01T07:35:05Z

7

10 hr

~17 hr 35 min

2022-01-01T17:35:05Z

8

10 hr

~27 hr 35 min

2022-01-02T03:35:05Z

See full list of events here
event
entire event object
Print & Mail Edition
receive the webhook
rate limit
here
securing your endpoint
Settings
tracking events
Debugger
Debugger tool
ngrok
webhook dashboard
creating a new webhook
webhooks dashboard
dashboard
Debugger
cross-site request forgery
API Version on your account
hard-coded header
return envelopes with tracking
return envelope tracking
dashboard
return envelope tracking events
https://s3-us-west-2.amazonaws.com/public.lob.com/assets/beach.jpg
https://s3-us-west-2.amazonaws.com/public.lob.com/assets/jungle.jpg
Print & Mail edition
sales team
custom envelopes
API documentation
Template Gallery
Letter design template with horizontal card affix
Card design template
image formatting guides
Cards section
endpoint
endpoint
inventory management
Campaigns
Campaign API
single-endpoint Letters API
Campaigns API
Campaigns dashboard
Upload & order
letter campaign
creating
ordering
sending letter campaigns
Template Gallery
Buckslip design template
image formatting guides
Buckslips
endpoint
endpoint
inventory management
Campaigns
Campaign API
Buckslips
Cards
Envelopes
What your inventory management screen typically looks like (Envelope inventory in this example)
Sample spoilage message when ordering

Letter envelopes

Standard letter outer envelopes

Letters printed by Lob are sent in a plain Standard #10 double-windowed outer envelope, or in a flat envelope when letter pages exceed 6 pages. These are automatically included when a Letter API request is made, and no special request will need to be made to utilize them. These standard outer envelopes cannot be customized by default.

Standard #10 outer envelope (double-windowed)

Design templates
  • Letter template for standard letter & check orders (tri-folded)

Envelope specs
  • Envelope face size: 4.125 x 9.5"

  • Window #1 (Top):

    • Window size: 0.875 x 3.25"

    • Position from left edge: 0.625"

    • Position from bottom edge: 2.375"

  • Window #2 (Bottom):

    • Window size: 1 x 4"

    • Position from left edge: 0.625"

    • Position from bottom edge: 1"

  • 24# White Wove

  • Contains blue inside security tint

  • Fits up to 6 sheets of tri-folded 8.5 x 11" paper / 12 duplexed pages

9 x 12" Flat outer envelope (single window)

Design templates
  • Letter template for standard letter & check orders (full page)

Envelope specs
  • Envelope face size: 9 x 12"

  • Window #1:

    • Window size: 4 x 3.375"

    • Position from left edge: 0.5"

    • Position from top edge: 0.625"

  • 24# White Wove

  • Contains blue inside security tint

  • Fits between 7 to 60 sheets of 8.5 x 11" paper / up to 120 duplexed pages

Certified Mail envelopes

All Certified Mail printed by Lob are sent in a large single-windowed Standard #10 Certified Mail envelope with an inside security tint. These Certified Mail envelopes cannot be customized.

Design templates
  • Design template for Certified single-window #10 envelope

  • Design template for Certified letter orders (tri-folded)

Envelope specs
  • Envelope face size: 4.125 x 9.5"

  • Window #1:

    • Window size: 3 x 8"

    • Position from left & right edges: 0.75"

    • Position from top & bottom edges: 0.5625"

  • 28# White Wove

  • Contains inside security tint

  • Fits up to 6 sheets of tri-folded 8.5 x 11" paper / 12 duplexed pages

Return envelopes

Aspects of this feature are exclusive to higher edition customers. Upgrade your Print & Mail edition to gain access to this form factor, or reach out to our sales team.

Lob offers two options for USPS reply mail for our letter form factors only:

  • Courtesy Reply Mail, available to all customers

  • Business Reply Mail, available to Enterprise edition customers only

Both reply mail options will be sent in a standard #9 return envelope (single-windowed), which are available to all customers by default. They are blank, come without prepaid postage, and will expire in 6 months. No custom artwork is permitted on the front or back sides of these plain #9 envelopes. See our Template Gallery for design examples.

Design templates
  • #9 Standard return envelope (single window)

  • Perforated letter template for custom return envelopes

Envelope specs
  • Envelope face size: 3.875 x 8.875"

  • Window #1:

    • Window size: 1.125 x 4.5"

    • Position from left edge: 0.875"

    • Position from bottom edge: 0.5"

  • Contains inside security tint

  • Expiration: 6 months (to ensure the integrity of adhesives)

  • Fits up to 6 sheets of 8.5 x 11" paper / 12 duplexed pages (+ letter perforation required)

To include a return envelope with your mail pieces, you will need to send a Letter API request with return_envelope and perforated_page options completed:

  • return_envelope = true

  • perforated_page, specifying the page that will have tear-off slips with a remittance slip and return address for the reply mail

Once the return envelope setting is activated, letter designs will automatically include a bottom perforation if including a return envelope.

For customer's who want to further customize their #9 envelope artwork, please reach out to your Customer Success Representative.

Sending Business Reply Mail (BRM)

This feature is exclusive to Enterprise edition customers. Upgrade your Print & Mail edition to gain access to this form factor, or reach out to our sales team.

  • A valid BRM permit must be obtained from USPS before you can start using a BRM mail piece and receive BRM mail

  • BRM users also need a unique Zip+4Code assigned by the USPS to qualify for volume discounts

    • Assigned Zip+4 Codes are unique to the category of Reply Mail used

  • Customers sending Business Reply Mail (BRM) must use Business Return Envelopes (BREs). BREs are #9 return envelopes (no windows) with inside security tint

    • A USPS-approved design must be used in BREs; no custom artwork is allowed

    • Postage must be prepaid

    • Letter perforation is required

Business Return Envelopes (BREs) cannot be ordered through the dashboard; please reach out to your account manager to facilitate.

Return envelope tracking

This feature is exclusive to higher edition customers. Upgrade your Print & Mail edition to gain access to this form factor, or reach out to our sales team.

Lob offers return envelope tracking for their USPS Courtesy Reply Mail services. Return tracking information is only available via webhooks for standard return envelopes (non-custom single-windowed envelopes only).

To access this feature, enterprise customers need to send an API request for a letter with return_envelope, return_address and perforated_page options completed:

  • return_envelope = true, or return_envelope = no_9_single_window, if custom return envelopes are enabled on the account

  • perforated_page, specifying the page that will have tear-off slips with a remittance slip and return address for the reply mail

  • return_address, specifying the return address the return envelope customers should send remittance slips to

This will result in the return address and associated Intelligent Mail Barcode (IMb) tracking code to be placed within the window area of the perforated page. The #9 return envelope will be mailed to the customer along with the letter including the perforated page and return address in a #10 standard outer envelope. Note that no custom outer envelopes can be used with this feature at this time.

It is possible to send Courtesy Reply mail without enabling return envelope tracking, as they are two separate features. To use normal reply mail without tracking, make sure to skip the return_address field. This means only the return address (and no IMb) will be rendered in the window area of the perforated page.

Tracking event notifications

Once the returned envelope enters the mail stream and is scanned by the USPS, the customer can start receiving notifications to mail tracking events, which will be surfaced via webhooks.

The following is a list of mail tracking event labels and descriptions available for reply mail:

  • Created: Return envelope is first created (should be simultaneous with Letter creation)

  • In transit: Return envelope is being processed at the entry/origin facility

  • In local area: Return envelope is being processed at the destination facility

  • Processed for delivery: Return envelope is greenlit for delivery at the end recipient's nearest postal facility. The mailpiece should reach the mailbox within 1 business day of this tracking event.

  • Re-routed: Return envelope is re-routed due to recipient change of address, address errors, or USPS relabeling of barcode/ID tag area

  • Returned to sender: Return envelope is undeliverable and is being returned to sender due to barcode, ID tag area, or address errors.

Return envelope tracking is accessible via our webhooks, and the Event Logs node in the Lob dashboard. Tracking events will appear in the Letters Events portion of the original individual mailpiece in the dashboard as soon as they become available, or can be downloaded using the Export button that’s located at the top of the Letters section in the dashboard.

Note: As USPS does not return the Delivered mail tracking event for return envelopes, Lob is unable to surface this event via webhooks.

Best practices

Return addresses that are passed into the return_address field will be used exactly as passed in. We do not run this address through any verification services like NCOA or CASS. This helps ensure that remittance slips are sent to the business address provided. Customers must take extra care to ensure that the address information provided matches their desired delivery address.

Additionally, we recommend supplying ZIP+4 codes in the return address specified to ensure the fastest, most accurate mailing possible. This can speed up USPS processing and delivery by up to as much as 2 days.

Custom envelopes

This feature is exclusive to Enterprise edition customers. Upgrade your Print & Mail edition to gain access to this feature, or contact our sales team.

Overview

Lob allows customization of select #10 outer envelopes and #9 return envelopes. Envelopes must be created, ordered, printed and made available in your inventory before they can be utilized with Letter API call requests. Envelope orders and inventory can be fully managed in the Lob dashboard. Note that custom envelopes are only supported for letters, and are unavailable for checks or postcards.

To start creating letters with custom envelopes, refer to our Letters API documentation or see our Template Gallery for inspiration.

Envelope dimensions & specs

Standard #10 outer envelope (single-window only)

Design templates
  • Custom #10 outer envelope template

  • Letter template for custom envelopes

Envelope specs
  • Envelope face size: 4.125 x 9.5"

  • Window #1:

    • Window size: 1.125 x 4.5"

    • Position from left edge: 0.875"

    • Position from bottom edge: 0.5"

  • 24# White Wove

  • Contains inside security tint

  • Expiration: 6 months (due to ensure adhesive's integrity)

  • Fits up to 6 sheets of tri-folded 8.5 x 11" paper / 12 duplex pages

Standard #9 return envelope (no-window & single-window options)

Design templates
  • #9 Standard return envelope (no window)

  • #9 Standard return envelope (single window)

  • Perforated letter template for custom return envelopes

Envelope specs
  • Envelope face size: 3.875 x 8.875"

  • Window #1 (if single-windowed option):

    • Window size: 1.125 x 4.5"

    • Position from left edge: 0.875"

    • Position from bottom edge: 0.5"

  • Contains inside security tint

  • Expiration: 6 months (to ensure the integrity of adhesives)

  • Fits up to 6 sheets of tri-folded 8.5 x 11"paper / 12 duplexed pages (+ letter perforation required)

Design placement

Follow the guidelines below to achieve optimal results for your envelope designs, and to ensure a smooth creation process.

Layout considerations
  • Bleeds should extend 0.125" past the trim line

  • Any other artwork should be 0.125" away from trim line due to movement at press

  • Custom envelopes will not be printed outside of the safe zone, nor on the flap

Accepted image submission formats
  • Preferred: PDF file (.pdf)

  • Secondary: Adobe Illustrator (.ai), Indesign (.indd), Photoshop (.psd)

Artwork considerations
  • Outline all fonts: differences in kerning, font versions, anti-aliasing, etc., can cause small variations between what you see on your screen and what we output to press

  • Double-check that all images are embedded into your document

  • Ensure all rasterized artwork (images, effects, copy, etc.) is created and saved at or above 300 dpi

  • All images must be at or under 25% ink saturation

  • Type should be no smaller than 5 pt

  • Thin, small fonts with over 3 colors may fill in slightly or appear “fuzzy”

  • Line weights of 0.5 pt or more assure optimum print results

  • It is preferred that barcodes/QR codes are vector/editable

  • CMYK documents are preferred over RGB

Envelope window placement

The envelope window is where your recipient address information will be visible. Reference our letter template for custom envelopes to ensure that your recipient’s address is visible. No design within the envelope window will be printed.

Stamp placement

Postage will be placed in the upper right corner of the envelope. No design will be printed in this space. Refer to our custom envelope template for stamp placement.

Return address placement

USPS prefers that return addresses are placed in the upper left portion of the mail piece, on the side of the piece bearing postage. USPS does not require that all mail include a return address; however, mail sent without a return address cannot be returned.

Ordering envelopes

Envelopes must be created, ordered, printed, and available in your inventory before they can be utilized.

First, create an envelope design by uploading your artwork in the 'Envelope' section of the Lob dashboard. Hit “Create”, and in the new envelope creation screen, select the envelope size & design and the desired postage option for #10 outer envelopes. Any #9 return envelope selection will default to USPS Standard Class postage.

#10 custom outer envelopes (front & back options)
#9 custom return envelopes (front-side only)

Once envelope designs are uploaded into the dashboard, an order must be placed to make them available in your inventory for later use. Envelopes can be purchased as one-off orders or through auto-reordering directly in the Lob dashboard.

First-time orders:

  • New envelope designs take time for quoting, production, and shipment; please allow up to 25 days for any new design orders to be fulfilled.

  • The minimum order quantity for any custom envelope order is 10,000 envelopes per artwork design submitted.

  • Spoilage is an industry norm that occurs during print set-up and processing. Based on the industry average, we recommend adding 2-3% to account for spoilage.

Auto-reordering:

  • When the auto-reordering function is turned on, a new order will be submitted whenever the remaining envelope quantity in inventory falls below 20%. A confirmation will show the reorder quantity and price that will be charged.

Plan ahead:

  • Given additional lead times, we recommend enabling auto-reorder for envelopes that will be continuously utilized to ensure there will be no risk of running out.

  • Additionally, custom envelopes have a 6-month expiration date to ensure the adhesive's integrity. Any unused envelopes that have expired will be discarded by Lob.

Sending letters with custom envelopes

Envelopes cannot be used until the dashboard indicates that they have been made available, and any preemptive API requests that include your unique envelope ID will fail. Once an envelope order is available in your inventory, it can be utilized with Letter API call requests.

To use a custom envelope with your mail piece, you will need to set the custom_envelope parameter in your POST call to https://api.lob.com/v1/letters to the desired custom envelope ID, which can be found in your dashboard.

If a letter is created with a specified envelope ID that is not in stock, the letter request will be rejected. If a letter is created with a specified envelope ID and is 7+ sheets, the letter will be sent instead in a blank, flat envelope, and the custom envelope inventory will not be decremented. Additionally, custom envelopes have an expiration date, which ensures the envelope's integrity.

When using the single endpoint Letter API, the minimum quantity of envelopes that can be sent during any 24-hour production-day period (10AM PT - 10AM PT) is 4,000 envelopes. For any customer that fails to send over the 4,000 envelope minimum (with corresponding Letter API calls) will incur a flat surcharge of $375/day on your month-end usage invoice.

Reach out to your dedicated Customer Success Manager if you have any questions.

Inventory management

Envelope details

Return to the dashboard at any given time to view existing order designs, the number of remaining envelopes, the number of orders that are still outstanding or fulfilled, and mailing class/postage type selected. Inventory will decrease with each API call made for a specific custom envelope design corresponding to a unique envelope ID.

Auto-reorder settings

When the auto-reordering function is turned on, a new order will be submitted whenever the remaining envelope quantity in inventory falls below 20%. A confirmation will show the reorder quantity and price that will be charged.

Given that custom envelopes have additional lead times, we recommend enabling auto-reorder for envelopes that will be continuously utilized to ensure there will be no risk of running out.

Order history

View previously submitted orders, and order details once any order is submitted. Rough expected date of availability for submitted orders provides an approximate time of when envelopes may be available, while an email confirmation will be sent when envelopes are actually ready for use.

Custom letter envelopes are set to expire in 6 months (due to adhesives). Expiration dates of ordered designs that still remain in your inventory can be viewed. Once envelopes are expired, customers will not be able to access any remaining inventory of the particular design order in their dashboard.

How to add a QR code in Campaigns tool
events

Advanced templating (Handlebars)

Using the Handlebar templating engine to create advanced templates

Personalizing templates with Handlebars

By default, Lob uses a basic templating engine based on Mustache. If you would like to render complex personalizations, use the alternate Handlebars templating engine route through Lob API. Handlebars syntax allows you to populate, evaluate, and iterate using templates and API requests. The biggest advantage of this approach is quickly creating dynamic personalization without making any changes to your codebase. We can use advanced templating to make dynamic tables.

Creating a template

  1. Start with any Handlebars-friendly template. Dynamic variables should be wrapped in double curly braces {{like_this}} . To the right is an example of a simple handlebars template.

<html>
Name is: {{user.name}}
Location is: {{user.location}} 
</html>
  1. To push your template to a Lob environment, use the /v1/templates API. Creating Handlebars templates via the Dashboard UI is not supported at this time. To specify that our service should use the Handlebars templating engine, you will need pass handlebars in the template request engine field as shown on the right.

POST 
	[/v1/templates](<https://api.lob.com/v1/templates>)/ 

{
"description":"Test Template",
"html":"<html>Name is: {{user.name}} <br> 
Location is: {{user.location}} </html>",
"engine":"handlebars",
"required_vars": ["user"] //optional
}

Response

{
    "id": "tmpl_81ff8f64ce61285",
....
}

Note the optional field, required_vars. Any request to create a mailpiece using this template will require the variables listed there in order to complete successfully.

Template compilation API

You can use this newly created endpoint to test that your Handlebars template compiles as expected. To do that, use the /v1/templates/ endpoint and add your merge variable(s) as a dynamic URL query parameter. You can use this to inspect how your template will display with the merge variables passed in. The response is the same format that Lob will use to render your mailpiece.

GET
/v1/templates/:id/compile
  ?merge_vars={"someVar":"someVal"}

Returns HTML

Create a mailpiece using Handlebars

Now that your template has been created in a Lob environment, the templating engine has been set to handlebars, and you've tested out your template using the Template Compilation API, you can send a mailpiece request to the /v1/checks/, /v1/postcards/, /v1/letters/ or /v1/self_mailers/ endpoint as you normally would. In the request message body, use the merge_variables field to pass in dynamic values.

Helpers

Built in helpers

The below helpers can be used for many dynamic use cases. Helpers like if blocks can include nested built-in and customer helper conditionals (like if, and, or, eq, etc).

#if

You can use the if helper to conditionally render a block. If its argument returns false, undefined, null, "", 0, or [], Handlebars will not render the block.


<div class="entry">
{{#if author}}
<h1>{{firstName}} {{lastName}}</h1>
{{/if}}
</div>

When you pass the following input to the above template:


{
  author: true,
  firstName: "Yehuda",
  lastName: "Katz",
}

This will produce the result as below:


<div class="entry">
<h1>Yehuda Katz</h1>
</div>

If the input is an empty JSONObject {}, then author will become undefined and if condition fails, resulting in the output as follow:

<div class="entry"></div>

When using a block expression, you can specify a template section to run if the expression returns a falsey value. The section, marked by else is called an "else section".


<div class="entry">
{{#if author}}
<h1>{{firstName}} {{lastName}}</h1>
{{else}}
<h1>Unknown Author</h1>
{{/if}}
</div>

#unless

You can use the unless helper as the inverse of the if helper. Its block will be rendered if the expression returns a falsy value.


<div class="entry">
{{#unless license}}
<h3 class="warning">WARNING: This entry does not have a license!</h3>
{{/unless}}
</div>

If looking up license under the current context returns a falsy value, Handlebars will render the warning. Otherwise, it will render nothing.

#each

You can iterate over a list using the built-in each helper. Inside the block, you can use this to reference the element being iterated over.


<ul class="people_list">
  {{#each people}}
    <li>{{this}}</li>
  {{/each}}
</ul>

when used with this context:


{
  people: [
    "Yehuda Katz",
    "Alan Johnson",
    "Charles Jolley",
  ],
}

will result in:


<ul class="people_list">
    <li>Yehuda Katz</li>
    <li>Alan Johnson</li>
    <li>Charles Jolley</li>
</ul>

You can use the this expression in any context to reference the current context.

You can optionally provide an else section which will display only when the list is empty.


{{#each paragraphs}}
<p>{{this}}</p>
{{else}}
<p class="empty">No content</p>
{{/each}}

When looping through items in each, you can optionally reference the current loop index via {{@index}}.

{{#each array}} {{@index}}: {{this}} {{/each}}

Additionally for object iteration, {{@key}} references the current key name:

{{#each object}} {{@key}}: {{this}} {{/each}}

The first and last steps of iteration are noted via the @first and @last variables when iterating over an array. When iterating over an object only the @first is available. Nested each blocks may access the iteration variables via depth based paths. To access the parent index, for example, {{@../index}} can be used.

#with

The with-helper allows you to change the evaluation context of template-part.


{{#with person}}
{{firstname}} {{lastname}}
{{/with}}

when used with this context:


{
  person: {
    firstname: "Yehuda",
    lastname: "Katz",
  },
}

will result in:

Yehuda Katz

with can also be used with block parameters to define known references in the current block. The example above can be converted to


{{#with city as | city |}}
  {{#with city.location as | loc |}}
    {{city.name}}: {{loc.north}} {{loc.east}}
  {{/with}}
{{/with}}

Which allows for complex templates to potentially provide clearer code than ../ depthed references allow for.

You can optionally provide an {{else}} section which will display only when the passed value is empty.


{{#with city}}
{{city.name}} (not shown because there is no city)
{{else}}
No city found
{{/with}}

#lookup

The lookup helper allows for dynamic parameter resolution using Handlebars variables.

This is useful for resolving values for array indexes.


{{#each people}}
   {{.}} lives in {{lookup ../cities @index}}
{{/each}}

It can also be used to lookup properties of object based on data from the input. The following is a more complex example that uses lookup in a sub-expression to change the evaluation contextto another object based on a property-value.


{{#each persons as | person |}}
    {{name}} lives in {{#with (lookup ../cities [resident-in])~}}
      {{name}} ({{country}})
    {{/with}}

Custom helpers

Custom helpers are additional functions that can assist in the formatting of your document. The documentation here is directly pulled from the associated third-party github repo. The helpers below are supported.

For uniformity with Handlebars' terminology, we use the wordfalsey instead of the more commonly used falsy.

Array helpers

{{after}}

Returns all of the items in an array after the specified index. Opposite of before.

Params

  • array {Array}: Collection

  • n {Number}: Starting index (number of items to exclude)

  • returns {Array}: Array exluding n items.

Example

<!-- array: ['a', 'b', 'c'] -->

{{after array 1}}

<!-- results in: '["c"]' -->

{{arrayify}}

Cast the given value to an array.

Params

  • value {any}

  • returns {Array}

Example

 {{arrayify "foo"}}

<!-- results in: [ "foo" ] -->

{{before}}

Return all of the items in the collection before the specified count. Opposite of after.

Params

  • array {Array}

  • n {Number}

  • returns {Array}: Array excluding items after the given number.

Example

<!-- array: ['a', 'b', 'c'] -->

{{before array 2}}

<!-- results in: '["a", "b"]' -->

{{eachIndex}}

Implementation of the default Handlebars loop helper {{#each}} adding index (0-based index) to the loop content

Params

  • array {Array}

  • options {Object}

  • returns {String}

Example

<!-- array: ['a', 'b', 'c'] -->

{{#eachIndex array}}  
{{item}} is {{index}}
{{/eachIndex}}

<!-- results in 'a is 0, b is 1, c is 2' -->

{{filter}}

Block helper that filters the given array and renders the block for values that evaluate to true, otherwise the inverse block is returned.

Params

  • array {Array}

  • value {any}

  • options {Object}

  • returns {String}

Example

<!-- array: ['a', 'b', 'c'] -->

{{#filter array "foo"}}AAA
{{else}}BBB
{{/filter}}

<!-- results in: 'BBB' -->

{{first}}

Returns the first item, or first n items of an array.

Params

  • array {Array}

  • n {Number}: Number of items to return, starting at 0.

  • returns {Array}

Example

{{first "['a', 'b', 'c', 'd', 'e']" 2}}

<!-- results in: '["a", "b"]' -->

{{forEach}}

Iterates over each item in an array and exposes the current item in the array as context to the inner block. In addition to the current array item, the helper exposes the following variables to the inner block:

  • index

  • total

  • isFirst

  • isLast Also, @index is exposed as a private variable, and additional private variables may be defined as hash arguments.

Params

  • array {Array}

  • returns {String}

Example

<!-- accounts = [
{'name': 'John', 'email': '[email protected]'},
{'name': 'Malcolm', 'email': '[email protected]'},
{'name': 'David', 'email': '[email protected]'}
] -->

{{#forEach accounts}}
  <a href="mailto:{{ email }}" title="Send an email to {{ name }}">
    {{ name }}
  </a>{{#unless isLast}}, {{/unless}}
{{/forEach}}

{{inArray}}

Block helper that renders the block if an array has the given value. Optionally specify an inverse block to render when the array does not have the given value.

Params

  • array {Array}

  • value {any}

  • options {Object}

  • returns {String}

Example

<!-- array: ['a', 'b', 'c'] -->

{{#inArray array "d"}}  foo{{else}}  bar{{/inArray}}

<!-- results in: 'bar' -->

{{isArray}}

Returns true if value is an es5 array.

Params

  • value {any}: The value to test.

  • returns {Boolean}

Example

{{isArray "abc"}}
<!-- results in: false --> 

<!-- array: [1, 2, 3] -->

{{isArray array}}

<!-- results in: true -->

{{itemAt}}

Returns the item from array at index idx.

Params

  • array {Array}

  • idx {Number}

  • returns {any} value

Example

<!-- array: ['a', 'b', 'c'] -->

{{itemAt array 1}}

<!-- results in: 'b' -->

{{join}}

Join all elements of array into a string, optionally using a given separator.

Params

  • array {Array}

  • separator {String}: The separator to use. Defaults to ,.

  • returns {String}

Example

<!-- array: ['a', 'b', 'c'] -->

{{join array}}

<!-- results in: 'a, b, c' --> 

{{join array '-'}}

<!-- results in: 'a-b-c' -->

{{equalsLength}}

Returns true if the the length of the given value is equal to the given length. Can be used as a block or inline helper.

Params

  • value {Array|String}

  • length {Number}

  • options {Object}

  • returns {String}

<!-- var value = "example" -->

{{equalsLength value 7}}

<!-- results in: true -->

<!-- var value = "example" -->

{{equalsLength value 5}}

<!-- results in: false -->

{{last}}

Returns the last item, or last n items of an array or string. Opposite of first.

Params

  • value {Array|String}: Array or string.

  • n {Number}: Number of items to return from the end of the array.

  • returns {Array}

Example

<!-- var value = ['a', 'b', 'c', 'd', 'e'] --> 

{{last value}}

<!-- results in: ['e'] --> 

{{last value 2}}

<!-- results in: ['d', 'e'] --> 

{{last value 3}}

<!-- results in: ['c', 'd', 'e'] -->

{{length}}

Returns the length of the given string or array.

Params

  • value {Array|Object|String}

  • returns {Number}: The length of the value.

Example

{{length '["a", "b", "c"]'}}

<!-- results in: 3 --> 

<! myArray = ['a', 'b', 'c', 'd', 'e']; -->

{{length myArray}}

<!-- results in: 5 --> 

<!-- myObject = {'a': 'a', 'b': 'b'}; -->

{{length myObject}}

<!-- results in: 2 -->

{{map}}

Returns a new array, created by calling function on each element of the given array. For example,

Params

  • array {Array}

  • fn {Function}

  • returns {String}

Example

<!-- array: ['a', 'b', 'c'], and "double" is afictitious function that duplicates letters -->

{{map array double}}

<!-- results in: '["aa", "bb", "cc"]' -->

{{pluck}}

Map over the given object or array or objects and create an array of values from the given prop. Dot-notation may be used (as a string) to get nested properties.

Params

  • collection {Array|Object}

  • prop {Function}

  • returns {String}

Example

// {{pluck items "data.title"}}

<!-- results in: '["aa", "bb", "cc"]' -->

{{reverse}}

Reverse the elements in an array, or the characters in a string.

Params

  • value {Array|String}

  • returns {Array|String}: Returns the reversed string or array.

Example

<!-- value: 'abcd' -->

{{reverse value}}

<!-- results in: 'dcba' -->

<!-- value: ['a', 'b', 'c', 'd'] -->

{{reverse value}}

<!-- results in: ['d', 'c', 'b', 'a'] -->

{{some}}

Block helper that returns the block if the callback returns true for some value in the given array.

Params

  • array {Array}

  • iter {Function}: Iteratee

  • {Options}: Handlebars provided options object

  • returns {String}

Example

<!-- array: [1, 'b', 3] -->

{{#some array isString}}  
Render me if the array has a string.{{else}} Render me if it doesn't.
{{/some}}

<!-- results in: 'Render me if the array has a string.' -->

{{sort}}

Sort the given array. If an array of objects is passed, you may optionally pass a key to sort on as the second argument. You may alternatively pass a sorting function as the second argument.

Params

  • array {Array}: the array to sort.

  • key {String|Function}: The object key to sort by, or sorting function.

Example

<!-- array: ['b', 'a', 'c'] -->

{{sort array}}

<!-- results in: '["a", "b", "c"]' -->

{{sortBy}}

Sort an array. If an array of objects is passed, you may optionally pass a key to sort on as the second argument. You may alternatively pass a sorting function as the second argument.

Params

  • array {Array}: the array to sort.

  • props {String|Function}: One or more properties to sort by, or sorting functions to use.

Example

<!-- array: [{a: 'zzz'}, {a: 'aaa'}] -->

{{sortBy array "a"}}

<!-- results in: '[{"a":"aaa"}, {"a":"zzz"}]' -->

{{withAfter}}

Use the items in the array after the specified index as context inside a block. Opposite of withBefore.

Params

  • array {Array}

  • idx {Number}

  • options {Object}

  • returns {Array}

Example

<!-- array: ['a', 'b', 'c', 'd', 'e'] -->

{{#withAfter array 3}}  {{this}}{{/withAfter}}

<!-- results in: "de" -->

{{withBefore}}

Use the items in the array before the specified index as context inside a block. Opposite of withAfter.

Params

  • array {Array}

  • idx {Number}

  • options {Object}

  • returns {Array}

Example

<!-- array: ['a', 'b', 'c', 'd', 'e'] -->

{{#withBefore array 3}}  {{this}}{{/withBefore}}

<!-- results in: 'ab' -->

{{withFirst}}

Use the first item in a collection inside a handlebars block expression. Opposite of withLast.

Params

  • array {Array}

  • idx {Number}

  • options {Object}

  • returns {String}

Example

<!-- array: ['a', 'b', 'c'] -->

{{#withFirst array}}  {{this}}{{/withFirst}}

<!-- results in: 'a' -->

{{withGroup}}

Block helper that groups array elements by given group size.

Params

  • array {Array}: The array to iterate over

  • size {Number}: The desired length of each array "group"

  • options {Object}: Handlebars options

  • returns {String}

Example

<!-- array: ['a','b','c','d','e','f','g','h'] -->

{{#withGroup array 4}}  
{{#each this}} {{.}}  {{each}}  <br>{{/withGroup}}

<!-- results in: -->
<!-- 'a','b','c','d'<br> -->
<!-- 'e','f','g','h'<br> -->

{{withLast}}

Use the last item or n items in an array as context inside a block. Opposite of withFirst.

Params

  • array {Array}

  • idx {Number}: The starting index.

  • options {Object}

  • returns {String}

Example

<!-- array: ['a', 'b', 'c'] -->
{{#withLast array}}  {{this}}{{/withLast}}
<!-- results in: 'c' -->

{{withSort}}

Block helper that sorts a collection and exposes the sorted collection as context inside the block.

Params

  • array {Array}

  • prop {String}

  • options {Object}: Specify reverse="true" to reverse the array.

  • returns {String}

Example

<!-- array: ['b', 'a', 'c'] -->

{{#withSort array}}{{this}}{{/withSort}}

<!-- results in: 'abc' -->

{{unique}}

Block helper that return an array with all duplicate values removed. Best used along with a each helper.

Params

  • array {Array}

  • options {Object}

  • returns {Array}

Example

<!-- array: ['a', 'a', 'c', 'b', 'e', 'e'] -->

{{#each (unique array)}}{{.}}{{/each}}

<!-- results in: 'acbe' -->
Comparison helpers

{{and}}

Helper that renders the block if both of the given values are truthy. If an inverse block is specified it will be rendered when falsey. Works as a block helper, inline helper or subexpression.

Params

  • a {any}

  • b {any}

  • options {Object}: Handlebars provided options object

  • returns {String}

Example

<!-- {great: true, magnificent: true} -->

{{#and great magnificent}}A{{else}}B{{/and}}

<!-- results in: 'A' -->

{{compare}}

Render a block when a comparison of the first and third arguments returns true. The second argument is the arithemetic operator to use. You may also optionally specify an inverse block to render when falsey.

Params

  • a {}

  • operator {}: The operator to use. Operators must be enclosed in quotes: ">", "=", "<=", and so on.

  • b {}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or if specified the inverse block is rendered if falsey.

{{contains}}

Block helper that renders the block if collection has the given value, using strict equality (===) for comparison, otherwise the inverse block is rendered (if specified). If a startIndex is specified and is negative, it is used as the offset from the end of the collection.

Params

  • collection {Array|Object|String}: The collection to iterate over.

  • value {any}: The value to check for.

  • [startIndex=0] {Number}: Optionally define the starting index.

  • options {Object}: Handlebars provided options object.

Example

<!-- array = ['a', 'b', 'c'] -->

{{#contains array "d"}}  This will not be rendered.{{else}}  This will be rendered.{{/contains}}

{{default}}

Returns the first value that is not undefined, otherwise the "default" value is returned.

Params

  • value {any}

  • defaultValue {any}

  • returns {String}

{{eq}}

Block helper that renders a block if a is equal to b. If an inverse block is specified it will be rendered when falsey. You may optionally use the compare="" hash argument for the second value.

Params

  • a {String}

  • b {String}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

Example

{
"state":"California"
}

<html>

	{{#if (eq state "California")}} 
	<p>Welcome to Cali</p>
	{{else}}
	<p>You\\'re not in California</p>
	{{/if}}

</html>;
<!-- Results in 'Welcome to Cali' →

{{gt}}

Block helper that renders a block if a is greater than b.

If an inverse block is specified it will be rendered when falsey. You may optionally use the compare="" hash argument for the second value.

Params

  • a {String}

  • b {String}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

{{gte}}

Block helper that renders a block if a is greater than or equal to b.

If an inverse block is specified it will be rendered when falsey. You may optionally use the compare="" hash argument for the second value.

Params

  • a {String}

  • b {String}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

{{has}}

Block helper that renders a block if value has pattern. If an inverse block is specified it will be rendered when falsey.

Params

  • val {any}: The value to check.

  • pattern {any}: The pattern to check for.

  • options {Object}: Handlebars provided options object

  • returns {String}

{{isFalsey}}

Returns true if the given value is falsey. Uses the falsey library for comparisons. Please see that library for more information or to report bugs with this helper.

Params

  • val {any}

  • options {Options}

  • returns {Boolean}

{{isTruthy}}

Returns true if the given value is truthy. Uses the falsey library for comparisons. Please see that library for more information or to report bugs with this helper.

Params

  • val {any}

  • options {Options}

  • returns {Boolean}

{{ifEven}}

Return true if the given value is an even number.

Params

  • number {Number}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

Example

{{#ifEven value}}  render A{{else}}  render B{{/ifEven}}

{{ifNth}}

Conditionally renders a block if the remainder is zero when a operand is divided by b. If an inverse block is specified it will be rendered when the remainder is not zero.

Params

  • {}: {Number}

  • {}: {Number}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

{{ifOdd}}

Block helper that renders a block if value is an odd number. If an inverse block is specified it will be rendered when falsey.

Params

  • value {Object}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

Example

{{#ifOdd value}}  render A{{else}}  render B{{/ifOdd}}

{{is}}

Block helper that renders a block if a is equal to b. If an inverse block is specified it will be rendered when falsey. Similar to eq but does not do strict equality.

Params

  • a {any}

  • b {any}

  • options {Object}: Handlebars provided options object

  • returns {String}

{{isnt}}

Block helper that renders a block if a is not equal to b. If an inverse block is specified it will be rendered when falsey. Similar to unlessEq but does not use strict equality for comparisons.

Params

  • a {String}

  • b {String}

  • options {Object}: Handlebars provided options object

  • returns {String}

{{lt}}

Block helper that renders a block if a is less than b.

If an inverse block is specified it will be rendered when falsey. You may optionally use the compare="" hash argument for the second value.

Params

  • context {Object}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

{{lte}}

Block helper that renders a block if a is less than or equal to b.

If an inverse block is specified it will be rendered when falsey. You may optionally use the compare="" hash argument for the second value.

Params

  • a {Sring}

  • b {Sring}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

{{neither}}

Block helper that renders a block if neither of the given values are truthy. If an inverse block is specified it will be rendered when falsey.

Params

  • a {any}

  • b {any}

  • options {}: Handlebars options object

  • returns {String}: Block, or inverse block if specified and falsey.

{{not}}

Returns true if val is falsey. Works as a block or inline helper.

Params

  • val {String}

  • options {Object}: Handlebars provided options object

  • returns {String}

{{or}}

Block helper that renders a block if any of the given values is truthy. If an inverse block is specified it will be rendered when falsey.

Params

  • arguments {...any}: Variable number of arguments

  • options {Object}: Handlebars options object

  • returns {String}: Block, or inverse block if specified and falsey.

Example

{{#or a b c}}  If any value is true this will be rendered.{{/or}}

{{unlessEq}}

Block helper that always renders the inverse block unless a is equal to b.

Params

  • a {String}

  • b {String}

  • options {Object}: Handlebars provided options object

  • returns {String}: Inverse block by default, or block if falsey.

{{unlessGt}}

Block helper that always renders the inverse block unless a is greater than b.

Params

  • a {Object}: The default value

  • b {Object}: The value to compare

  • options {Object}: Handlebars provided options object

  • returns {String}: Inverse block by default, or block if falsey.

{{unlessLt}}

Block helper that always renders the inverse block unless a is less than b.

Params

  • a {Object}: The default value

  • b {Object}: The value to compare

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

{{unlessGteq}}

Block helper that always renders the inverse block unless a is greater than or equal to b.

Params

  • a {any}

  • b {any}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

{{unlessLteq}}

Block helper that always renders the inverse block unless a is less than or equal to b.

Params

  • a {any}

  • b {any}

  • options {Object}: Handlebars provided options object

  • returns {String}: Block, or inverse block if specified and falsey.

String helpers

{{append}}

Append the specified suffix to the given string.

Params

  • str {String}

  • suffix {String}

  • returns {String}

Example

<!-- given that "item.stem" is "foo" -->

{{append item.stem ".html"}}

<!-- results in:  'foo.html' -->

{{camelcase}}

camelCase the characters in the given string.

Params

  • string {String}: The string to camelcase.

  • returns {String}

Example

{{camelcase "foo bar baz"}};<!-- results in:  'fooBarBaz' -->

{{capitalize}}

Capitalize the first word in a sentence.

Params

  • str {String}

  • returns {String}

Example

{{capitalize "foo bar baz"}}

<!-- results in:  "Foo bar baz" -->

{{capitalizeAll}}

Capitalize all words in a string.

Params

  • str {String}

  • returns {String}

Example

{{capitalizeAll "foo bar baz"}}

<!-- results in:  "Foo Bar Baz" -->

{{center}}

Center a string using non-breaking spaces

Params

  • str {String}

  • spaces {String}

  • returns {String}

{{chop}}

Like trim, but removes both extraneous whitespace and non-word characters from the beginning and end of a string.

Params

  • string {String}: The string to chop.

  • returns {String}

Example

{{chop "_ABC_"}}

<!-- results in:  'ABC' --> 

{{chop "-ABC-"}}

<!-- results in:  'ABC' --> 

{{chop " ABC "}}

<!-- results in:  'ABC' -->

{{dashcase}}

dash-case the characters in string. Replaces non-word characters and periods with hyphens.

Params

  • string {String}

  • returns {String}

Example

{{dashcase "a-b-c d_e"}}

<!-- results in:  'a-b-c-d-e' -->

{{dotcase}}

dot.case the characters in string.

Params

  • string {String}

  • returns {String}

Example

{{dotcase "a-b-c d_e"}}

<!-- results in:  'a.b.c.d.e' -->

{{downcase}}

Lowercase all of the characters in the given string. Alias for lowercase.

Params

  • string {String}

  • returns {String}

Example

{{downcase "aBcDeF"}}

<!-- results in:  'abcdef' -->

{{ellipsis}}

Truncates a string to the specified length, and appends it with an elipsis, ….

Params

  • str {String}

  • length {Number}: The desired length of the returned string.

  • returns {String}: The truncated string.

Example

{{ellipsis (sanitize "<span>foo bar baz</span>"), 7}}

<!-- results in:  'foo bar…' -->{{ellipsis "foo bar baz", 7}}

<!-- results in:  'foo bar…' -->

{{hyphenate}}

Replace spaces in a string with hyphens.

Params

  • str {String}

  • returns {String}

Example

{{hyphenate "foo bar baz qux"}}

<!-- results in:  "foo-bar-baz-qux" -->

{{isString}}

Return true if value is a string.

Params

  • value {String}

  • returns {Boolean}

Example

{{isString "foo"}}

<!-- results in:  'true' -->

{{lowercase}}

Lowercase all characters in the given string.

Params

  • str {String}

  • returns {String}

Example

{{lowercase "Foo BAR baZ"}}

<!-- results in:  'foo bar baz' -->

{{occurrences}}

Return the number of occurrences of substring within the given string.

Params

  • str {String}

  • substring {String}

  • returns {Number}: Number of occurrences

Example

{{occurrences "foo bar foo bar baz" "foo"}}

<!-- results in:  2 -->

{{pascalcase}}

PascalCase the characters in string.

Params

  • string {String}

  • returns {String}

Example

{{pascalcase "foo bar baz"}}

<!-- results in:  'FooBarBaz' -->

{{pathcase}}

path/case the characters in string.

Params

  • string {String}

  • returns {String}

Example

{{pathcase "a-b-c d_e"}}

<!-- results in:  'a/b/c/d/e' -->

{{plusify}}

Replace spaces in the given string with pluses.

Params

  • str {String}: The input string

  • returns {String}: Input string with spaces replaced by plus signs

Example

{{plusify "foo bar baz"}}

<!-- results in:  'foo+bar+baz' -->

{{prepend}}

Prepends the given string with the specified prefix.

Params

  • str {String}

  • prefix {String}

  • returns {String}

Example

<!-- given that "val" is "bar" -->

{{prepend val "foo-"}}

<!-- results in:  'foo-bar' -->

{{raw}}

Render a block without processing mustache templates inside the block.

Params

  • options {Object}

  • returns {String}

Example

{{{{#raw}}}}{{foo}}{{{{/raw}}}}

<!-- results in:  '{{foo}}' -->

{{remove}}

Remove all occurrences of substring from the given str.

Params

  • str {String}

  • substring {String}

  • returns {String}

Example

{{remove "a b a b a b" "a "}}

<!-- results in:  'b b b' -->

{{removeFirst}}

Remove the first occurrence of substring from the given str.

Params

  • str {String}

  • substring {String}

  • returns {String}

Example

{{remove "a b a b a b" "a"}}

<!-- results in:  ' b a b a b' -->

{{replace}}

Replace all occurrences of substring a with substring b.

Params

  • str {String}

  • a {String}

  • b {String}

  • returns {String}

Example

{{replace "a b a b a b" "a" "z"}}

<!-- results in:  'z b z b z b' -->

{{replaceFirst}}

Replace the first occurrence of substring a with substring b.

Params

  • str {String}

  • a {String}

  • b {String}

  • returns {String}

Example

{{replace "a b a b a b" "a" "z"}}

<!-- results in:  'z b a b a b' -->

{{reverse}}

Reverse a string.

Params

  • str {String}

  • returns {String}

Example

{{reverse "abcde"}}

<!-- results in:  'edcba' -->

{{sentence}}

Sentence case the given string

Params

  • str {String}

  • returns {String}

Example

{{sentence "hello world. goodbye world."}}

<!-- results in:  'Hello world. Goodbye world.' -->

{{snakecase}}

snake_case the characters in the given string.

Params

  • string {String}

  • returns {String}

Example

{{snakecase "a-b-c d_e"}}

<!-- results in:  'a_b_c_d_e' -->

{{split}}

Split string by the given character.

Params

  • string {String}: The string to split.

  • returns {String} character: Default is an empty string.

Example

{{split "a,b,c" ","}}

<!-- results in:  ['a', 'b', 'c'] -->

{{startsWith}}

Tests whether a string begins with the given prefix.

Params

  • prefix {String}

  • testString {String}

  • options {String}

  • returns {String}

Example

{{#startsWith "Goodbye" "Hello, world!"}}  
Whoops{{else}}  Do you even hello world?
{{/startsWith}}

{{titleize}}

Title case the given string.

Params

  • str {String}

  • returns {String}

Example

{{titleize "this is title case"}}

<!-- results in:  'This Is Title Case' -->

{{trim}}

Removes extraneous whitespace from the beginning and end of a string.

Params

  • string {String}: The string to trim.

  • returns {String}

Example

{{trim " ABC "}}

<!-- results in:  'ABC' -->

{{trimLeft}}

Removes extraneous whitespace from the beginning of a string.

Params

  • string {String}: The string to trim.

  • returns {String}

Example

{{trim " ABC "}}

<!-- results in:  'ABC ' -->

{{trimRight}}

Removes extraneous whitespace from the end of a string.

Params

  • string {String}: The string to trim.

  • returns {String}

Example

{{trimRight " ABC "}}

<!-- results in:  ' ABC' -->

{{truncate}}

Truncate a string to the specified length. Also see ellipsis.

Params

  • str {String}

  • limit {Number}: The desired length of the returned string.

  • suffix {String}: Optionally supply a string to use as a suffix to denote when the string has been truncated. Otherwise an ellipsis (…) will be used.

  • returns {String}: The truncated string.

Example

truncate("foo bar baz", 7);

<!-- results in:  'foo bar' -->

truncate(sanitize("<span>foo bar baz</span>", 7));

<!-- results in:  'foo bar' -->

{{truncateWords}}

Truncate a string to have the specified number of words. Also see truncate.

Params

  • str {String}

  • limit {Number}: The desired length of the returned string.

  • suffix {String}: Optionally supply a string to use as a suffix to denote when the string has been truncated.

  • returns {String}: The truncated string.

Example

truncateWords("foo bar baz", 1);

<!-- results in:  'foo…' -->truncateWords("foo bar baz", 2);

<!-- results in:  'foo bar…' -->truncateWords("foo bar baz", 3);

<!-- results in:  'foo bar baz' -->

{{upcase}}

Uppercase all of the characters in the given string. Alias for uppercase.

Params

  • string {String}

  • returns {String}

Example

{{upcase "aBcDeF"}}

<!-- results in:  'ABCDEF' -->

{{uppercase}}

Uppercase all of the characters in the given string. If used as a block helper it will uppercase the entire block. This helper does not support inverse blocks.

Params

  • str {String}: The string to uppercase

  • options {Object}: Handlebars options object

  • returns {String}

Example

{{uppercase "aBcDeF"}}

<!-- results in:  'ABCDEF' -->
  • array {Array}: The array to iterate over

  • size {Number}: The desired length of each array "group"

  • options {Object}: Handlebars options

  • returns {String}