LetterStream API Information

Getting Started

LetterStream offers an API for tech-savvy businesses looking to streamline and automate mailing workflows, eliminating the manual labor from the entire process (including interacting with our portal).

This guide outlines the API’s capabilities, available modes, and how to get started based on your integration goals.

In This Article

General Requirements

To use the LetterStream API, here are a few things to keep in mind:

  • Your system must be able to generate PDF and CSV files
  • Mailings are not processed until paid for
  • Use the PrePay option and enable a Low Balance Alert for a seamless experience
  • A developer is required—whether in-house or contracted—to complete the integration

Features & Benefits

The LetterStream API offers multiple benefits to enhance efficiency and visibility of your mailing operations such as:

  • Instantaneous Job Submission: Submit mail jobs quickly for fast processing and mail out.
  • API‑Accessible Data: Information that can be requested via the API:
    • Proofs
    • Pricing
    • Mail Date
    • Job Status
    • Tracking information for Certified Mail
    • Delivery Signatures for Certified Mail with ERR
  • Developer Resources: Once the API is activated, you will have access to sample files and code directly within your LetterStream account to help you integrate quickly.

Supported Mail Types

The API supports:

  • USPS First-Class Mail (optional “Homeowner Statement Enclosed” endorsement)
  • Certified Mail (with or without Electronic Return Receipt)
  • Flats
  • Postcards

API Modes

Choose the mode that best fits your goals:

Automation Mode

Some organizations are just looking for ways to speed up the process of getting mailings created. Those who want Automation are the mail owners and will use the API internally to help their departments. Insurance organizations and high-volume compliance mailers enjoy the benefits of this version.

  • Best for internal use to automate and speed up your own mail processes
  • Easiest and quickest to implement
  • LetterStream provides platform support

Monetization Mode

Some organizations realize the power of automation and want to hide (or not) LetterStream in the background, thus taking advantage of all that LetterStream has to offer and yet fulfilling the mailing request for their clients. These organizations can mark up the price of the LetterStream product, creating a powerful revenue stream.

  • Allows you to sell LetterStream services to your customers
  • You manage pricing, billing, and customer support for your clients
  • LetterStream will have no relationship with your customers
  • Customer mailings are processed under your single, master LetterStream account

Partnership Mode

Some organizations have software that generates print-ready mailing documents for their subscribers. Often, these are client apps or SAAS (Software as a Service) providers. The Partnership arrangement sends the documents into their clients' LetterStream account. It's not a revenue model, but it does make things simple for your users.

  • Your customers create their own accounts via your special partner link
  • Customers pay LetterStream directly at standard prices
  • LetterStream supports customers on the LetterStream website (login issues, mail creation questions, etc.)
  • You assist customers with account setup, integration, and inquiries related to your software

API Activation Process

The API is not enabled in your LetterStream account by default. Send us an email to discuss your needs and confirm API suitability. Once approved, you will be able to access API documentation under the My Account tab in your account.

Note: I Integration must be handled by your developers—LetterStream does not implement integration. To help developers implement our API quickly, sample files and sample code is available within LetterStream accounts after API activation.

Reviews

Here is a link to an article in CIO Review magazine about the strategy behind our API:

Common API Questions


Question Answer
If I query a batch or job status and it is "Mailed" does that mean all pieces went out? Is there some kind of flag to indicate I need to get more detailed status at doc level? Yes, a job status includes all pieces within the job. If a job status is "Mailed" there is no reason to check the doc.
Is the Intelligent Mail Barcode (IMB) on the envelope one you are printing? Or that was put on it later by USPS in their processing? Just asking in case, if the former, you were looking at pulling data from USPS for First Class, which can get you to "Out for Delivery". Currently the IMB is applied downstream but we will likely be placing that in the near future.
Am I correct those statuses are just pushed every few hours? Correct, every 4 hours.
Are the statuses historical/cumulative? Or only includes records for new events that occurred since the last push? Since the last push.
If we have some problem on our end at time of a push, are those statuses lost, or you hold and resend later at next regular interval? If your system does not respond with a success code, we will attempt to resend. Once your system accepts a push that information, while not lost, will not be sent again via the callback.
Does the callback status give us your internal status (like the status pull queries) or just USPS? If it is First Class, is there any USPS status? I'd have to verify, but off the top of my head, that only includes USPS data and is only available for certified mail at this time.
What is the difference between BATCH and POST (batch vs. post)?

Post is for the submission of a single letter to one or more recipients. Batch is primarily for submitting lots of letters to lots of recipients, but can also be used for one letter to one recipient. Both options require that the address data is sent separate of the pdf. In the post method, the address data is sent as an argument. In the batch method all address/document data is sent in a csv.


Example: If you had a 1,000 recipients with unique 1pg letters and you used post, you'd create 1,000 jobs in our system. If you did the same with batch, you'd create 1 job.
If my account is in TEST mode and I want to see the kind of data that is returned as part of the callback, is there a way to see sample callback JSON without sending mail? At the bottom of the API Callback section on the API Information page there are 4 buttons for sending test data. Clicking "Push JSON Sample to Endpoint" will send sample data to your endpoint.