Getting Started
A simple API to send letters, postcards, and cheques. You can integrate this API to automate your transactional mailings and/or provide offline sending capabilities to your users.
If you just want to perform one-off sends, you can also do so directly from the API dashboard at https://dashboard.postgrid.com/
API Keys
Every user in your organization will be provided 2 API keys which they can access from their settings: the test key and the live key. Any API calls made with the test key operate in an isolated sandbox. None of the resources you manage in test mode will affect your live environment, and vice versa.
You can try out your integration using the Test API key. There is no difference other than the fact that we do not verify addresses in test mode. Also, more importantly, none of the orders made in test mode will be sent out. Once you've tested your integration, you can switch to the live API key and it will just work.
Test orders will also transition from ready to completed at the same time (equivalent) live orders would transition into printing.
More details can be found here, in the official API documentation. With each request, be sure to include the x-api-key header with your API key as the value.
SDKs
We currently offer SDKs for two languages: Python and NodeJS. Both can be installed from their respective package managers.
Design
There are two primary ways of providing printable content to this API: you can either send predesigned PDFs or provide HTML with personalizable variables. In either case, the address information will automatically be stamped on the final mailing.
For letters, the destination and return addresses are stamped on the first page of your mailing by default. Refer to the following table:
| Country | Guideline |
|---|---|
| Canada | Click here |
| United Kingdom | Click here |
| US & Intl. | Click here |
| Australia | Click here |
| Country | Page Size |
|---|---|
| Canada | 8.5 x 11 inches |
| United Kingdom | 8.3 x 11.7 inches |
| US & Intl. | 8.5 x 11 inches |
| Australia | 8.25 x 11.75 inches |
All content underneath the indicated region is covered. If you do not want this, you can also insert a blank page just for the address via the letters API addressPlacement parameter.
For postcards, the guideline varies depending on size and country. Refer to the following table
Canada
United Kingdom & Europe
Note that for the UK postcards, the red zone's width is half the width of the postcard itself.
US & International
For cheques, the message HTML can cover 7 inches from the top of the first page to the top of the cheque. There is a 0.3in margin applied to this message as it is required for optimal printing.
Letter Size
By default, the letter size will be chosen based on the destination country. You can override this to get a specific letter size by supplying a size parameter with one of the other size options us_letter, us_legal, a4.
| Country | Allowed Options |
|---|---|
| US | us_letter, us_legal |
| UK | a4 |
| Rest of the world | us_letter |
Cheque Size
By default, the cheque size will be chosen based on the destination country. You can override this to get a specific cheque size by supplying a size parameter with one of the other size options us_letter or us_legal.
| Country | Allowed Options |
|---|---|
| US | us_letter, us_legal |
| Rest of the world | us_letter |
Authorization
All requests here can be authorized via an x-api-key header. If you're using cURL, you can also supply the key using the shorthand -u YOUR_API_KEY:
You can retrieve your API key from the dashboard inside the 'Settings' page.
Request Bodies
All request bodies can be specified in application/json or application/x-www-form-urlencoded. For the endpoints that require uploading a file, you can supply the body as multipart/form-data.
Note that the examples here use the URL encoded format. However, this maps easily into JSON. Wherever you see e.g. to[addressLine1]=Example, that's equivalent to
"to": { "addressLine1": "Example" }
in JSON.
Idempotent Requests
Our API supports idempotence on our order creation endpoints. This allows you to safely retry API calls without creating duplicate orders. This also makes your code more robust in the presence of network issues which disrupt API calls. As such, we highly recommend you make use of this feature.
In order to make your order creation calls idempotent, you must supply an additional Idempotency-Key: header. If your request validates successfully, we will ensure that subsequent requests with an identical idempotency key made up to 24 hours after the initial will return the exact same response without creating any orders. This includes error responses.
You are free to generate your keys however you like, but we suggest using V4 UUIDs.
Errors
All of our error responses contain an error top-level object. This is what it looks like.
| Name | Type | Description |
|---|---|---|
| type | string | An computer friendly stable string like invalid_pdf_error |
| message | string | A human-readable description of the error |
Lists and Pagination
All of our listing endpoints are paginated and produce responses according to the List schema. These endpoints receive a skip and limit parameter which can be used to traverse the pages. You can traverse a complete list by incrementing skip by limit for each request until skip >= totalCount, where totalCount is returned in the list response.
Search
Our resource listing endpoints such as GET /contacts and GET /letters provide advanced search capabilities. You can perform this search via a search query parameter, or use the search field on our dashboard.
For example GET /v1/contacts?search="New York" (i.e. search="New York") will produce all the contacts that have the exact string "New York" in their body.
You can also perform structured queries like GET /v1/letters?search={"metadata.campaignID": "ABC"} which searches for
{
"metadata.campaignID": "ABC"
}
In other words, this will produce all the letters whose campaignID matches ABC.
Expansions
Some of our endpoints return resources with nested IDs. For example, when you retrieve a letter that was created from a template, its body will contain the template ID. Rather than making a separate API request for the nested template, you can pass along an query parameter like GET /letters?expand[]=template.
This also works for getting the nested bankAccount inside a cheque. However, it is important to note that you cannot do this for the listing endpoints due to its performance implications.
Metadata
Every object in the API can have arbitrary metadata attached to it. For example, you can tag yourletters with a campaign ID:
{
// Other letter fields...
"metadata": {
"campaignID": "ABC"
}
}
You can then get analytics on these letters using the advanced search functionality in the dashboard.
The metadata object must not exceed 10kb of uncompressed storage.
Merge Variables
Whenever you supply HTML to the API via a Template, directly inside a Letter, Postcard, or in the message of a Cheque, you can specify variable fields using curly braces like {{variableName}}. You can then supply a mergeVariables object in your POST requests, and provide values for them.
mergeVariables on a request can contain arbitrarily nested objects. For example
{
"income": {
"beforeTax": 100,
"afterTax": 73
}
}
and these can be referenced by using a . to access nested fields {{income.beforeTax}} and {{income.afterTax}}. Note that variable names (e.g. income****, beforeTax****, afterTax****) cannot contain the characters ', # $' .
You can also access the following predefined merge variables in your template
| Name | Type | Description |
|---|---|---|
| to | Contact | The recipient info e.g. to.firstName, to.companyName |
| from | Contact | The sender info e.g. from.firstName, from.companyName |
PDF Previews
We provide PDF previews for all orders (including those created in test mode). These previews should be generated a few seconds after you create an order. They can be accessed through the url property of the returned objects or on the dashboard by clicking View PDF on the top-right of the order details page.
In the case of cheques, the previews will censor the account number by padding the last 4 digits of the account number with zeros.
Updated about 2 months ago