Skip to content
PostGrid PostGrid
Get started
Overview

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.

Verify
POST/v1/addver/verifications
Get Lookup Info
GET/v1/addver/
Get Autocomplete Previews
GET/v1/addver/completions
Autocomplete
POST/v1/addver/completions
Batch Verification
POST/v1/addver/verifications/batch
Suggest Addresses
POST/v1/addver/suggestions
Parse An Address
POST/v1/addver/parses
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.

Verify
POST/v1/intl_addver/verifications
Batch Verification
POST/v1/intl_addver/verifications/batch
Get Autocomplete Previews
GET/v1/intl_addver/completions
Get Autocomplete Advanced Previews
GET/v1/intl_addver/completions
Autocomplete
POST/v1/intl_addver/completions
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}
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}

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
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
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
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}
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
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

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

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}

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

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 support@postgrid.com

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}

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 support@postgrid.com

Sample a Saved Report
POST/print-mail/v1/reports/{id}/samples

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 support@postgrid.com

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}

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 support@postgrid.com

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
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

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 support@postgrid.com

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

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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

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}

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 support@postgrid.com

Create Virtual Mailbox
POST/print-mail/v1/virtual_mailboxes
List Virtual Mailboxes
GET/print-mail/v1/virtual_mailboxes
Retrieve Virtual Mailbox
GET/print-mail/v1/virtual_mailboxes/{id}
Retrieve Physical Address
GET/print-mail/v1/virtual_mailboxes/{id}/address

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 support@postgrid.com

List Virtual Mailbox Items
GET/print-mail/v1/virtual_mailboxes/{id}/items
Create Test Virtual Mailbox Item
POST/print-mail/v1/virtual_mailboxes/{id}/items
Retrieve Virtual Mailbox Item
GET/print-mail/v1/virtual_mailboxes/{id}/items/{itemID}