API Reference

Libraries

TypeScript

0.0.1

npm install postgrid-node

Read Docs

Python

0.0.1

pip install postgrid-python

Read Docs

API Overview

Address Verification

Standard Address Verification API.

Provides endpoints to verify and standardize addresses across US and Canada, supporting both structured and freeform inputs.

Note that this uses a different set of lookups than our international API.

Lookup City Or State From Postal Or Zip Code

POST/v1/addver/city_states

Lookup Zip Code From City Or State

POST/v1/addver/zip_codes

Intl Address Verification

International Address Verification API.

Provides endpoints to verify and standardize international addresses, supporting both structured and freeform inputs.

Get Autocomplete Advanced Previews

GET/v1/intl_addver/completions

Bulk Verification

Note: For verifying batches of addresses in real-time via JSON, please use the “Batch Verify Addresses” endpoint.

The bulk verification API allows you to submit CSV files to be processed through our address verification engine. Each file can contain up to 250,000 addresses, and the output lines up with what is returned from our batch verification API.

Note that you will be invoiced for every list that processes successfully. You can pre-purchase bulk verification credits from our dashboard to prevent this. However, these cannot be used for geocoded lists, and you must individually pay for every list that you process with those flags.

Also note that in order to access bulk geocoding you must contact [email protected] to enable the feature.

Upload

POST/v1/addver_lists

List

GET/v1/addver_lists

Retrieve

GET/v1/addver_lists/{id}

Print Mail

Print MailContacts

Manage contacts that you can mail to. Test mode addresses will always have a verified status. In live mode, they may be verified, corrected, or failed. Addresses that fail to be corrected are likely undeliverable, but you can still send to them if you want to.

For test mode contacts, you have the ability to assert the addressStatus of the contact by passing specific values to the description field. To receive an addressStatus of failed, the description of the contact should be a string with the exact value test failed. For an addressStatus value of corrected, the description of the contact should be a string with the exact value test corrected.

Our address correction engine will often be able to fix missing postal/ZIP codes, city names, and also append ZIP+4. It is SERP (Canada Post) and CASS (USPS) certified, so you can rest assured that if an address is verified, we can deliver to it.

Create Contact

POST/print-mail/v1/contacts

List Contacts

GET/print-mail/v1/contacts

Get Contact

GET/print-mail/v1/contacts/{id}

Delete Contact

DELETE/print-mail/v1/contacts/{id}

Print MailTemplates

Create and manage reusable HTML templates. A template’s HTML can include merge variables (e.g. {{firstName}}) and be referenced by ID when creating letters, postcards, cheques, and self mailers.

Create Template

POST/print-mail/v1/templates

List Templates

GET/print-mail/v1/templates

Get Template

GET/print-mail/v1/templates/{id}

Update Template

POST/print-mail/v1/templates/{id}

Delete Template

DELETE/print-mail/v1/templates/{id}

Print MailTrackers

Create and manage Trackers.

Trackers can be used to track interactions in your orders through personalized URLs and QR codes.

As a brief introduction to using Trackers in your orders, a QR code can be generated by using the Tracker’s ID as a merge variable in your orders HTML and Templates. The following example HTML uses Trackers to generate personalized URLs (PURLs) in your orders.

See the following guide for more details: https://postgrid.readme.io/reference/trackers-1

Create Tracker

POST/print-mail/v1/trackers

List Trackers

GET/print-mail/v1/trackers

Update Tracker

POST/print-mail/v1/trackers/{id}

Get Tracker

GET/print-mail/v1/trackers/{id}

Delete Tracker

DELETE/print-mail/v1/trackers/{id}

List Tracker Visits

GET/print-mail/v1/trackers/{id}/visits

Print MailWebhooks

Create and manage Webhooks.

Webhooks can be used to notify your application when events occur in PostGrid. For example, you may use a letter.updated webhook to receive a notification when a letter has been processed for delivery.

Every webhook has a secret and this is used to sign the payload of the event.

You can choose what format you want the payload to be delivered in. By default, the webhook payload will be delivered as a JSON Web Token. When you receive the event, you can verify it using a JWT library available for your particular language (using the HMAC SHA256 Algorithm). There are many off-the-shelf solutions you can use.

You can alternatively choose to receive a JSON payload. In this case, you’ll also receive a PostGrid-Signature HTTP header along with the payload.

You must respond with a 200 status from your webhook. Otherwise, PostGrid will retry the webhook up to 3 times. First, after 1 hour, then 2 hours, then 4 hours. We will also keep track of every invocation and its response status. You can retrieve data about prior invocations using the webhook invocations list endpoint below.

Create Webhook

POST/print-mail/v1/webhooks

List Webhooks

GET/print-mail/v1/webhooks

Update Webhook

POST/print-mail/v1/webhooks/{id}

Get Webhook

GET/print-mail/v1/webhooks/{id}

Delete Webhook

DELETE/print-mail/v1/webhooks/{id}

List Webhook Invocations

GET/print-mail/v1/webhooks/{id}/invocations

Print MailEvents

View Events related to your orders.

An event is created whenever a webhook is triggered. For example, if a webhook is created that listens to letter.updated events and the delivery status of a letter is updated, an event detailing the updated fields will get created.

List Events

GET/print-mail/v1/events

Print MailLetters

Create and manage letter orders.

Create Letter Create Letter

POST/print-mail/v1/letters

List Letters

GET/print-mail/v1/letters

Get Letter

GET/print-mail/v1/letters/{id}

Cancel Letter

DELETE/print-mail/v1/letters/{id}

Get Letter Preview

GET/print-mail/v1/letters/{id}/url

Cancel Letter With Note

POST/print-mail/v1/letters/{id}/cancellation

Progress Status

POST/print-mail/v1/letters/{id}/progressions

Print MailPostcards

Create and manage postcard mailings.

Create Postcard Create Postcard

POST/print-mail/v1/postcards

List Postcards

GET/print-mail/v1/postcards

Get Postcard

GET/print-mail/v1/postcards/{id}

Cancel Postcard

DELETE/print-mail/v1/postcards/{id}

Get Postcard Preview

GET/print-mail/v1/postcards/{id}/url

Cancel Postcard With Note

POST/print-mail/v1/postcards/{id}/cancellation

Progress Status

POST/print-mail/v1/postcards/{id}/progressions

Print MailBank Accounts

Manage bank accounts that will be used for mailing cheques.

Create Bank Account

POST/print-mail/v1/bank_accounts

List Bank Accounts

GET/print-mail/v1/bank_accounts

Get Bank Account

GET/print-mail/v1/bank_accounts/{id}

Delete Bank Account

DELETE/print-mail/v1/bank_accounts/{id}

Print MailCheques

Create and manage cheque orders.

Create Cheque

POST/print-mail/v1/cheques

List Cheques

GET/print-mail/v1/cheques

Get Cheque

GET/print-mail/v1/cheques/{id}

Cancel Cheque

DELETE/print-mail/v1/cheques/{id}

Get Cheque Preview

GET/print-mail/v1/cheques/{id}/url

Retrieve Cheque Deposit-Ready PDF (Digital Only)

GET/print-mail/v1/cheques/{id}/with_deposit_ready_pdf

Cancel Cheque With Note

POST/print-mail/v1/cheques/{id}/cancellation

Progress Status

POST/print-mail/v1/cheques/{id}/progressions

Print MailSelf Mailers

Create and manage self mailers.

Create Self Mailer Create Self Mailer

POST/print-mail/v1/self_mailers

List Self Mailers

GET/print-mail/v1/self_mailers

Get Self Mailer

GET/print-mail/v1/self_mailers/{id}

Cancel Self Mailer

DELETE/print-mail/v1/self_mailers/{id}

Get Self Mailer Preview

GET/print-mail/v1/self_mailers/{id}/url

Progress Status

POST/print-mail/v1/self_mailers/{id}/progressions

Print MailReturn Envelopes

You can use the return envelopes API to create and manage return envelopes. These are envelopes that are sent along with your mail (if specified) and allow your recipients to send mail to a particular address without having to purchase their own envelopes/stamps.

Note that you must order return envelopes and wait for the order to be filled before you can use them. You can manage these return envelope orders via the API as well as the dashboard.

Create Return Envelope

POST/print-mail/v1/return_envelopes

List Return Envelopes

GET/print-mail/v1/return_envelopes

Get Return Envelope

GET/print-mail/v1/return_envelopes/{id}

Print MailReturn EnvelopesOrders

Note that you must order return envelopes and wait for the order to be filled before you can use them. You can manage these return envelope orders via the API as well as the dashboard.

Create Return Envelope Order

POST/print-mail/v1/return_envelopes/{id}/orders

List Return Envelope Orders

GET/print-mail/v1/return_envelopes/{id}/orders

Get Return Envelope Order

GET/print-mail/v1/return_envelopes/{id}/orders/{orderID}

Fill Test Return Envelope Order

POST/print-mail/v1/return_envelopes/{id}/orders/{orderID}/fills

Cancel Return Envelope Order

DELETE/print-mail/v1/return_envelopes/{id}/orders/{orderID}

Print MailCampaigns

The campaigns API enables you to send out large volumes of fully personalized mail to a mailing list.

Create Campaign

POST/print-mail/v1/campaigns

List Campaigns

GET/print-mail/v1/campaigns

Get Campaign

GET/print-mail/v1/campaigns/{id}

Update Campaign

POST/print-mail/v1/campaigns/{id}

Delete Campaign

DELETE/print-mail/v1/campaigns/{id}

Send Campaign

POST/print-mail/v1/campaigns/{id}/send

Print MailMailing List Imports

The mailing list imports API enables you to import contact lists from files and validate them for use in campaigns.

Create Mailing List Import

POST/print-mail/v1/mailing_list_imports

List Mailing List Imports

GET/print-mail/v1/mailing_list_imports

Update Mailing List Import

POST/print-mail/v1/mailing_list_imports/{id}

Get Mailing List Import

GET/print-mail/v1/mailing_list_imports/{id}

Delete Mailing List Import

DELETE/print-mail/v1/mailing_list_imports/{id}

Print MailMailing Lists

The mailing lists API enables you to manage collections of contacts that can be used for bulk mail campaigns.

Create Mailing List

POST/print-mail/v1/mailing_lists

List Mailing Lists

GET/print-mail/v1/mailing_lists

Get Mailing List

GET/print-mail/v1/mailing_lists/{id}

Update Mailing List

POST/print-mail/v1/mailing_lists/{id}

Delete Mailing List

DELETE/print-mail/v1/mailing_lists/{id}

Submit a Mailing List Job

POST/print-mail/v1/mailing_lists/{id}/jobs

Print MailReports

The reports API lets you run SQL queries against a data lake with all of your PostGrid data. You can use this to run ad-hoc SQL queries or save them as reports. You can bulk export data from these reports to fit all of your reporting needs. Note that the data this API provides may be up to 2 hours behind your current PostGrid environment. Your test and live data lakes are fully segregated, so you’ll need a live API key to run queries against your live data.

You can request access to this to this feature by reaching out to [email protected]

Create Saved Report

POST/print-mail/v1/reports

Run Ad-hoc Query

POST/print-mail/v1/reports/samples

Update Report

POST/print-mail/v1/reports/{id}

List Saved Reports

GET/print-mail/v1/reports

Retrieve Saved Report

GET/print-mail/v1/reports/{id}

Delete Saved Report

DELETE/print-mail/v1/reports/{id}

Print MailReportsSamples

You can request access to this to this feature by reaching out to [email protected]

Sample a Saved Report

POST/print-mail/v1/reports/{id}/samples

Print MailReportsExports

You can request access to this to this feature by reaching out to [email protected]

Create a Report Export

POST/print-mail/v1/reports/{reportID}/exports

Get Report Export

GET/print-mail/v1/reports/{reportID}/exports/{exportID}

Delete Report Export

DELETE/print-mail/v1/reports/{reportID}/exports/{exportID}

Print MailSub Organizations

Sub-organizations enable you to create isolated PostGrid accounts (“sub-organizations”) under your PostGrid account (the “parent organization”). Each sub-organization has fully isolated resources and users, and can act independently.

This allows you to isolate different departments or even re-sell PostGrid entirely.

You can request access to this feature by reaching out to [email protected]

Create a sub-organization.

POST/print-mail/v1/sub_organizations

List sub-organizations.

GET/print-mail/v1/sub_organizations

Get a sub-organization.

GET/print-mail/v1/sub_organizations/{id}

List users for a sub-organization.

GET/print-mail/v1/sub_organizations/{id}/users

Print MailBoxes

Create and manage box orders.

Create Box

POST/print-mail/v1/boxes

List Boxes

GET/print-mail/v1/boxes

Get Box

GET/print-mail/v1/boxes/{id}

Cancel Box

DELETE/print-mail/v1/boxes/{id}

Progress Status

POST/print-mail/v1/boxes/{id}/progressions

Print MailSnap Packs

Snap packs are pressure-sealed mailers that resemble official documents and encourage higher open rates. They do not require envelopes and are opened by tearing along perforated edges. The sealed design keeps contents hidden until opened, making snap packs ideal for sensitive or important documents such as contracts, forms, or notices.

You can request access to this feature by reaching out to [email protected]

Create Snap Pack Create Snap Pack

POST/print-mail/v1/snap_packs

List Snap Packs

GET/print-mail/v1/snap_packs

Capabilities

GET/print-mail/v1/snap_packs/capabilities

Get Snap Pack

GET/print-mail/v1/snap_packs/{id}

Cancel

DELETE/print-mail/v1/snap_packs/{id}

Progress Status

POST/print-mail/v1/snap_packs/{id}/progressions

Print MailTargeted List Builds

Beta: the targeted list builds API is in beta and is subject to breaking changes. Endpoint shapes, status values, and filter fields may change without notice.

The targeted list builds API lets you programmatically build mailing lists of US consumers (B2C) or US companies (B2B) that match a set of demographic, geographic, and firmographic filters.

The lifecycle of a list build is:

Create a list build by supplying either usConsumers or usCompanies filters. A quote is generated asynchronously — poll the resource or wait for its status to become quote_ready.
Review the quote (total count and price per contact) and masked previewRecords. Adjust the filters with an update call if needed — this will regenerate the quote.
Confirm the build. This deducts the appropriate amount of list build credits from your organization (in live mode) and begins constructing the mailing list. buildProgressPercent reflects progress from 0 to 100.
Once status is completed, the ID of the resulting mailing list is available in the mailingList field and can be used like any other mailing list in the PostGrid API.

Targeted list builds must be enabled on your organization before they can be used. Contact PostGrid support to request access.

Create Targeted List Build

POST/print-mail/v1/targeted_list_builds

List Targeted List Builds

GET/print-mail/v1/targeted_list_builds

Get Targeted List Build

GET/print-mail/v1/targeted_list_builds/{id}

Update Targeted List Build

POST/print-mail/v1/targeted_list_builds/{id}

Delete Targeted List Build

DELETE/print-mail/v1/targeted_list_builds/{id}

Confirm Targeted List Build

POST/print-mail/v1/targeted_list_builds/{id}/confirm

Print MailTargeted List BuildsFilters

Beta: the targeted list builds API is in beta and is subject to breaking changes. Endpoint shapes, status values, and filter fields may change without notice.

The targeted list builds API lets you programmatically build mailing lists of US consumers (B2C) or US companies (B2B) that match a set of demographic, geographic, and firmographic filters.

The lifecycle of a list build is:

Create a list build by supplying either usConsumers or usCompanies filters. A quote is generated asynchronously — poll the resource or wait for its status to become quote_ready.
Review the quote (total count and price per contact) and masked previewRecords. Adjust the filters with an update call if needed — this will regenerate the quote.
Confirm the build. This deducts the appropriate amount of list build credits from your organization (in live mode) and begins constructing the mailing list. buildProgressPercent reflects progress from 0 to 100.
Once status is completed, the ID of the resulting mailing list is available in the mailingList field and can be used like any other mailing list in the PostGrid API.

Targeted list builds must be enabled on your organization before they can be used. Contact PostGrid support to request access.

Autocomplete Filter Values

POST/print-mail/v1/targeted_list_builds/filters/autocomplete

Print MailTemplate Editor Sessions

You can use template editor sessions to bring the capabilities of our template editor to your website. When you create a session, you provide the template which you want to edit, and we return a session with a url that you can iframe or redirect your customers to.

When users save their changes in the editor session, it will update the underlying template. Note that sessions are only valid for 24 hours, after which point they are automatically deleted for security reasons.

You can have multiple sessions active for the same template at the same time. In general, we recommend creating a new session every time you present our editor to your users.

Note: you can use the template editor to modify templates created using HTML, but saving a session from the editor will override the original HTML content.

Create Session

POST/print-mail/v1/template_editor_sessions

List Sessions

GET/print-mail/v1/template_editor_sessions

Delete Session

DELETE/print-mail/v1/template_editor_sessions/{id}

Print MailVirtual Mailboxes

Virtual mailboxes let you receive, scan, and forward your physical mail without needing a traditional physical mailbox. Each mailbox is fully digital, giving you a unique ID, status, and a set of capabilities such as forwarding mail to another address or viewing envelope scans. This allows you to manage physical correspondence entirely online.

You can request access to this feature by reaching out to [email protected]

Print MailVirtual MailboxesItems

You can request access to this feature by reaching out to [email protected]