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 or with third-party lists, make sure that you create targeted mailing lists with select attributes to maximize your responses and channel ROI.
Easily in ,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 functionality to reduce bad addresses, or incorporate Lob's product to fully ensure your mail data is as accurate as possible to maximize your intended reach.
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 via to get a feel for intelligent direct mail.
Explore our APIs! Check out our to explore our in your preferred programming language, explore our our , and go to 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 to create mail pieces that can truly resonate with your audience
Experiment with different and to see how to best increase relevance and conversion
Ingest data, set up notification alerts via , or add to improve attribution and reporting
Enrich your data, connections, and processes
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, .
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 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.
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
For more support related to our SFMC API integration, please contact your Account Manager or to discuss your requirements and use case.
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.
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 the guidebooks below to get started!
Past acceptance/approval in prior year promotion does not guarantee acceptance/approval in current year promotions. Refer to each promotion for enrollment and acceptance criteria.
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 , 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
- 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.
- 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 .
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
- 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.
- 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.
PDF
- Here are some design layout and dimension guides you’ll want to keep in mind.
- Learn more about formatting and ensuring your .
Step 4: How do you plan to measure the success of your mail?
Lob dashboard
- 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.
- 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.
Custom analytics
- Leverage webhook functionality to take asynchronous action and enhance your line of sight for the mail that is requested.
- Gain a deeper understanding of your mail data at a mail piece, recipient, batch, or campaign level by adding your own data labels.
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 .
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.
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:
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. .
Alternatively, , and make magic happen automatically in Lob.
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.
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.
Instructions on how to connect Blueshift and Lob can be found in .
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.
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.
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.
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.
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.
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.
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.
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.)
Tactile, Sensory & Interactive Promotion
What is the 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.
Custom mail
As a direct mail automation platform, Lob's focus is to offer 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.
Technical use case guides
The following guides are intended to provide an in-depth walkthrough of some of Lob's product features that customers can use to accomplish their business needs.
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.
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.
Lob & Optimove: In episode 21 of the Lob Podcast, we sat down with Pini Yakuel, Founder and CEO of Optimove, to discuss how marketers can embrace AI to create successful marketing campaigns.
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.
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
Metadata - Gain a deeper understanding of your mail data at a mail piece, recipient, batch, or campaign level by adding your own data labels.
When you send an API request to Lob, you are sending 3 pieces of information:
the "To" address,
the "From" address, and
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.
We offer 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.
Our creative conversion tools are in beta and subject to change we ask that you reach out to your Account Manager or contact us for access and support.
Image resolution should be 300 dpi
for the best print quality; the video will walk you through adjusting the resolution.
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.
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.
Keep your file size under5MB. 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.
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”. See our full PDF preflight checklist here.
When is the Tactile, Sensory, and Interactive Promotion live?
The promotion runs from January 1, 2026, to June 30, 2026.
How can I take advantage of the Tactile, Sensory, and Interactive Promotion through Lob?
By opting into the satin-finish or grooved envelopes (or both), these elements engage the senses, create a stronger connection with your audience and save money.
Here’s everything you need to know to qualify for a 5% discount.
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 .
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
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.
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 . You may similarly opt for an electronic return receipt by passing certified_return_receipt in the extra_services parameter in the .
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 .
Visit the for more guidance around sending Certified Mail.
Electronic Return Receipts
An Electronic Return Receipt is available to the sender as a USPS 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 .
The return receipt will be accessible via the certified tracking number from the . However, if you would like to receive the signature PDF via email, follow these steps:
Visit
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 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 .
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.
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.
Snap packs 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.
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
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 existing customer database, and can augment your first-party data with additional datasets to increase reach.
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.
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!
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.
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?
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.
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.
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
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.
Upgrading API version
When backward-incompatible changes are made to the API, a new dated version is released. You can view your current version in your dashboard settings.
Any API version prior to 2020-02-11 has been sunsetted.
It is recommended that when you are ready to upgrade your API version to the current version, you should add the version to your requests in the HTTP header as shown in the API documentation and then attempt test requests to ensure your integration will not break upon fully upgrading.
Once testing is complete, you can go into your dashboard and make the full upgrade. After that is complete, you should remove the Lob version header from your requests to ensure all your requests use your global version.
You will only need to specify a version if you would like to test a newer version of the API without doing a full upgrade. The API will return an error if a version older than your current one is passed in.
For more information about versioning see .
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
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
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
Mail piece design specs
Browse our available mail formats and associated design specs:
Visibility of address changes
When sending mail or using Address Verification through Lob, addresses can be altered to match USPS requirements. This includes performing actions such as standardization, fixing typos like wrong zip codes, etc. These changes are surfaced back up to you, and if needed you can see the changes made.
Why is this important?
Some companies may want to update their addresses to what we return when standardizing and correcting—however, some may also want to log what we changed. This could be important for compliance reasons as well as customer experience; showing your end users what was changed could be a very nice touch in your workflow.
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
AV FAQs
What are some address verification use cases?
Some customers love to use our address verification API to ensure addresses are accurate, deliverable and USPS standardized. Others love to use it for front-end autocompletion and to practice good data hygiene to prevent downstream bottlenecks. The possibilities are endless!
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.
A sophisticated data integration and governance platform, managing your entire customer data ecosystem
Government agencies
Utility companies
Mail service providers
Legal service providers
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.
How often does Lob update their Address Verification API?
It depends! For US verifications, our API updates on the 15th of every month, in accordance with USPS’s update schedule. For international verifications, our API updates in accordance with that specific country’s update schedule. For the update schedule by country, check out our Global Address Coverage page.
Why are my verified addresses returning in capital letters?
By default Lob returns addresses in uppercase, to adhere with USPS' preference. If you prefer proper case you can configure this by changing the [case] to "proper." Changing the case is only available to users sending in API requests programmatically. For more information, check our docs.
How do I keep track of the amount of verifications I’ve done?
If you want to check how many verifications you completed in a given timeframe, there are two ways to get this done:
Look at the Overview tab once you sign in to your Lob Dashboard and hover over the chart below the “API REQUESTS (BY CREATION DATE)” section. If you want to customize the time frame, then select a Start and End date, and hover over the chart for date or month-specific verification information.
If you also want to see current month per-piece pricing:
Log in to your Lob Dashboard and click on Billing in the left navigation menu.
Click on “Editions”
Select the product you’d like to review usage for Select the product you’d like to review usage for
You should be able to see your usage settings under the “Current Month Usage”
Why is my address undeliverable?
There are various reasons an address can be deemed undeliverable, roughly grouped into four buckets below.
The full list of detailed definitions for various fields in the US Verification object can be found in our API docs.
Why did my address verification fail when Google Maps was able to successfully find it?
Our API focuses on whether or not addresses are valid delivery points for receiving mail. Google Maps focuses on locality and walking/driving directions, and therefore should not be relied on for verifying the validity of a mailing address. An address that can be located on a map is not necessarily an officially recognized address by the USPS.
What are the rate limits for the Address Verification API?
US and international verification of a single address (v1/us_verifications and v1/intl_verifications) allow 300 API calls per 5 second interval.
However, our bulk endpoints for US and interational verification have the following rate limits:
US bulk verifications (v1/bulk/us_verifications) — 70 API calls per 10 second interval, passing a maximum of 20 addresses per API call
International bulk verifications (v1/bulk/intl_verifications) — 30 API calls per 10 second interval, passing a maximum of 20 addresses per API call
HIPAA-compliant snap packs are offered at this time, so long as all HIPAA related information is on the inside of the snap pack.
Mailing Class 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. Learn more here.
See our most up-to-date list of global address coverage 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 API documentation 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 supportto 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 API documentation 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 API documentation under Coverage.
As a default, Lob mail will be immediately sent and routed to production after the customer submits a mail order, pending any cancellation rules 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 Tracking your mail on how to track individual mail pieces at each step of the production and delivery process, and see webhooks on setting up and surfacing mail tracking notifications.
Scheduled mailings for a future date
Scheduled Mailings is available only to Enterprise edition customers. Contact Sales 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 cancellation window set for the resource you are creating, passing a send_date will override that window. For more detailed request information, see our API documentation.
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 cancel those requests as long as the mailing's send_date has not passed. Additionally, you can cancel a mailing from your dashboard on the page associated with your mail piece.
Target delivery date
Target Delivery is under development; contact Sales 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 withTarget 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.
with regular, bold, and regular-italic variations.
🍎 On a Mac:
Open Finder.
Press Cmd + Shift + G.
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):
Open File Explorer.
Navigate to:
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 Stylesheet (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
The way to do this today is to do a string comparison and see what we altered. For example, you will need to compare the address you passed to Lob with the address we returned back. With our AV product, you can retrieve more granular information without having to split out the address data on your own. For example, if you passed in "street" and in the API response you received "ST" in the "Street Suffix" field, you would know that was the specific change. If the "Street Name" was corrected you would see that split out as well. Otherwise, you can compare the full address and pull out the changes from there.
This leaves a lot of room for customization on business logic to determine what is important to your team when classifying something as a change. Oftentimes a change like “Street” to “St '' is not something the business team wants to be surfaced. It’s these types of business rules that are important when handling these alterations.
Below is an example of creating a postcard and comparing the to address input with the to address response to identify changes.
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 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.
Create and open a blank design template.
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
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:
Mark dynamic text with double brackets. e.g. {{first_name}}
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.
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.
Open the plugin and click "Export your mail design"
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.
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.
For those using custom fonts (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 .
If you have any questions on the plugin, contact your CSM or reach out to . Happy designing!
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.
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
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.
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; see a response sample here.
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.
Ifyou 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.
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.
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
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:
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
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.
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.
Add-Ons
Informed Delivery
What is the Informed Delivery add-on?
Informed Delivery by USPS enhances the traditional mail experience by providing subscribers with a
If your addresses are returning as undeliverable, refer to the various fields in the US verification object in our API reference 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 verified. See our API reference for more details.
Use of the US Autocomplete API is included with every Address Verification subscription. See our pricing page for different Address Verification editions 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 API reference 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 API reference 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.
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 API reference under the JSON object lob_confidence_scorefor more details.
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
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.
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.
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.)
Under Webhooks in the dashboard, in the Live environment, click Create.
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]
Template Gallery for ready-to-use creatives and design inspiration
Self-mailer formats
Layout dimensions & specs
Layout dimensions
Lob currently supports the following self-mailers:
6x18” bifold template: measures 6x9” when folded in half, no offset of panels, and unfolds horizontally
12x9” bifold template: measures 6x9” when folded in half, no offset of panels, and unfolds vertically
11x9" bifold template: 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 ink-free zone 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
11x9" bifold self-mailer
W x H: 4 x 2.375"
0.15" from the center fold line
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)
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 Carbon Neutral Mail 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 no-ink zone
Avoid any prohibited artwork 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.
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 Lob’s Address Cleanser 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 Lob Address Cleanser app, and you’ll see two options for you to submit payment:
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.
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 Lob’s Address Cleanser 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.
You may also add QR codes 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 Carbon Neutral Mail 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
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.
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 fora less technical lift, you can automate your sends directly from the Lob dashboard.
daily email preview
of their incoming mail. 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.
As of March 2025, 72.9 million mail recipients are subscribed to USPS’s Informed Delivery program.
In order to qualify for the Informed Delivery Add-On, your mailpiece must be approved for an active base promotion on the date of mailing.
Here’s everything you need to know to qualify for an additional 1% discount.
How can I sign up for Informed Delivery through Lob?
Opt-in to the promotion
To get started, log into the Lob Promotions Portal:
You can send an Informed Delivery campaign via API or Campaigns in Lob.
Option 1: Send via API
POST campaign data:
Use the Lob API to send the informed_delivery_campaign and retrieve a campaign_id.
Include required fields:
Promotional URL
Campaign size
Optional fields:
Brand name: Defaults to the company name in Lob unless specified.
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.
Validate campaign:
After a successful POST, receive the campaign_id and confirm qualification for existing promotions.
Send mail:
Include the informed_delivery_campaign_id in your submission to Lob as usual.
Option 2: Send via Lob Campaigns
Set up campaign:
Begin your campaign setup in Lob Campaigns.
Enable Informed Delivery:
When prompted, select the option to use Informed Delivery.
Choose from available approved promotions obtained in Step 1.
Enter campaign details:
Promotional URL
Upload the Ride-Along Image.
Ride-Along Image specifications:
Format: JPG
Dimensions: 500x780 pixels
Optional fields:
Brand name: Appears in the Informed Delivery email sent to subscribers. Defaults to your company name in Lob unless customized.
Representative image: A sample of your mailpiece (similar rules as for API campaigns apply).
Launch campaign:
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 add-on.
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.
Please be sure to note that because you are ultimately responsible for ensuring compliance with all applicable laws and regulations, Lob can't offer guidance on the legality of your mailpieces and their content. For any questions of that nature, we always recommend consulting with the USPS and/or a qualified attorney.
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
Unsupported fonts
OTF ( into another type we support)
Type 1 fonts(Exception: standard base14 fonts)
Type 3 fonts
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.
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.
All about addresses
Anatomy of a mailpiece
When you send an API request to Lob, you are sending 3 pieces of information:
the "To" address,
the "From" address, and
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:
Name (or attention)
Company* (if applicable)
Delivery address: Line 1, and Line 2* (if applicable)
Items marked with a * are optional.
For more details on character limits etc., reference our or see the 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 or you can leverage the address_id to 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 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 and , 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 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 to ensure your addresses are standardized before any mail is sent.
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.
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 .
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 .
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 . There are three possible strictness levels: Strict, Normal, and Relaxed.
Learn more about the importance of 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 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.
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 followinguse 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 . 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 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 (, , , or ).
Example: Use Type selection when creating a new 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.
Example: POST /v1/postcards request with use_type included
3. Setting use types for each campaign
The Campaigns product is designed to help send large volumes of mail quickly, either through the or .
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 “” 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 , 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
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 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 anaccount default as a fall-back option as soon as possible
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".
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 . Letters and checks over 6 sheets of paper but not exceeding 60 total sheets of paper will be mailed in a .
Reference our design templates on where to place your design elements for letters; carefully note the placement of the address block.
(for 6 sheets of paper or less)
(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 to gain access to this mail format, or reach out to our 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.
(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
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 (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 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 for privacy
options may differ based on the destination and use case (e.g. promotional vs transactional)
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.
Mailing Classes & Postage
Mailing classes categorize mail based on factors like speed, cost, and content, determining how a mailpiece is handled by the U.S. Postal Service. Through Lob, you can take advantage of different mailing class options to reflect your business priorities
Important: via its Domestic Mail Manual (DMM), the U.S. Postal Service imposes certain standards for mail preparation and content. Such standards include requirements for sending mail containing personal information. Because violations of the DMM can result in mail being pulled from the mailstream and/or other penalties, Lob strongly recommends you review the DMM and consult your legal counsel with any questions or concerns.
First Class Mail
Used to send Lob postcards, self-mailers, letters, and checks
Intended mostly for personal or business correspondence
Option of add additional services, like Certified Mail
Must weigh 13oz or less; anything over 13oz can be sent as Priority Mail
Delivery is given priority over Standard Class Mail, both locally & nationally
Includes forwarding and return services with no additional charge
First Class domestic mail takes 5-7 business days to deliver and international mailings take an additional 5 to 7 business days.
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
Available mailing class options
Postcards
4x6, 6x9 and 6x11 postcards: Mailed via USPS First Class Mail (takes 5-7 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 5-7 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 5-7 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 and is predicated on automated production, dynamically-adjusted throughput, and consistency of quality that is on-demand and at scale. 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 integrated into our PDN ecosystem, enabling customers to easily access different mail delivery strategies.
Mail sent through Lob is dynamically distributed to the printers within our PDN, based on a number of factors, including:
Mail form factor and permutation availability
Mail volume capacity
Mail Content
If you're a printer that's interested in working with us, !
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
Exporting your data from the Lob dashboard
to your Lob dashboard.
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 (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
Video walkthrough
If you have any questions regarding exporting your data, reach out to your Customer Success Manager or to .
Integrated Technology Promotion
What is the USPS Integrated Technology promotion?
The Integrated Technology promotion bridges the gap between physical and digital marketing by incorporating cutting-edge tools that engage consumers in new and exciting ways.
Four key USPS Integrated Technology experiences are available through Lob:
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.
Artificial intelligence: Use generative AI to craft compelling copy or visuals to meet your campaign goals.
Voice assistant integration: Encourage interactions through voice prompts to guide exploration.
Augmented reality (AR): Create immersive experiences that blend physical and digital with 3D images.
Please refer to the to ensure that the mail piece meets all the 2026 Program Requirements.
When is the USPS Integrated Technology promotion live?
Lob will be supporting this promotion from July 1, 2026 to December 31, 2026.
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.
Here’s everything you need to know to qualify for a 5% discount.
Opt-in to the promotion
To get started, log into the Lob Promotions Portal:
https://dashboard.lob.com/promotions/available-promotions
Select the Available Promotion
Opt-In for the Tactile, Sensory, Interactive Engagement Promotion
Select your technology feature
Upload PDF of your mailpiece
Validate Promotion approval
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.
AI
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.
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.
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:
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.
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
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 .
The tools
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?
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 : 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.
Custom fonts within your HTML templates (any links must be accessible to Lob)
Adobe (Typekit) 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.)
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.
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
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
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.
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.
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.
Log into the Lob Dashboard; navigate to Billing > Promotions. Click on "Create an Informed Delivery Promotion."
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.
On successful POST, receive a campaign_id and validation if it qualifies for an existing promotion.
Once validated, send your mail as usual, including the usps_campaign_id in your submission.
Send via Campaigns
Begin your campaign setup as usual in Lob Campaigns.
When prompted, select the option to use Informed Delivery.
Choose from available approved Informed Delivery Promotions (Procured in Step 1).
Ride-along image specifications: JPG, 500x780px, max file size of 200KB.
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.
Please look over the uploaded images and make sure all information is correct.
Click "Next Step" to proceed with the Campaigns worklflow.
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.
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)
Test environment data export with no tracking events
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 account and you have already registered with (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
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 .
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 in your Lob account settings, and you can use a 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:
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 .
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.
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": “"
"back": ""
For more about designing/formatting creative for Lob, .
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 yourLIVE 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 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
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
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.
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 Salesforce, 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.
Set up the integration
First things first!
Download this JSON file (Lob OpenAPI specs) to use in Step 2.
Step 1: Set up a Named Credential
First, create a new legacy credential for Lob.com in Salesforce.
Give it a label, a name, and set the URL field to
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 .
Step 2: Create an External Service
Next, go to the External Services page and create a new External Service from API specification.
Fill in an External Service Name, an optional Description, then select "Complete JSON" for Service Schema, and select the Named Credential you just created.
In the JSON field, paste the entirety of the Lob OpenAPI specs you downloaded.
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.)
Create a new Flow Trigger explorer and set it as an Actions and Related Records type.
Choose the object field and configure it for when the record is created or updated. (Ensure that Actions and Related Records is selected.)
Add a Scheduled Path called "zero hour delay" and set it to 0 hours after the record is created.
Next, create a new resource called "postcard_payload" with the data type as Apex defined and set it to postcard editable.
Use the Assignment node to map the required fields for creating a mail piece in Lob.
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.
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.
Map the "postcard_payload" resource to the "body" field in the Action.
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.
You can edit the Decision:
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)
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:
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.
SOQL Queries: Salesforce imposes a limit on the number of SOQL (Salesforce Object Query Language) queries that can be executed per transaction.
DML Operations: There's also a limit on the number of DML (Data Manipulation Language) operations like INSERT
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 .
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: section or
for sample design inspiration and template
Booklets are exclusive to Enterprise edition customers. Upgrade your to gain access to this mail format, or reach out to our 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.
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)
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
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.
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).
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 , 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
HIPAA-compliant booklets are not offered at this time, as booklets are not placed in envelopes
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.
First Class Mail Advertising
What is the First-Class Mail Advertising promotion?
The First-Class Mail Advertising promotion offers businesses a unique opportunity to blend the reliability and prestige of First-Class Mail with impactful advertising. 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.
When is this promotion live?
The First-Class Marketing Mail promotion runs from September 1, 2026, to December 31, 2026.
How can I take advantage of the First-Class Advertising Mail promotion with Lob?
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.
Discount offer example: “Save 10% on your next purchase with this exclusive coupon!”
Limited-time offer example: “Act now! This offer expires in 7 days.”
Here’s everything you need to know to qualify for a 5% discount.
Opt-in to the promotion
To get started, log into the Lob Promotions Portal:
1. Select the Available Promotion
2. Provide campaign title, description, and PDF of mailpiece image
3. Validate Promotional approval
Your chosen Promotion will be visible within your My Promotions section:
Artboard layout
Note: All measurements are in inches, denoted by the double prime symbol (e.g. 4"x6").
Artboard components
Iterable
Overview
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.
Send campaigns via the Campaigns API
This functionality is in beta. Please reach out to 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.
SDKs & libraries
SDKs
Currently, we have SDKs available for the following languages:
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/campaignsDocumentation: 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.
Step 2: Add creative
Endpoint: POST api.lob.com/v1/creativesDocumentation: 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.
Step 3: Map columns from your data file to specified fields
Endpoint: POST api.lob.com/v1/uploadsDocumentation: 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.
Step 4: Upload your file
Endpoint: POST api.lob.com/v1/uploads/{{upload_id}}/fileDocumentation: Upload File
After creating your upload object, you can now upload your file as a byte stream (binary file).
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.
Step 6: Get failed addresses
Endpoint: POST api.lob.com/v1/uploads/{{upload_id}}/exportsDocumentation: 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.
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.
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:
All keys and values are enclosed in double quotes (").
Commas after every key-value pair except for the last one.
No newline characters in any values and no extra spaces between fields.
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 sizes of our mail pieces and their respective print layout requirements can be found in each respective section of the Mailpiece design specs 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 crop marks 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 sustainability standard for direct mail and helping our customers and partners meet their sustainability goals. Lob has partnered with USPS to include a Carbon Neutral Mail certification 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.
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.
For any questions on our Carbon Neutral Mail certification, reach out to your CSM or [email protected].
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 address block.
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
Address block size: 2.375" x 3.2835"
Placement within red box:
From right: 1.33"
Address block size: 2.375" x 4.0"
Placement within red box:
From right: 1.33"
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.
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.
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 Intelligent Mail barcode (IMb) 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 address block (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
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.
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)
Example artboard: 4"x6" postcard
Example artboard 8.5"x11" letter
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.
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.
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:
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.
A regular job is run, resulting in mail being sent to all users who meet specific criteria.
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.
Let us know which language you’d like us to support next. Drop us an email.
Libraries
Address Elements
Address Elements works by targeting the input elements of your address form and using their values with Lob's verification and autocomplete functionality.
Create an account at Lob.com to obtain a Live Public API Key. The key is available in the Lob settings panel and uses the format, live_pub_*.
Usage
Embed the Lob Address Elements script immediately before the closing tag in the HTML containing your address form. The script will autodetect your form and its inputs.
Learn more at the repository on GitHub.
This is a very lightweight component that uses the Lob Autocomplete API in order to simplify the process of adding in a search autocomplete bar or form. Check out the Autocomplete API for more configuration options in .
Incorporating Intelligent Mail into Customer.io Workflows
Overview
Customer.io 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
Log into your . To start you’ll need your . It is highly recommended that you use your (secret) test API key first for testing.
Have a (HTML template) ready to use.
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
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.
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
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
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
Click on Add Request to begin the setup process.
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 .
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
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.
You can send a test by opening up the Request and clicking on Send Test in the top right corner.
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.
You can also check the Test Results to ensure the request fields were correctly populated by the Liquid Statements.
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 .
Start by creating a new Campaign within Customer.io and select: Create Your Own Trigger From A Webhook as the trigger.
This will generate a URL to catch the webhook. Copy that to use within Lob in the next step.
Navigate to to set up the webhook event you want to capture.
Under Create A New Webhook, enter a webhook description and paste in the URL generated by Customer.io.
Finally, select the event you want to capture in Customer.io.
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.
Mail analytics
Overview
Our Mail Analytics 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 "Mail Analytics" 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 or a mail carrying partner for fulfillment.
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 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.
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
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.
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 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 . 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 ). 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.
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.
For more specific FAQs on our Address Verification product and how it works, .
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
Note that in the 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 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 . Upgrade to the appropriate 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 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 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 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
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 for more specific information.
Generating idempotency keys
The 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 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 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:
Ruby:
Python:
Postman & similar tools
Postman is a great way for developers to get started on using Lob’s APIs. Our public workspace allows you and your team to collaborate and make sure you have everything you need to get familiar with Lob’s APIs.
Watch the video below for an overview or read through the tutorial below.
Postman: How to create & test requests, then export source code
The following will guide you through the process of using Postman to create and test requests for Lob's API and then export the source code in your chosen programming language.
Lob provides an API for automating the sending of postcards, letters, checks, and more. With the help of Postman, we can easily test Lob's API endpoints, understand their behavior, and assist with the development of a custom Lob integration by exporting source code in any modern programming language.
Requirements
Your Lob API key - Can be located under in your Lob dashboard
Step 1: Launch Postman
Once you’ve downloaded Postman, follow the installation instructions and launch the app once it’s ready.
Step 2: Create a request
Click on the "New" button located in the top left corner of the application.
From the modal that appears, select "HTTP".
Once you’ve configured your request using the instructions below, you can used the “Save” button to select a name and save the request to a collection.
Step 3: Configure your request
You will see a new tab open in Postman.
From the dropdown menu on the left of the URL bar, select the required HTTP method (GET, POST, DELETE, etc.).
Input the desired Lob API endpoint into the URL field (e.g., https://api.lob.com/v1/postcards).
To authenticate, click on the Authorization tab below the URL field. Choose “Basic Auth” ****from the Type dropdown menu. In the Username field, enter your Lob API key, leave the Password field blank.
Depending on the request type, you may need to include additional information. For example, for POST requests, navigate to the "Body" tab, select "raw" and choose "JSON" from the dropdown menu (defaulted to “Text”). Here, you can input the data for your request in JSON format.
For fields that are intended to accept only string values, submitting JSON objects in string format (stringified JSON objects) is not supported. Our system automatically parses and validates incoming data according to their expected types. As a result, providing a stringified JSON object in a field designated for string input can cause parsing errors or lead to unexpected validation results.
If you’d like to send a file in your API request (for example, a PDF file), you can do so by following the instructions below. If you do not need to send a file (e.g. if you are not sending a POST request or you are using HTML templates), you can skip this step.
a. Select the “Body” tab and toggle into “form-data”.
b. From here, you should see a table with columns labelled “Key”, “Value”, and “Description”. In the first empty row, hover on the “Key” field cell to display a dropdown selector with the default datatype option “Text” selected. Click on this dropdown and select “File”.
c. You should se a button labelled “Select Files” appear in the “Value” field cell. Click this button to open the file browser and select the file you’d like to send.
d. Ensure the “Key” cell contains the value “file” (if creating a letter) or “front”/”back” (If creating a postcard or self-mailer).
Step 4: Send your request and test the response
Click on the blue "Send" button to the right of the URL bar.
The response will be displayed in the section below the request fields.
You can review the status, time, size, and headers of the response.
Step 5: Export the source code
Click on the "Code" button located on the far right side (it should look like an empty HTML tag, i.e., ”</>”).
In the Code snippets panel that appears, select your preferred language from the dropdown on the left side.
That’s all you need to test requests for Lob's API, and export the source code in your chosen programming language!
Postman can be an invaluable part of your API development and testing workflows. Always refer to the for any API-specific information and requirements.
Other tools
Usage
cURL is used in command lines or scripts to transfer data. We've included cURL code snippets in our documentation for each resource. By including your API key, you can run these commands from the terminal and see the response from Lob's API.
Explore Lob's for more cURL examples.
USPS Mail Growth Incentive
Lob is committed to helping you maximize your ROI by taking advantage of every opportunity to save on postage costs.
While many USPS programs are available, a primary focus for many of our customers is the USPS Mail Growth Incentive. This program offers 30% credit on incremental volume that exceeds your 2025 baseline in the form of a postage credit for use on future mailings, providing a powerful way to scale your outreach while lowering your bottom line.
How We Work Together
It is important to note that the USPS requires customers to sign up for the Mail Growth Incentive independently through the USPS Business Customer Gateway. However, you aren't in this alone. Lob is here to provide the support and insight you need to navigate the enrollment process, meet the program's requirements and ensure your mail volumes are reported accurately.
What You’ll Find in This Section
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:
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.
: 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
). 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.
field of that request. Instead, we will simply render nothing in the HTML in place of that merge variable.
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.
Mailed*: This bucket is a count of all pieces that have received a
event, which represents handoff to USPS or a mail carrying partner. 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.
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.
See a graph of QR Code scans over a selected date range
Filter for more specific subsets of your mail by leveraging metadata.
The right side will display the request code in the selected language.
Click "Copy snippet" or manually select and copy the code.
Usage
Insomnia REST client is a free cross-platform desktop framework for testing RESTful applications. We've created a collection for Lob's API endpoint for use with Insomnia.
We've written an OpenAPI v3 authored specification for the current Lob API. This provides users the ability to generate SDKs in languages not currently supported by Lob, import Lob operations and schemas into popular tools that support OpenAPI or define operations and schemas in middleware solutions.
Learn more at the lob-openapi repository on GitHub.
In the guides below, we walk you through the specifics of the Mail Growth Incentive and other seasonal USPS promotions. We’ve designed these resources to help you:
Timing: Registration March 1, 2026 through May 31, 2026
Understand Qualifications: Eligible mail volumes: First-Class Letters, Postcards, Flats and Marketing Letters - each Mail Class has its own MGI Program
Navigate the USPS Business Customer Gateway: Step-by-step assistance creating your USPS BCG account
MGI Enrollment Process: Re-enrollment and new program participant registration process
Claim Your Postage Credit: Step-by-step instructions for claiming and assigning your postage credits to Lob
USPS Mail Growth Incentive Program Checklist: the checklist as a helpful guide
Registration Period
The Mail Growth Incentive registration for 2026 opens on March 1, 2026 and runs through May 31, 2026.
Mail Growth Incentive Requirements
Mail Owners must register under their own Mail Owners Customer Registration ID (CRID) assigned by USPS.
A CRID is a unique, USPS-generated numeric code, up to 15 digits, that identifies a specific business location involved in mailing activities.
If a Mail Owner does not have a CRID, one will be assigned during the USPS Business Customer Gateway account creation process.
It is incumbent upon the Mail Owner to ensure that the CRID(s) that they mail under are included and approved in their MGI registration and that all mailings that are entered are designated under their registered CRID in order to earn credits.
Mail Owners must mail a minimum of 1 million mailpieces in either the First-Class Mail or the Marketing Mail classes.
Aggregated volumes for both mail classes are not allowed when determining either the baseline volume or the over-achievement of volume.
Lob customers with a minimum volume of 800,000 annually AND have the potential to exceed 1,000,000 mailpieces annually in either First-Class Letters & Postcards or Marketing Letters are encouraged to register for the Mail Growth Incentive program.
Enrollment Process for 2026
Re-Enrollment for 2025 Participants
USPS enhancements to the 2026 Mail Growth Incentive program allows existing customer Mail Owners who participated in the 2025 MGI Program to automatically re-enroll via email.
Expect to receive the emails from the Mail Growth Incentive team beginning March 1, 2026.
💡If you participated in both First-Class and Marketing Mail Growth Incentive, you will receive separate emails for each. You must confirm the Baseline Volume agreement for each.
Confirm Baseline Volume
Mail Owners will need to confirm their baseline volume. The email from USPS will allow you to accept or dispute the reported volume.
Baseline volumes are separate for each First-Class Mail and Marketing Mail.
Below is an example of the email:
Upon agreement of baseline volume, the Mail Owner will receive an email confirmation of 2026 MGI program enrollment.
New Mail Growth Incentive Participant Enrollment
New Mail Growth Incentive enrollment is a multi-step process. This section provides instructions for navigating each step successfully.
Step 1: Create a USPS Business Customer Gateway account.
Step 2: Complete the My Products Portal Request Form.
Step 3: Mail Growth Incentive Program Enrollment.
Step 1: Create a USPS Business Customer Gateway account
New Mail Growth Incentive enrollment takes place in the USPS Business Customer Gateway portal. If you do not have an existing USPS Business Customer Gateway account, you will need to create an account first.
Customers will need to create a USPS Business Customer Gateway account if they do not already have one.
Refer to PP-BCG_SignUp_1.mp4 for instructions on how to sign up for a BCG account.
Once BCG enrollment is complete, this customer will see confirmation on their screen:
Step 2: Complete the My Products Portal Request Form
The form is located within the My Products Portal.
(The service has been renamed and will be visible as either My Products Portal or MP Portal.)
New enrollees will need to complete the portal access request form.
Step 3: Mail Growth Incentive Program Enrollment
The My Products Portal is segmented into two key sections: Mailing Promotions and Mail Growth Incentives. Select the Mail Growth Incentives section.
The USPS 20 page resource for step-by-step registration with screenshots are located here:
Full USPS Mailing Promotions Portal User Guide located .
Confirm and Communicate Enrollment Status
Users will receive an email when the registration request is approved by USPS and the baseline volume is confirmed by the Program Office.
Lob recommends sharing their MGI approval confirmation emails and screenshots of confirmed baseline volumes to their Account Manager / Account Executive.
Monitor Reported Volume by Period
💡It’s important to monitor your reported volumes on a regular basis and alert the MGI team when reported volumes are not aligned with your mail volumes within each period.
Lob encourages our customers to provide screenshots of the reported actual volume each month to support issue mitigation prior to the Postage Credit Claim reporting period.
It is the Mail Owner’s responsibility to review volumes and alert the MGI team when Actual Volume is not accurate.
If your reported volumes are not aligned with Lob reported volumes during monthly check-ins, you must immediately open an inquiry ticket with the Ask Me team.
Refer to the Ask Me section for instructions on how to submit a ticket.
Requesting Postage Credit on a Permit
Customers will need to request the Postage Credit through the My Products Portal. The USPS step-by-step instructions are also available for download if additional details are needed.
Log into the My Products Portal and select the Mail Growth Incentives button.
Select the Incentive Credit Dashboard and then select the SR# that has the Credit information available to create the Permit.
From the Service Request details page, select the Claim Credit tab and button.
Enter the Permit Number and Finance Number in the Permit Search fields, then select the Add Permit button.
Details to submit claim for Lob, the Mail Service Provider’s approval:
An acknowledgement message will appear requesting the MSP point of contact email so the Permit request can be sent for their approval.
Once the [email protected] email address is entered, select the Confirm button and a confirmation message will populate when the Permit is successfully created and added to the list.
One the message is acknowledged, the Mail Owner will need to enter the amount of credit needed to be applied to the Permit. Do this by selecting the pencil icon, enter the amount and then select the Save button.
If you’ve made a mistake on the amount, just select the Edit button to update the information.
Or the X button to remove the Permit from the Credit Claim request and make the change.
A confirmation message will appear stating that the Permit was successfully updated:
Once all Permits are updated, select the Submit button and confirm the list of Permits being submitted is accurate.
You can view the Postage Credit Claim transfer status in the Incentive Permits pane which is located under the Related tab in the Service Request screen:
The Permit Status will initially show Submitted for Approval:
Once Lob, the MSP, receives the email, the Partner Operations team will review and Accept the transfer request. You can view the status in the Incentive Permit screen:
After Lob accepts the Postage Credit, the Permit Status will change to Pending Program Review:
When Lob customers request their Postage Credit to be transferred to Lob, the Mail Owner will receive an email notification confirming their request. The Program Office will review and approve then Lob will receive an email notification to either accept or reject.
In some cases, Lob has not received the email notification. It is important to keep your Lob representative informed in order for Lob to monitor and support related issues.
Update Contact Information: The My Products Portal
Below are the instructions to update contact information, if you need to make a change to your organization's main point of contact email address.
The USPS will send an email to the contact email address listed in the MP Portal profile.
Select the dropdown arrow next to the login name and choose My Profile.
You can verify or change your email address in your Profile by selecting the Edit button in the top right hand corner.
If you need to update your email address, select Edit, this launches the Edit User screen.
Update your email address and select Save.
Ask Me: Issue Submission Process
These are the steps the customers need to take to open a ticket with the MGI team to address the issue:
Log into the BCG
Select the MP Portal link:
Also listed as My Products Portal (f/k/a My Mailing Promotions):
In the My Products Portal, select the Mail Growth Incentives option
Select the Ask My button located in the middle of the page
Then select the Mail Growth Incentive Type that they are having an issue on.
Complete the Question Summary and the Question area with the details.
After selecting Next, you’ll receive confirmation your question has been submitted:
The Mail Owner’s email address on the MPP Profile will receive an email from the resource the USPS assigned to the ticket.
Once the Mail Owner receives the email, I encourage them to include their Lob representative and Lori Tiseth to monitor or assist with responding to USPS.
Design assets (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 Campaigns tab 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 Lob integrations here.
Step 1: Configure settings
Note: fields marked with *are required; all others are optional features.
*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.
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 here.
Select campaign type*: Select what will your campaign have: are you sending out a marketing campaign or using this for operational (non-promotional) purposes?
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
Send options: ASAP or schedule a future date up to 180 days
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
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
Upload your target audience*: Select your segment via CSV
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
Map optional address fields: These fields will be added to your recipient address block if mapped
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
Upload your creative assets* (Example, front and back of postcard)
Make sure you are following the design guidelines specific to your mail format
You can utilize PDF or HTML; learn more about Creative formatting 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 canadd a QR codeto your mailpieces after you upload your creative.
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
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.
Campaign settings: Review the campaign send details
Audience: Review the target audience list
Creative: Preview a mailpiece to ensure the campaign will render correctly
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.
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 cancellation window.
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.
If applicable, click the Cancel Campaign button.
You will be asked to confirm; your Campaign will go back into Draft state.
Your Campaign will be canceled; you can return the dashboard or edit the Campaign.
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 Mail Analytics 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 rendering best practices and rendering errors.
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:
Title
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.
There are no character limits for the title
Destination
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
There are no character limits for the destination URL
Shortened Display URL
Domain
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.
Metadata
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:
Sign in to your domain registrar's website.
Use the same steps as above to locate the DNS settings for your domain.
Create a CNAME record for your subdomain.
Add a new CNAME record with the following details:
Host: Your desired subdomain. For example, if you want your short links to use `links.example.com`, enter `links` as the host.
Type: CNAME
Data/Points to: cname.short.io
Save your changes.
Ensure all changes are saved to make your DNS record active.
Wait for activation.
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:
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 dashboard 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.
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
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 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:
Sign up for and
Connect Lob to Make
Create custom workflows, or use ones
Sign up for Make
Navigate to Make's website at
Create an account by clicking on the Sign Up button on the top right of the screen
Start with a free developer’s account, or sign up for a that suits your needs
Connecting Lob to Make
Log in to your and accounts
In the Make dashboard, click on "+ Create a new Scenario" button at the top right corner of the home screen
Search for "Lob" in the app directory and hit "Continue"
Use pre-built Lob modules
Here are (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
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 your online apps to Lob.
For example, to connect Google Drive to Make:
Create a
Using the , create a new project.
Create credentials for the new project, adding Make to the project’s Scope and allowing external users
You can find more information about connecting Make to Google Services in this .
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 .
Using pre-built is typically an easier place to start than building one from scratch:
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
From your scenario builder screen in Make, navigate and click on the “More” button (see below box with an ellipsis). Click “Export Blueprint.”
The ‘blueprint.json’ file will then be downloaded to your device’s folder.
Download/Import a Make blueprint
In the scenario builder screen, click on the “More” button (same box as above). Click “Import Blueprint.”
When the Import Blueprint menu is launched, click on “Choose Files” and select blueprint.json from your files.
→
Once the file has been submitted to your Import Blueprint builder click on the “Save” button.
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, 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:
Support information
Feel free to contact Make’s support team via their for issues on the Make side, or email for Lob-specific debugging!
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
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
Override cancellation window
Anytime you place an order it’s good to understand the cancellation policy. By default, new accounts have a 4-hour cancellation window. Within that time frame, you can cancel mailings, free of charge. Once the cancellation time window has passed for a postcard, self-mailer, letter, or check, the mailing is no longer cancelable.
Users on higher editions can customize their cancellation windows in their dashboard settings. Upgrade your Print & Mail edition to gain access to this feature, or reach out to our sales team to learn more.
Can I programmatically override my cancellation window?
Using a custom send date in your Lob request enables you to override your default cancelation window and set a specific date and time for which you want a mail piece to go into production.
Why is this important?
Some clients may want to create a campaign today with Lob, but have it actually mailed in 2 weeks. This provides them the time to QA and make sure everything is in order. Others may need to dictate when certain mail pieces go out after a trigger, e.g., two weeks after a shopper abandons their cart, a postcard is sent telling them that the item is now on sale. Either way, this feature enables customers to dictate when a mail piece goes into production if a static cancellation window is not sufficient for their needs. They can do this for each specific mail piece and can customize as needed. If this is not used in the request, it will use the default cancellation window as it is not required.
How do we (programmatically) solve this problem?
If a custom send date is desired, you will have to send either a date or a timestamp of the desired send date. If you send a simple date (YYYY-MM-DD) it will evaluate to midnight UTC of that date. If you don't need to send a custom send date, simply do not include it in the payload—or pass null—to use your default cancellation window.
In the code sample below, we want mail to go into production on July 1st at 6:00 am PST which is 2:00 pm UTC.
To do this our send date is "2022-07-01T14:00:00"
If you are using Lob's free Developer edition, setting the send_date is not available
Message you will receive from Lob's API:
NCOA responses
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.
Prerequisites
In order to leverage Lob’s NCOA feature, we must have a signed Processing and Acknowledgement Form and the account must meet other volume requirements. If NCOA reporting is not currently enabled for your account, please reach out to your Account Manager or your Customer Success Manager for more information and next steps.
A live API key is also required. In order to get this, refer to step one of .
How to use Lob’s NCOA functionality
Using the NCOA data is simple. When an address is created in the Lob API and a mail piece is created, the recipient and address are used to look up current change of address records.
If there is a currently active COA, then the mail piece created will include the recipient’s new address information and the response from the Lob API will include a representation of the Address record that has a recipient_moved value of true and redacted values for address_line1 and address_line2, but all other values will reflect the COA changes.
Code example
For example, an application is sending a check. Because of the business logic of this application, when the recipient has changed addresses, we want to cancel the check instead of allowing it to be rerouted.
For this, we will assume there is a verified bank account already recorded and the application is aware of the Lob record id for that bank account.
Conclusion
Lob’s NCOA feature, once enabled for an account, allows a consuming application to more completely manage the behavior of mail pieces when a recipient has moved.
Further resources
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 .
AV Elements
How to get started
Registration
Create an account at
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, .
Select an amount of time for your campaign cancellation window, 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
import com.lob.Lob;
import com.lob.model.Address;
import com.lob.model.Check;
import com.lob.net.LobResponse;
public class App
{
public static void main( String[] args )
{
Lob.init("test_XXXXXXXX");
try {
LobResponse<Check> response = new Check.RequestBuilder()
.setDescription("Remimburse $1")
.setAmount("1.00")
.setTo(
new Address.RequestBuilder()
.setName("Harry Zhang")
.setLine1("185 Berry Street")
.setLine2("Ste 6100")
.setCity("San Francisco")
.setState("CA")
.setZip("94107")
)
.setFrom(
new Address.RequestBuilder()
.setName("Leore Avidar")
.setLine1("210 King St")
.setCity("San Francisco")
.setState("CA")
.setZip("94107")
)
.setBankAccount("bank_XXXXXXXX")
.create();
Check newCheck = response.getResponseBody();
if(newCheck.getTo().getRecipientMoved() != null) {
LobResponse<Check> deleteResp = Check.delete(newCheck.getId());
System.out.println("Recipient has moved - cancel check");
} else {
System.out.println("Check is in the mail");
}
} catch (Exception err) {
System.out.println("Error on check creation: " + err);
}
}
}
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.
Back-half
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 lob.st/mail. In this case, lob.st/mail would be what you add on your direct mail creative copy to then be printed. When users type lob.st/mail in their web browser, it would then redirect to the full destination URL.
There are no character limits for the back-half URL
TTL: You can leave this at the default setting. Common defaults are 3600 seconds or automatic.
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
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
Once the connection is completed, finish building your Scenario or browse pre-built Scenarios to leverage
Once you've tested your first Scenario, switch the API key to the Live key and begin sending physical mail!
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
Create the application
Retrieve Client ID and Secret
Use ID and Secret to establish Make connection
Once complete, you will receive a confirmation banner along the bottom right side of your scenario builder screen.
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.
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
Click on the continue button on the top right side of the page.
When you enter your scenario builder screen, you will see a blank module. Click on the module and select the “Google Sheets” option.
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.
Make should now integrated with Google Sheets. You can continue to build out your module by completing the scenario with your new Sheets connection.
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.
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)
Overnight mailing options are not available for checks
"Your account's Print & Mail Edition does not allow you to use the Scheduled Mailings feature. Upgrade here: https://dashboard.lob.com/#/settings/editions"
import{Configuration,Postcard,PostcardsApi,PostcardEditable,CountryExtended}from"@lob/lob-typescript-sdk"asyncfunctiondemo(){constconfig:Configuration=newConfiguration({username:"<YOUR_TEST_KEY>"})constpostcardData:PostcardEditable={to:{name:"Harry Zhang",address_line1:"210 King Street",address_city:"San Francisco",address_state:"CA",address_zip:"94107"},from:{name:"Leore Avidar",address_line1:"210 King Street",address_city:"San Francisco",address_state:"CA",address_zip:"94107",address_country:CountryExtended.Us},front:"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf",back:"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf",send_date:"2022-07-01T14:00:00"}try{constresult:Postcard=awaitnewPostcardsApi(config).create(postcardDatareturnresult}catch(err:any){console.error(err)}}demo().then((result)=>console.log(result)).catch()
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 500MB. 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 metadata 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:
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”
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.
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 Using Metadata 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 Campaigns > Step 2: Add Audience.
Campaigns API
When sending 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 API documentation.
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:
Default return address
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.
Return_address_name
The name (first/last) for the return address
Return_address_line1
Return_address_city
Return_address_state
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:
Return_address_line2
Return_address_company
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 Campaigns > Step 3: Choose Creative
Campaigns API
This can either be configured 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.
Avoid disallowed characters in the header row.
Allowed characters in the headers are: alphanumeric (a-z, A-Z, 0-9), underscore (_), dash (-), parentheses (()), space (), and period (.).
to obtain a Live Public API Key. The key is available in the
of the Lob
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:
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
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
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
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.
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 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.
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:
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 which can be obtained through USPS in three ways:
Go to . Select "." 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
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.
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:
Sign up for Lob and Zapier accounts
Connect Lob to Zapier, within the Zapier interface
Connect any other apps/services (for example, where you store customer data) to Zapier, in order to then connect them with Lob
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
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 account, where you will begin building the automation.
Connecting Lob to Zapier
to your Lob Account
Log in to your
Navigate to "Connected Accounts" from the top menu bar in Zapier
Getting started with Zapier
To help you hit the ground running, you can choose from :
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
From the Zapier home screen, click on a “Make a Zap!” button to get started
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
Stage 2: Setting up your Action
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.
Select Lob to be your Action App.
Select “Send Postcard” as the action Lob will take after the Zap is initiated by the Trigger.
Stage 3: Test the Zap to Confirm
Test the entire Zap (From Trigger to Action) by clicking on the "Send Test to Lob" button.
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.
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 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).
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 , 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. 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 . 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 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 above for more context.
Support information
Feel free to email for issues on the Zapier side, or for Lob-specific debugging!
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.
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.
import lob
lob.api_key = "<YOUR_TEST_KEY>"
postcard = lob.Postcard.create(
description = "First Postcard",
to_address = {
"name": "Harry Zhang",
"address_line1": "210 King Street",
"address_city": "San Francisco",
"address_state": "CA",
"address_zip": "94107"
},
from_address = {
"name": "Leore Avidar",
"address_line1": "210 King Street",
"address_city": "San Francisco",
"address_state": "CA",
"address_zip": "94107",
"address_country": "US"
},
front = "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
back = "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>",
merge_variables = {
"name": "Harry"
},
send_date = "2022-07-01T14:00:00"
)
print(postcard)
require 'lob.rb'
require 'pp'
lob = Lob::Client.new(api_key: "<TEST_API_KEY>")
pp lob.postcards.create(
description: "First Postcard",
to: {
name: "Harry Zhang",
address_line1: "210 King Street",
address_city: "San Francisco",
address_state: "CA",
address_zip: "94107"
},
from: {
name: "Leore Avidar",
address_line1: "210 King Street",
address_city: "San Francisco",
address_state: "CA",
address_zip: "94107"
},
merge_variables: { name: "Harry" },
front: "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
back: "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>",
send_date: "2022-07-01T14:00:00"
)
<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>
)
Temporary service disruptions (due to conditions like wildfires or COVID-19 for example) are subject to change.
By bulk electronic file transfer for mailers who provide an electronic manifest to the United States Postal Service
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.
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!
Connect your Google account to Zapier and give Zapier access to the account
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.
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
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.
In the next stage, you will configure the action you want Zapier to take after your trigger is initiated.
Connect your Lob account to Zapier and give Zapier access to the account, so it can take action on your behalf.
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.
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.
Fill in the appropriate information needed to complete your mail. Note that some fields are optional and others are required.
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.
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, . Example HTML templates can be found in our .
Alternatively, provide a link to a hosted PDF, PNG, or JPG file
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.
Lob defaults to USPS First Class Mail (a faster option), but Standard Class mail is also an option.
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.
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:
Select the PDF file that you want to convert to PDF/X.
Once the PDF document is open, go to the “File” menu option and choose “Save As”
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.
Next, look for a dropdown menu or an option that allows you to select the file format. Click on the PDF/X option.
Next, configure the settings:
Select Save as PDF/X-1a
Select Convert to PDF/X-1a (Coated GracOL 2006)
Click the “OK” button to initiate the conversion process.
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.
Once the conversion is complete, the software will save the PDF/X-1afile 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:
Open the pdf you want to check
Open Print Production tools (View > Tools > Print Production)
Click Preflight
Click the PDF/X tab
Click convert to PDF/X1-a (coated GRACoL 2006)
Click on the Analyze button.
The preflight tool will return information on where transparency was applied.
How to save:
Open PDF file to flatten
Open Print Production > Flattener preview
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:
Open the PDF file or creative you want to check.
Click on the layers icon on the left panel as shown in the screenshot below.
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 font types Lob can and cannot support.
Fonts must be outlined (preferred) or embedded. Fonts that have not been outlined or embedded might change or render incorrectly, specific letters may be substituted with incorrect glyphs.
How to review:
Go to "File" and choose "Open" to select the PDF file you want to check the fonts.
Click on "File" and then select "Properties" from the dropdown menu.
Access the Fonts tab: In the Properties dialog box, click on the "Fonts" tab.
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.
To embed a new font, go to File > Print and then select Adobe PDF. Click Properties.
Select the Adobe PDF settings tab at the end and then click the EDIT button to the right of the default settings.
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.
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:
Open the PDF file that you’re looking to check.
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:
Open the PDF you wish to re-save as a smaller file.
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:
Open the pdf you want to check the color profile for
Open Print Production tools (View > Tools > Print Production > Output Preview
Under Show > select dropdown CMYK.
This will show the area which is in the CMYK profile.
How to save:
Open the pdf you want to save
Open Print Production tools (View > Tools > Print Production)
Click Preflight
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:
Locate the image file on your Mac and select it.
Right-click (or Control-click) on the image file and select "Open With" from the context menu.
Choose "Preview" from the submenu. The image will open in the Preview application.
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.
Getting Started
Make sure you have a Lob account and your API keys. It is highly recommended that you use your (secret) test API key first
Have a creative file ready to use (hosted PDF file or HTML template)
In the sidebar, navigate to “Connections” -> “Catalog,” and then click the Functions tab:
Click the “New Function” button:
Under “Select Function Type,” click “Destination,” and then click “Build”:
Enter your Javascript code in the editor on the left, and test your function on the right; refer to the following section on form factors for details. Click “Configure” when done:
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:
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:
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.
/**
* @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();
}
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 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.
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.
Click OK on the pop-up window and you’re done.
Click the PDF/X tab
Click convert to PDF/X1-a GRACoL 2006)
Click on Analyze and Fix button.
In Preview, click on the "Tools" menu at the top and select "Show Inspector". A sidebar with image information will appear.
In the Inspector sidebar, click on the "General" tab. You should see information about the image, including its dimensions, file size, and resolution.
Look for the "Resolution" field, which will display the image's PPI value.
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 (Braze Documentation). 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 conditional logic. 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.
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
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 }}
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:
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
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?
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 Media Library 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:
Set up a Data Transformation in Braze. This will generate a Webhook URL you can use to pass events into Braze.
Create Lob Webhook for the events you want to track, using the Braze-provided URL
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.
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'.
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 ; 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 or a mail carrying partner for fulfillment. (Event will be displayed in dashboard at individual mailpiece level; no webhook available.)
Mailed - Confirmation that mail has been handed off to USPS or a mail carrying partner from our printers.
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 "" 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 .
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 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 ), 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 .
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 , and how to via webhooks.
How to confirm USPS received your mail
, 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 .)
The following mailpiece webhooks indicate USPS possession:
xxx.delivered
xxx.in_local_area
xxx.in_transit
xxx.processed_for_delivery
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.)
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.
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.
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 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 USPS 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 for details on tracking mail pieces abroad.
Delivery timelines & delayed pieces
Delivery times for mail will vary depending on 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 as originally addressed.
This results in a yellow sticker being affixed to the mailing by USPS for tracking purposes called a 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.)
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
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):
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;
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), 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 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 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 .
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 . 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.
Adding QR codes
Overview
Lob’s platform allows you to generate a QR code for each individual mailpiece you send. This feature is available via
Personalized response tracking is a standard feature of digital marketing channels, but has traditionally been difficult to replicate in Direct Mail. However, with Lob’s QR code offering, personalized tracking can now be easily incorporated into your Direct Mail campaigns.
We offer 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
Lob handles URL encoding within the QR code generation process. Do not encode your QR code URL or parameters in advance, as this will lead to double-encoding of the complete QR code URL.
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.
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
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)
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.
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.
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.
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.
All keys and values are enclosed in double quotes (").
Commas after every key-value pair except for the last one.
No newline characters in any values and no extra spaces between fields.
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.
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 USPS 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.
xxx.re-routed
xxx.returned_to_sender
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
Example of a USPS Return to Sender sticker (NIXIE label)
-
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}}
option where you can provide the Hex code for the color you wish to apply to the QR codes.
See below section on URL redirects for how to personalize URLs.
For Self-mailers & Snap packs, the values should be inside, outside,or inside,outside.
The mergeVariableColumnMapping holds the mapping for the name variable created in the URL template.
If generating via API, use your Test API Key to preview your creative in Lob and verify that everything looks as intended.
Make sure to leave 0.25” of space between your QR code position and any content of your mailpiece that you don’t want to be covered.
When positioning your QR code, make sure to take into account the bleed edge added to the artboard dimensions of the mailpiece. For example, the dimensions of a 4x6” Postcard in Lob are 4.25” x 6.25”.
Lob QR Codes do not expire. If your destination URL expires, you may want to update live QR codes to redirect to an active landing page.
URL Encoding: All QR codes are URL-encoded by Lob for security purposes. Do not URL-encode your URL or URL parameters in advance, or this will lead to double-encoding within the QR code.
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).
Lob utilizes response codes to indicate whether an API request has succeeded or failed.
Lob uses both Standard RESTful and custom response codes, which reflect specific Lob requirements or functionality. Lob’s error response contains a message parameter containing developer-facing information about the reason for failure.
Live requests that result in a non-2XX code response are indicative of resource creation being stopped. That is, those requests do not incur a postage cost as no resource is created.
Handling particular error messages can be crucial in ensuring you have a robust integration with Lob. The main categories of error status codes are 4xx and 5xx. However, timeouts can also be viewed as an error in and of itself.
5XX codes & timeouts
5XX error codes indicate a server failure, as mentioned below, whereas timeouts are indicative of just that. A request did not receive a response in the allotted amount of time. Either way, the request sent to Lob may or may not have been properly received.
To ensure that your request to Lob was successful, it is advisable to institute retry logic accordingly. When setting up this retry logic, it is essential to keep the following in mind:
Idempotency-keys will ensure your retry attempts are safe by checking that no unique mail piece is created more than once. It is crucial to use these keys to make sure you do not incur any undesired usage costs.
Backoff logic should be utilized to allow the network time to recover in the event of a short outage. Lob has sub-second response times, which means if a timeout occurs, it is likely a network issue.
3-5 retry attempts are considered best practice.
4XX codes
4XX error codes indicate something about the request was invalid. In the case of Lob, we have custom response codes that should be handled accordingly.
This code is related to exceeding your rate limit. If this status code is received, you should have logic in place to back off all requests to this specific endpoint and resume attempts after 5 seconds. You can utilize the 3 rate limit headers in your retry logic.
ratelimit-remaining - The number of requests remaining in the current window.
ratelimit-remaining - The number of requests remaining in the current window.
ratelimit-reset - The time at which the rate limit window resets in UTC epoch seconds.
If you receive a 404 response code on a GET request, it is recommended that you attempt that request with proper retry logic in place, as you may be attempting to retrieve a resource that has yet to be created. Usually, within a minute, these errors are resolved.
These error codes should be investigated as they relate to authentication issues. No retry attempts are necessary.
Other than the cases above, all errors should be acted upon as you see fit. Ultimately, the error code you receive from Lob can help you take corrective action, but not retry attempts are needed as you will get the same error message each time.
Note: For fields that are intended to accept only string values, submitting JSON objects in string format (stringified JSON objects) is not supported. Our system automatically parses and validates incoming data according to their expected types. As a result, providing a stringified JSON object in a field designated for string input can cause parsing errors or lead to unexpected validation results.
HTTP status codes
SUCCESS
200
Successful API request
UNAUTHORIZED
401
Authorization error with your API key or account
FORBIDDEN
403
Error codes - generic
FEATURE_LIMIT_REACHED
403
The account has reached its resource limit and requires upgrading to add more.
UNRECOGNIZED_ENDPOINT
404
The requested endpoint doesn't exist.
NOT_FOUND
404
Error codes - authentication
EMAIL_REQUIRED
401
Account must have a verified email address before creating live resources.
UNAUTHORIZED
401
The request isn't authorized.
UNAUTHORIZED_TOKEN
401
Error codes - advanced
PAYMENT_METHOD_UNVERIFIED
401
You must have a verified bank account or credit card to submit live requests.
BILLING_ADDRESS_REQUIRED
403
In order to create a live mail piece, your account needs to have a .
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.
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.
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:
Forbidden error with your API key or account
NOT FOUND
404
The requested item does not exist
BAD REQUEST
422
The query or body parameters did not pass validation
TOO MANY REQUESTS
429
Too many requests have been sent with an API key in a given amount of time. Learn more about Lob’s rate limits here.
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"
Embossed 24# White Wove with a
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.
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.
Expiration: 6 months (to ensure the integrity of adhesives)
Fits up to 6 sheets of 8.5 x 11" paper / 12 duplexed pages (+ letter 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 with inside security tint
A USPS-approved design must be used in BREs; no custom artwork is allowed
Postage must be prepaid
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.
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.
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
Create, view, edit, and manage your HTML templates for any mail format by saving them within Lob's system. You can create an HTML template in two ways:
By creating templates within your Lob dashboard under HTML Templates.
Template fields
While creating your template, you may want to include a few important fields.
Description: This is a name or summary for your template. While optional, we highly recommend adding this field so you can easily identify each of your templates.
Mail format and size: These are required fields if you’re saving your template in the dashboard, but optional in the API.
Meta data: These are tags you can add to your template for easier filtering and reporting later. Find this field in the Settings tab in the dashboard.
You can always edit template fields after you’ve saved your template.
Template proof
We encourage you to create a proof of your template; it’s the easiest way to validate that your creative looks as expected before you start using it for live mail pieces.
In the dashboard, you can generate a proof directly next to the HTML code box while you’re creating or editing a template. Lob requires you to select a mail format and size in order to generate your proof. If your template has merge variables, or you want to further customize your proof, go to the Settings tab to the right of the Proof tab. There, you can alter specifics about the mail format, the address, or enter sample merge variable data.
Reminder: Generate a new proof any time your HTML code or Settings change so that you’re always viewing the latest creative. If Lob is unable to generate your proof, we’ll explain why and offer tips for resolving the issue. If a template proof is unable to generate, avoid using it for live mail until all issues are resolved.
In the API, you can generate a template proof by making a call to Lob’s resource proof generation endpoint. The documentation lives here.
Template environment (test vs live)
Like with 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.
You can move templates from one environment to the other, but make sure you are working in the correct environment – and 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.
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.
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 or delete the template (from the meatball menu).
Also the this page you can:
See a proof of the template
View the Template ID (completely unique to this particular 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.
If the HTML above were used with the information below:
name
fontsize
color
img
Harry
20px
red
Ami
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:
To access these within your template you can do the following:
This renders the following template:
You can also create a "section" which will change the context of the variables you are accessing. For instance:
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:
Template:
This renders:
If you want to render content if a condition does not pass, simply use ^: {{^condition}}{{/condition}}.
For example:
Loops allow you to display content multiple times for multiple objects. The following is an example of how to use loops:
Merge variables:
Template:
This renders:
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.
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:
Then reference the font in your <style></style> tag or inline:
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:
And then reference the font in your <style></style> tag or inline:
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-afterproperty.
For example, create a page class in your HTML and apply these styles:
And then, divide the pages of content in your HTML by this page class:
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 template proof with your HTML templates, whether in Live or in Test mode, to visually validate that it looks as expected. (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 to correct the rotation value
Example: jhead -autorot myfile.jpg
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.
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.
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 event 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 entire event object to the URL provided.
Subscribing to a webhook in the Lob dashboard
Select Webhooks from the left navigation bar.
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 Print & Mail Edition. There is no limit in Test mode.
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.
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 securing your endpoint 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 Settings 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 tracking events 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 Debugger 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 Debugger tool. 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 ngrok. 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 webhook dashboard and either: (1) enter the rate limit when creating a new webhook 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 webhooks dashboard 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
1
Immediately
0 min
2022-01-01T00:00:00Z
2
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 dashboard 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 Debugger 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.
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.
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.
Step 3: Compare signatures
Compare the expected signature with the Lob-Signature header. If the strings are equal, then the webhook is valid.
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 cross-site request forgery. 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 API Version on your account at the time of event creation. If your account is set to an older API version but a request is sent with a hard-coded header, 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 return envelopes with tracking 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 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.
You can view your return envelope tracking events by setting up your webhooks:
Letter add-ons are features exclusive to our Enterprise tier customers. Upgrade to the appropriate Print & Mail edition to gain access, or contact our sales team to learn more. Add-ons are currently only available for 8.5" x 11" standard letters.
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
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
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.
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
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
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
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
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
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
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
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
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
Buckslip dimensions & design specs
Layout templates
Buckslip paper specs
8.5” x 3.5” size
80 lb. Text, Gloss or Matte finish
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
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.
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
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
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
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.
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
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
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
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.
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.
Once card details show, select the Order button at the bottom
Add the desired number of cards and hit Order
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}/ordersendpoint with the following field:
Quantity (Required, number): Number of cards you would like to order
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
You cannot pair cards with other letter add-ons at this time
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
Additionally, you can find all cards in your account by sending a GET call to https://api.lob.com/v1/cards
Cards affixed to the top fold of a trifold letter towards the right
Letters sent in standard #10 outer envelopes
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
Or watch a quick demo of ordering buckslips and sending them with letters via the dashboard
Double-sided, full bleed
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
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.
Once buckslip details show, select the Order button at the bottom
Add the desired number of buckslips and hit Order
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}/ordersendpoint with the following field:
Quantity (Required, number): Number of buckslips you would like to order
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
You cannot send buckslips if you have an insufficient amount in your inventory, as your campaign request will be rejected
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
Finish
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
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
If not elapsed, you will need to provide a list of the resource IDs you would like to have canceled.
Submitting deletion requests via Support is not a suitable replacement for making deletion requests on your own.
Overview
Having a mass delete system in place is essential to avoid unnecessary costs, save time, and protect customer relationships when a campaign is mistakenly triggered. This feature allows you to cancel large amounts of mail associated with a specific campaign, identified by a batch ID, without disrupting other outgoing mail.
In this tutorial, we’ll show you how to leverage Lob’s metadata property or manage mail campaign information within your infrastructure for efficient mass deletion. This helps you quickly stop unintended campaigns before they go to print, preventing early or incorrect mail from reaching customers.
A large number of mail pieces needing to be canceled quickly
The mail pieces have not been sent to printers
Mass deletion using Lob metadata
The recommended approach for identifying batches of mail sent through Lob is to use the metadata property with a unique key-value pair. Below is an example of how to create a single mail piece that includes metadata with a batch_id set to “NEWYORK2022”. The batch_id can be anything you want as long as it is unique to the batch, is a maximum length of 500 characters and is used for all mail pieces in the batch.
Create a config using your LOB_API_KEY found in the Lob dashboard. Find more on idempotency keys here.
In order to delete all postcards from the NEWYORK2022 campaign, use the list function and pass a metadata object with a batch_id key set to NEWYORK2022. This returns a list of all NEWYORK2022 campaign postcards, loop over each one and pass the postcard id into the cancel function.
To see the full list of acceptable parameters in the list, visit the docs.
Mass deletion utilizing your own infrastructure
If you plan to save details about individual mail pieces in your database, consider including an identifier for the campaign as well. In the example below, we create a new postcard and upon successful completion, we store details in our database.
Create a config using your LOB_API_KEY found in the lob dashboard.
For extra resiliency, you can pass in the batch id via metadata (see above example), as well as store it locally as seen below.
To mass delete, we fetch a list of mail pieces from our database using a unique id for our campaign and loop over all the mail pieces to cancel them.
Fetch the list ids from your database using your unique group id
Fetch the list ids from your database using your unique group id
Fetch the list ids from your database using your unique group id
Fetch the list ids from your database using your unique group id
Fetch the list ids from your database using your unique group id
const config: Configuration = new Configuration({
username: "test_XXXXXXXXX",
});
const postcardsApi = new PostcardsApi(config);
const listOfPostcards = await postcardsApi.list(
undefined,
undefined,
undefined,
undefined,
undefined,
{ batch_id: "NEWYORK2022" }
);
for (let postcard of listOfPostcards) {
await postcardsApi.cancel(postcard.id);
}
import lob
lob.api_key = "test_XXXXXXXXXXXXXX"
list_of_postcards = lob.Postcard.list(metadata={"batch_id": "NEWYORK2022"})
for i in list_of_postcards.data:
lob.Postcard.delete(i.id)
require 'lob.rb'
require 'pp'
require 'json'
lob = Lob::Client.new(api_key: "test_XXXXXXXXXX")
list = lob.postcards.list(metadata: {"batch_id": "NEWYORK2022"})
data = list['data']
data.each do |item|
begin
lob.postcards.destroy( item['id'])
rescue Lob::InvalidRequestError => e
obj = JSON.parse(e.json_body)
pp obj['error']['message']
end
end
const config: Configuration = new Configuration({
username: "test_XXXXXXXXX",
});
const postCardExample: PostcardEditable = {
to: {
name: "HARRY ZHANG",
address_line1: "210 KING STREET",
address_city: "SAN FRANCISCO",
address_state: "CA",
address_zip: "94107",
address_country: CountryExtended.Us,
},
from: {
name: "LEORE AVIDAR",
address_line1: "185 BERRY ST",
address_line2: "SUITE 6100",
address_city: "SAN FRANCISCO",
address_state: "CA",
address_zip: "94107",
address_country: CountryExtended.Us,
}
};
const postcardsApi = new PostcardsApi(config);
const postcard = await postcardsApi.create(postCardExample);
/* Save to your database with the postcard.id and a unique group id */
import lob
lob.api_key = "test_XXXXXXXXX"
postcard = lob.Postcard.create(
to_address = {
"name": "HARRY ZHANG",
"address_line1": "210 KING STREET",
"address_city": "SAN FRANCISCO",
"address_state": "CA",
"address_zip": "94107"
},
from_address = {
"name": "LEORE AVIDAR",
"address_line1": "185 BERRY ST",
"address_line2": "SUITE 6100",
"address_city": "SAN FRANCISCO",
"address_state": "CA",
"address_zip": "94107",
"address_country": "US"
},
front = "<html style='padding: 1in; font-size: 50;'>Front HTML for Postcard</html>",
back = "<html style='padding: 1in; font-size: 20;'>Back HTML for Postcard</html>"
)
# Save to your database with the postcard.id and a unique group id
require 'lob.rb'
require 'pp'
lob = Lob::Client.new(api_key: "test_XXXXXX")
newPostcard = lob.postcards.create(
to: {
name: "HARRY ZHANG",
address_line1: "210 KING STREET",
address_city: "SAN FRANCISCO",
address_state: "CA",
address_zip: "94107"
},
from: {
name: "LEORE AVIDAR",
address_line1: "185 BERRY ST",
address_line2: "SUITE 6100",
address_city: "SAN FRANCISCO",
address_state: "CA",
address_zip: "94107"
},
front: "<html style='padding: 1in; font-size: 50;'>Front HTML</html>",
back: "<html style='padding: 1in; font-size: 20;'>Back HTML</html>"
)
//Save to your database with the postcard.id and a unique group id
$lob = new \Lob\Lob('test_XXXXXX');
$postcard = $lob->postcards()->create(array(
"to[name]" => "HARRY ZHANG",
"to[address_line1]" => "210 KING STREET",
"to[address_city]" => "SAN FRANCISCO",
"to[address_state]" => "CA",
"to[address_zip]" => "94107",
"from[name]" => "LEORE AVIDAR",
"from[address_line1]" => "185 BERRY STREET",
"from[address_line2]" => "SUITE 6100",
"from[address_city]" => "SAN FRANCISCO",
"from[address_state]" => "CA",
"from[address_zip]" => "94107",
"front" => "<html style='padding: 1in; font-size: 50;'>Front HTML</html>",
"back" => "<html style='padding: 1in; font-size: 20;'>Back HTML</html>"
));
/* Save to your database with the postcard.id and a unique group id */
import java.util.Map;
import com.lob.Lob;
import com.lob.model.Address;
import com.lob.model.Postcard;
import com.lob.net.LobResponse;
public class App
{
public static void main( String[] args )
{
Lob.init("test_XXXXXXXX");
try {
LobResponse<Postcard> response = new Postcard.RequestBuilder()
.setTo(
new Address.RequestBuilder()
.setName("HARRY ZHANG")
.setLine1("210 KING STREET")
.setCity("SAN FRANCISCO")
.setState("CA")
.setZip("94107")
)
.setFrom(
new Address.RequestBuilder()
.setName("LEORE AVIDAR")
.setLine1("210 KING STREET")
.setCity("SAN FRANCISCO")
.setState("CA")
.setZip("94107")
)
.setFront("<html style='padding: 1in; font-size: 50;'>Front HTML</html>")
.setBack("<html style='padding: 1in; font-size: 20;'>Back HTML</html>")
.create();
/* Save to your database with the postcard.id and a unique group id */
} catch (Exception err) {
System.out.println("Error on postcard creation: " + err);
}
}
}
const config: Configuration = new Configuration({
username: LOB_API_KEY,
});
const postcardsApi = new PostcardsApi(config);
for (let item of dbdata) {
await postcardsApi.cancel(item.id);
/* Remove the record from your database */
}
import lob
lob.api_key = "test_XXXXXXXXXX"
for i in dbdata:
lob.Postcard.delete(i.id)
/* Remove the record from your database */
dbdata.each do | item |
begin
lob.postcards.destroy( item['id'])
# Remove the record from your database
rescue Lob::InvalidRequestError => e
obj = JSON.parse(e.json_body)
pp obj['error']['message']
end
end
foreach($dbdata as $item) {
try {
$lob->postcards()->delete($item['id']);
/* Remove the record from your database */
} catch (Exception $e) {
echo 'Caught exception: ', $e->getMessage(), "\n";
}
}
import java.util.Map;
import java.util.HashMap;
import com.lob.Lob;
import com.lob.model.PostcardCollection;
import com.lob.model.Postcard;
import com.lob.net.LobResponse;
public class App
{
public static void main( String[] args )
{
Lob.init("test_XXXXXXXXX");
for(int i=0; i<list.getCount(); i++) {
try {
LobResponse<Postcard> deleteResponse = Postcard.delete(list.getData().get(i).getId());
/* delete record from your database */
} catch (Exception err) {
System.out.println("Error: " + err);
}
}
}
}
API quickstart guide
Jump in and explore our APIs
The following quickstart guide allows you to jump in and explore the Lob Print & Mail API in your preferred programming language.
Lob account basics
In order to follow this Quickstart guide, you will need:
A Lob account; create your account .
Your (you can find these in your Dashboard under Settings → API Keys)
Language setup guides
These brief sections are aimed at developers who are less familiar with the languages with which they will be working with Lob API. Currently, Lob provides client libraries in the following languages:
(Note: If you are a TypeScript user, you can jump right in with a video tutorial: .)
Follow the instructions on the . For Windows, installing through the Visual Studio text editor is the best option.
Follow the download and setup instructions on .
To make switching between Node versions easy, install nvm on your local machine, following in the official Node Version Manager GitHub repository. To get the latest LTS release, run:
Alternatively, Windows users should install the of nvm-windows by following in its home repository.
Download and set up the appropriate version from
Installing Lob’s API client
This Quickstart guide provides a code example of one of Lob’s core services: creating a postcard through our Print & Mail API. Make sure you are in the correct directory before running the code samples (creating one for the purpose of running these is advised, but not required).
Create a new directory and switch to it from your terminal app with these commands.
mkdir lob-qs
cd lob-qs
The next step is to install the version of Lob API which matches the language you are working in:
Install Lob's TypeScript SDK
npm install @lob/lob-typescript-sdk
Create a new virtual environment
python3 -m venv venv
Creating a Postcard via API
Now that a Lob API wrapper has been installed on your local machine, we can begin by sending a request to the API with the data necessary for postcard creation.
Open the text editor of your choice (if you need to download one, we recommend Visual Studio Code) and paste the code in the language of your choice: (As a note, if the address in question has a suite or apartment number, you can add in a data point for it as such: -d "to[address_line2]=<OPTIONAL SECONDARY INFORMATION>")
In your working directory:
Create a new file app.ts
Copy and paste the code below into app.ts
Data formatting
To ensure your requests are processed efficiently and without error, it's crucial to submit data in the precise format outlined in our documentation. Adhering to these specifications guarantees the continued reliability and performance of our API services.
For fields that are intended to accept only string values, submitting JSON objects in string format (stringified JSON objects) is not supported. Our system automatically parses and validates incoming data according to their expected types. As a result, providing a stringified JSON object in a field designated for string input can cause parsing errors or lead to unexpected validation results.
Understanding the response
This is a sample of the postcard object you will receive upon sending a creation request. Some information breakdowns:
As you can see, the to and from address objects have been expanded with more detail, including optional fields, creation and modification dates, and sanitized, verified address lines.
The postcard object also includes a signed URL to a digital copy of the created postcard, as well as thumbnails in three different sizes of the postcard’s front and back. Generated URLs are kept active for 30 days by default (or 60 seconds for HIPAA-enabled accounts) and can be regenerated by performing a new GET request on the mailpiece ID.
To see the postcards you have created, log into your and navigate to the “Postcards” tab on the left-side navigation menu. You can toggle between the ones you have created using either your test or live key:
More resources
Github
For more comprehensive code examples for the different languages supported by Lob, see the individual GitHub repositories for each language:
(see also, video)
Postman
You can also .
.
Mac
Run ruby -v to check whether it’s pre-installed. If not, run brew install ruby (make sure to install Homebrew first if you haven’t already). Add the path for your version of Ruby to your environment’s PATH variable.
Windows
Download the appropriate version from .
Mac
Runphp -vto check whether it’s pre-installed.
If not, runbrew install php(make sure to install Homebrew first if you haven’t already). Add the path for your version of PHP to your environment’s PATH variable.
In your working directory, you should have a file named Program.cs from running the dotnet new console command.
Copy and paste the code below into Program.cs.
Replace <YOUR_TEST_KEY> with your Lob Test API Key in the code.
In your working directory:
Run your app:
dotnet run
front_template_id and back_template_id are null in this particular object because we used inline HTML in the templates, rather than referencing a previously-saved HTML template.
Because we did not specify a size, the postcard is the default size of 4x6".
Both the send_date and the expected_delivery_date of the postcard are provided for transparency in the mailing process.
import lob_python
from lob_python.exceptions import ApiException
from lob_python.model.postcard_editable import PostcardEditable
from lob_python.model.address_editable import AddressEditable
from lob_python.model.merge_variables import MergeVariables
from lob_python.model.country_extended import CountryExtended
from lob_python.api.postcards_api import PostcardsApi
configuration = lob_python.Configuration(
username = "<YOUR_TEST_KEY>"
)
postcard_editable = PostcardEditable(
description = "First Postcard",
front = "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
back = "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>",
to = AddressEditable(
name = "Harry Zhang",
address_line1 = "210 King Street",
address_city = "San Francisco",
address_state = "CA",
address_zip = "94107",
),
_from = AddressEditable(
name = "Leore Avidar",
address_line1 = "210 King Street",
address_city = "San Francisco",
address_state = "CA",
address_zip = "94107",
address_country = CountryExtended("US")
),
merge_variables = MergeVariables(
name = "Harry",
),
)
with lob_python.ApiClient(configuration) as api_client:
api = PostcardsApi(api_client)
try:
created_postcard = api.create(postcard_editable)
print(created_postcard)
except ApiException as e:
print(e)
require 'lob.rb'
require 'pp'
lob = Lob::Client.new(api_key: "<TEST_API_KEY>")
pp lob.postcards.create(
description: "First Postcard",
to: {
name: "Harry Zhang",
address_line1: "210 King Street",
address_city: "San Francisco",
address_state: "CA",
address_zip: "94107"
},
from: {
name: "Leore Avidar",
address_line1: "210 King Street",
address_city: "San Francisco",
address_state: "CA",
address_zip: "94107"
},
merge_variables: { name: "Harry" },
front: "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
back: "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>"
)
<?php require __DIR__ . '/vendor/autoload.php';
$lob = new \Lob\Lob('<TEST_API_KEY');
$postcard = $lob->postcards()->create(array(
"description" => "First Postcard",
"to[name]" => "HARRY ZHANG",
"to[address_line1]" => "210 KING STREET",
"to[address_city]" => "SAN FRANCISCO",
"to[address_state]" => "CA",
"to[address_zip]" => "94107",
"from[name]" => "LEORE AVIDAR",
"from[address_line1]" => "210 KING STREET",
"from[address_city]" => "SAN FRANCISCO",
"from[address_state]" => "CA",
"from[address_zip]" => "94107",
"front" => "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
"back" => "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>",
"merge_variables[name]" => "Harry"
));
print_r($postcard);
?>
package com.company.app;
import com.lob.api.ApiClient;
import com.lob.api.ApiException;
import com.lob.api.Configuration;
import com.lob.api.auth.*;
import com.lob.model.*;
import com.lob.api.client.PostcardsApi;
public class App
{
public static void main( String[] args )
{
ApiClient lobClient = Configuration.getDefaultApiClient();
// Configure HTTP basic authorization: basicAuth
HttpBasicAuth basicAuth = (HttpBasicAuth) lobClient.getAuthentication("basicAuth");
basicAuth.setUsername("<YOUR_LOB_API_KEY>");
PostcardsApi apiInstance = new PostcardsApi(lobClient);
PostcardEditable postcardEditable = new PostcardEditable();
AddressEditable to = new AddressEditable();
to.setName("MORTICIA ADDAMS");
to.setAddressLine1("1313 CEMETERY LN");
to.setAddressCity("WESTFIELD");
to.setAddressState("NJ");
to.setAddressZip("07091");
AddressEditable to = new AddressEditable();
to.setName("MORTICIA ADDAMS");
to.setAddressLine1("1313 CEMETERY LN");
to.setAddressCity("WESTFIELD");
to.setAddressState("NJ");
to.setAddressZip("07091");
AddressEditable from = new AddressEditable();
from.setName("FESTER");
from.setAddressLine1("001 CEMETERY LN");
from.setAddressLine2("SUITE 666");
from.setAddressCity("WESTFIELD");
from.setAddressState("NJ");
from.setAddressZip("07091");
Gson gson = new Gson();
postcardEditable.setTo(gson.toJson(to));
postcardEditable.setFrom(gson.toJson(from));
postcardEditable.setFront("https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf");
postcardEditable.setBack("https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/4x6_pc_template.pdf");
try {
Postcard result = apiInstance.create(postcardEditable);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling PostcardsApi#postcardCreate");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
using System;
using System.Collections.Generic;
using System.Diagnostics;
using lob.dotnet.Api;
using lob.dotnet.Client;
using lob.dotnet.Model;
namespace test_dotnet
{
class Program
{
static void Main(string[] args)
{
Configuration config = new Configuration();
config.BasePath = "https://api.lob.com/v1";
// Configure HTTP basic authorization: basicAuth
config.Username = "<YOUR_TEST_KEY>";
Dictionary<string, string> mergeVariables = new Dictionary<string, string>();
mergeVariables.Add("name", "Harry");
PostcardsApi apiInstance = new PostcardsApi(config);
AddressEditable to = new AddressEditable(
"210 King St", // addressLine1
null, // addressLine2
"San Francisco", // addressCity
"CA", // addressState
"94107", // addressZip
CountryExtended.US, // addressCounty
"First Postcard", // description
"Harry Zhang" // name
);
AddressEditable from = new AddressEditable(
"210 King St", // addressLine1
null, // addressLine2
"San Francisco", // addressCity
"CA", // addressState
"94107", // addressZip
CountryExtended.US, // addressCounty
null, // description
"Leore Avidar" // name
);
PostcardEditable postcardEditable = new PostcardEditable(
to.ToJson(), // to
from.ToJson(), // from
default(PostcardSize), // size
"First Postcard", // description
null, // metadata
default(MailType), // mailType
mergeVariables, // mergeVariables
default(DateTime), // sendDate
"<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>", // front
"<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>" // back
);
try
{
// create
Postcard result = apiInstance.create(postcardEditable);
Console.WriteLine(result.ToString());
}
catch (ApiException e)
{
Console.WriteLine("Exception when calling PostcardsApi.create: " + e.Message );
Console.WriteLine("Status Code: "+ e.ErrorCode);
Console.WriteLine(e.StackTrace);
}
}
}
}
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
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.
To push your template to a Lob environment, use the 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.
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.
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
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 . The helpers below are supported.
For uniformity with Handlebars' terminology, we use the wordfalsey instead of the more commonly used falsy.
Array helpers
Returns all of the items in an array after the specified index. Opposite of .
Params
Comparison helpers
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.
String helpers
Append the specified suffix to the given string.
, or
[]
, Handlebars will not render the block.
When you pass the following input to the above template:
This will produce the result as below:
If the input is an empty JSONObject {}, then author will become undefined and if condition fails, resulting in the output as follow:
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".
#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.
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.
when used with this context:
will result in:
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.
When looping through items in each, you can optionally reference the current loop index via {{@index}}.
Additionally for object iteration, {{@key}} references the current key name:
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.
when used with this context:
will result in:
with can also be used with block parameters to define known references in the current block. The example above can be converted to
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.
#lookup
The lookup helper allows for dynamic parameter resolution using Handlebars variables.
This is useful for resolving values for array indexes.
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.
array{Array}: Collection
n{Number}: Starting index (number of items to exclude)
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.
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.
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.
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.
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.
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.
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.
Block helper that renders a block if a is equal tob. If an inverse block is specified it will be rendered when falsey. You may optionally use the compare="" hash argument for the second value.
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.
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.
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.
Block helper that renders a block if a is equal tob. If an inverse block is specified it will be rendered when falsey. Similar to eq but does not do strict equality.
Block helper that renders a block if a is not equal tob. If an inverse block is specified it will be rendered when falsey. Similar to unlessEq but does not use strict equality for comparisons.
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
array{Array}: The array to iterate over
size{Number}: The desired length of each array "group"
<!-- var value = "example" -->
{{equalsLength value 7}}
<!-- results in: true -->
<!-- var value = "example" -->
{{equalsLength value 5}}
<!-- results in: false -->
<!-- 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'] -->
<!-- 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.' -->
<!-- array = ['a', 'b', 'c'] -->
{{#contains array "d"}} This will not be rendered.{{else}} This will be rendered.{{/contains}}
{
"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' →
