Introduction

This is designed to be a quick introduction some core concepts

45 Second Overview

TryPaper provides an API that will print and mail documents for you. You can add mailings using our API by providing the return address, recipient address, and the contents (stuff we'll print) for the mailing. Once you've sent us the mailing, we'll automatically batch any additional mailings over the next 24 hours. At the end of that period we'll begin the process of:

  • Download/Convert anything you sent us that wasn't a PDF
  • Scrubs addresses (Zip+4 lookup, and other fixes)
  • Build address wrapper pages so you don't have to format your document to line up in the envelope windows
  • Print, package and mail your documents

The API can be used with any programming language, but we've written (and are working on more) client libraries for .NET, Ruby, Python, Java, and PHP. Each client has a quick start guide available.

Authorization & Security

In order to use the API you'll need an API key. Your API key can be found on your account dashboard by clicking the eye icon to make it visible ( ). This key will always start with the letters 'TP'.

This key should be kept private. Only persons you want sending mailings on your behalf should have access to this key. If you feel it's been compromised, you can generate a new one at any time and the old key will become invalid immediately.

TryPaper uses basic HTTP authentication, simply append the 'Authorization' header to each of your requests with your API key. If you're using one of our pre-built client libraries, we'll do this automatically for you.

Additionally, ALL requests must be made using HTTPS. Requests to non HTTPS endpoints will result in either a redirect (HTTP 304) to the HTTPS endpoint, or a bad request (HTTP 400) endpoint.

Data Serialization

TryPaper supports both JSON and XML seralization though we prefer JSON due to reduced verbosity. This can be controlled with the HTTP headers of 'Accept' and 'Content-Type'. JSON should be presented as 'application/json' and XML as 'text/xml'.

Creating your first mailing

Sending your first mailing is super easy. A single HTTP POST to https://api.trypaper.com/v1/Mailing with a valid payload get's it done. Let's take a look at the key compontents of a mailing:

Mailings have four (4) components that you'll specify:

  1. Id - a unique string (to your account) for your mailing.
  2. Return Address (SenderKey) - A string representing the addresss you want to use as the return address
  3. Recipient - The address of the recipient
  4. Content - The content to print, fold, and mail. This can be a link (http://www.myserver.com/path/to/the/file") to a PDF or HTML file, or a base64 encoded PDF file

Show JSON Example

If no Batch was specified, we create a batch for you automatically that will close and start printing 24 hours later. Any additional mailings added over the next 24 hours with no batch specified will automatically be placed in the same batch.

Spooling (Processing) your mailings/batches

Once you're ready to have us print and mail your (um....) mailings, we'll begin to spool (process) your mailings. There are two ways to begin this process.

  • Automatically - If you didn't specify a batch when adding the mailing OR you created a batch and specified the AutoSpoolDate
  • Manually - You can send a Batch ID to the /v1/Spool endpoint and we'll begin processing
Once you've spooled the documents, we automatically do the the following things:
  • Downloads any content that wasn't base64 encoded (contents you linked to)
  • Converts any HTML files to PDF (you can see what this looks like at //TODO: link to the HTML to PDF converter)
  • Scrubs addresses (we'll do our best to scrub addresses and do things such as Zip+4 lookup, and other normalization)
  • Build address wrapper pages so you don't have to format your document to line up in the envelope windows
  • Schedules your documents to be printed, packaged and mailed (within 1 business day)

Once we've scheduled your documents to be printed we'll authorized the credit card on file and finalize the charge once we've printed and put the final product in the mail stream.

Next: Vocab