Skip to content
PostGrid PostGrid
Get startedDashboardSupport
API Reference

Print Mail

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
client.printMail.contacts.create(ContactCreateParamsbody, RequestOptionsoptions?): Contact { id, addressLine1, addressStatus, 21 more }
POST/print-mail/v1/contacts
List Contacts
client.printMail.contacts.list(ContactListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<Contact { id, addressLine1, addressStatus, 21 more } >
GET/print-mail/v1/contacts
Get Contact
client.printMail.contacts.retrieve(stringid, RequestOptionsoptions?): Contact { id, addressLine1, addressStatus, 21 more }
GET/print-mail/v1/contacts/{id}
Delete Contact
client.printMail.contacts.delete(stringid, RequestOptionsoptions?): ContactDeleteResponse { id, deleted, object }
DELETE/print-mail/v1/contacts/{id}
ModelsExpand Collapse
One of the following:
One of the following:

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
client.printMail.templates.create(TemplateCreateParams { description, html, metadata } body, RequestOptionsoptions?): Template { id, createdAt, live, 5 more }
POST/print-mail/v1/templates
List Templates
client.printMail.templates.list(TemplateListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<Template { id, createdAt, live, 5 more } >
GET/print-mail/v1/templates
Get Template
client.printMail.templates.retrieve(stringid, RequestOptionsoptions?): Template { id, createdAt, live, 5 more }
GET/print-mail/v1/templates/{id}
Update Template
client.printMail.templates.update(stringid, TemplateUpdateParams { description, html, metadata } body, RequestOptionsoptions?): Template { id, createdAt, live, 5 more }
POST/print-mail/v1/templates/{id}
Delete Template
client.printMail.templates.delete(stringid, RequestOptionsoptions?): TemplateDeleteResponse { id, deleted, object }
DELETE/print-mail/v1/templates/{id}
ModelsExpand Collapse

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
client.printMail.trackers.create(TrackerCreateParams { redirectURLTemplate, urlExpireAfterDays, description, metadata } body, RequestOptionsoptions?): TrackerCreateResponse { id, createdAt, live, 8 more }
POST/print-mail/v1/trackers
List Trackers
client.printMail.trackers.list(TrackerListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<TrackerListResponse { id, createdAt, live, 8 more } >
GET/print-mail/v1/trackers
Update Tracker
client.printMail.trackers.update(stringid, TrackerUpdateParams { redirectURLTemplate, urlExpireAfterDays, description, metadata } body, RequestOptionsoptions?): TrackerUpdateResponse { id, createdAt, live, 8 more }
POST/print-mail/v1/trackers/{id}
Get Tracker
client.printMail.trackers.retrieve(stringid, RequestOptionsoptions?): TrackerRetrieveResponse { id, createdAt, live, 8 more }
GET/print-mail/v1/trackers/{id}
Delete Tracker
client.printMail.trackers.delete(stringid, RequestOptionsoptions?): TrackerDeleteResponse { id, deleted, object }
DELETE/print-mail/v1/trackers/{id}
List Tracker Visits
client.printMail.trackers.retrieveVisits(stringid, TrackerRetrieveVisitsParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<TrackerRetrieveVisitsResponse { id, createdAt, device, 6 more } >
GET/print-mail/v1/trackers/{id}/visits
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:
One of the following:

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
client.printMail.webhooks.create(WebhookCreateParams { enabledEvents, url, description, 3 more } body, RequestOptionsoptions?): Webhook { id, createdAt, enabled, 9 more }
POST/print-mail/v1/webhooks
List Webhooks
client.printMail.webhooks.list(WebhookListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<Webhook { id, createdAt, enabled, 9 more } >
GET/print-mail/v1/webhooks
Update Webhook
client.printMail.webhooks.update(stringid, WebhookUpdateParams { description, enabled, enabledEvents, 4 more } body, RequestOptionsoptions?): Webhook { id, createdAt, enabled, 9 more }
POST/print-mail/v1/webhooks/{id}
Get Webhook
client.printMail.webhooks.retrieve(stringid, RequestOptionsoptions?): Webhook { id, createdAt, enabled, 9 more }
GET/print-mail/v1/webhooks/{id}
Delete Webhook
client.printMail.webhooks.delete(stringid, RequestOptionsoptions?): WebhookDeleteResponse { id, deleted, object }
DELETE/print-mail/v1/webhooks/{id}
List Webhook Invocations
client.printMail.webhooks.listInvocations(stringid, WebhookListInvocationsParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<WebhookInvocation { id, createdAt, event, 6 more } >
GET/print-mail/v1/webhooks/{id}/invocations
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:

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
client.printMail.events.list(EventListParams { limit, skip, type } query?, RequestOptionsoptions?): SkipLimit<Event { id, createdAt, live, 4 more } >
GET/print-mail/v1/events
ModelsExpand Collapse
One of the following:

Create and manage letter orders.

Create Letter Create Letter
client.printMail.letters.create(LetterCreateParamsparams, RequestOptionsoptions?): LetterCreateResponse
POST/print-mail/v1/letters
List Letters
client.printMail.letters.list(LetterListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<Letter { id, addressPlacement, color, 30 more } >
GET/print-mail/v1/letters
Get Letter
client.printMail.letters.retrieve(stringid, RequestOptionsoptions?): Letter { id, addressPlacement, color, 30 more }
GET/print-mail/v1/letters/{id}
Cancel Letter
client.printMail.letters.delete(stringid, RequestOptionsoptions?): Letter { id, addressPlacement, color, 30 more }
DELETE/print-mail/v1/letters/{id}
Get Letter Preview
client.printMail.letters.retrieveURL(stringid, RequestOptionsoptions?): LetterRetrieveURLResponse { id, object, url }
GET/print-mail/v1/letters/{id}/url
Cancel Letter With Note
client.printMail.letters.cancel(stringid, LetterCancelParams { note } body, RequestOptionsoptions?): Letter { id, addressPlacement, color, 30 more }
POST/print-mail/v1/letters/{id}/cancellation
Progress Status
client.printMail.letters.progress(stringid, RequestOptionsoptions?): Letter { id, addressPlacement, color, 30 more }
POST/print-mail/v1/letters/{id}/progressions
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:

Create and manage postcard mailings.

Create Postcard Create Postcard
client.printMail.postcards.create(PostcardCreateParamsparams, RequestOptionsoptions?): PostcardCreateResponse
POST/print-mail/v1/postcards
List Postcards
client.printMail.postcards.list(PostcardListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<Postcard { id, createdAt, live, 18 more } >
GET/print-mail/v1/postcards
Get Postcard
client.printMail.postcards.retrieve(stringid, RequestOptionsoptions?): Postcard { id, createdAt, live, 18 more }
GET/print-mail/v1/postcards/{id}
Cancel Postcard
client.printMail.postcards.delete(stringid, RequestOptionsoptions?): Postcard { id, createdAt, live, 18 more }
DELETE/print-mail/v1/postcards/{id}
Get Postcard Preview
client.printMail.postcards.retrieveURL(stringid, RequestOptionsoptions?): PostcardRetrieveURLResponse { id, object, url }
GET/print-mail/v1/postcards/{id}/url
Cancel Postcard With Note
client.printMail.postcards.cancel(stringid, PostcardCancelParams { note } body, RequestOptionsoptions?): Postcard { id, createdAt, live, 18 more }
POST/print-mail/v1/postcards/{id}/cancellation
Progress Status
client.printMail.postcards.progress(stringid, RequestOptionsoptions?): Postcard { id, createdAt, live, 18 more }
POST/print-mail/v1/postcards/{id}/progressions
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:

Manage bank accounts that will be used for mailing cheques.

Create Bank Account
client.printMail.bankAccounts.create(BankAccountCreateParamsbody, RequestOptionsoptions?): BankAccount { id, accountNumber, bankCountryCode, 15 more }
POST/print-mail/v1/bank_accounts
List Bank Accounts
client.printMail.bankAccounts.list(BankAccountListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<BankAccount { id, accountNumber, bankCountryCode, 15 more } >
GET/print-mail/v1/bank_accounts
Get Bank Account
client.printMail.bankAccounts.retrieve(stringid, RequestOptionsoptions?): BankAccount { id, accountNumber, bankCountryCode, 15 more }
GET/print-mail/v1/bank_accounts/{id}
Delete Bank Account
client.printMail.bankAccounts.delete(stringid, RequestOptionsoptions?): BankAccountDeleteResponse { id, deleted, object }
DELETE/print-mail/v1/bank_accounts/{id}
ModelsExpand Collapse
One of the following:
One of the following:

Create and manage cheque orders.

Create Cheque
client.printMail.cheques.create(ChequeCreateParams { amount, bankAccount, from, 21 more } params, RequestOptionsoptions?): Cheque { id, amount, bankAccount, 31 more }
POST/print-mail/v1/cheques
List Cheques
client.printMail.cheques.list(ChequeListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<Cheque { id, amount, bankAccount, 31 more } >
GET/print-mail/v1/cheques
Get Cheque
client.printMail.cheques.retrieve(stringid, RequestOptionsoptions?): Cheque { id, amount, bankAccount, 31 more }
GET/print-mail/v1/cheques/{id}
Cancel Cheque
client.printMail.cheques.delete(stringid, RequestOptionsoptions?): Cheque { id, amount, bankAccount, 31 more }
DELETE/print-mail/v1/cheques/{id}
Get Cheque Preview
client.printMail.cheques.retrieveURL(stringid, RequestOptionsoptions?): ChequeRetrieveURLResponse { id, object, url }
GET/print-mail/v1/cheques/{id}/url
Retrieve Cheque Deposit-Ready PDF (Digital Only)
client.printMail.cheques.retrieveWithDepositReadyPdf(stringid, RequestOptionsoptions?): Cheque { id, amount, bankAccount, 31 more }
GET/print-mail/v1/cheques/{id}/with_deposit_ready_pdf
Cancel Cheque With Note
client.printMail.cheques.cancel(stringid, ChequeCancelParams { note } body, RequestOptionsoptions?): Cheque { id, amount, bankAccount, 31 more }
POST/print-mail/v1/cheques/{id}/cancellation
Progress Status
client.printMail.cheques.progress(stringid, RequestOptionsoptions?): Cheque { id, amount, bankAccount, 31 more }
POST/print-mail/v1/cheques/{id}/progressions
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:

Create and manage self mailers.

Create Self Mailer Create Self Mailer
client.printMail.selfMailers.create(SelfMailerCreateParamsparams, RequestOptionsoptions?): SelfMailerCreateResponse
POST/print-mail/v1/self_mailers
List Self Mailers
client.printMail.selfMailers.list(SelfMailerListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<SelfMailer { id, createdAt, from, 17 more } >
GET/print-mail/v1/self_mailers
Get Self Mailer
client.printMail.selfMailers.retrieve(stringid, RequestOptionsoptions?): SelfMailer { id, createdAt, from, 17 more }
GET/print-mail/v1/self_mailers/{id}
Cancel Self Mailer
client.printMail.selfMailers.delete(stringid, RequestOptionsoptions?): SelfMailer { id, createdAt, from, 17 more }
DELETE/print-mail/v1/self_mailers/{id}
Get Self Mailer Preview
client.printMail.selfMailers.retrieveURL(stringid, RequestOptionsoptions?): SelfMailerRetrieveURLResponse { id, object, url }
GET/print-mail/v1/self_mailers/{id}/url
Progress Status
client.printMail.selfMailers.progress(stringid, RequestOptionsoptions?): SelfMailer { id, createdAt, from, 17 more }
POST/print-mail/v1/self_mailers/{id}/progressions
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:

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
client.printMail.returnEnvelopes.create(ReturnEnvelopeCreateParams { to, description, metadata, idempotencyKey } params, RequestOptionsoptions?): ReturnEnvelope { id, available, createdAt, 6 more }
POST/print-mail/v1/return_envelopes
List Return Envelopes
client.printMail.returnEnvelopes.list(ReturnEnvelopeListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<ReturnEnvelope { id, available, createdAt, 6 more } >
GET/print-mail/v1/return_envelopes
Get Return Envelope
client.printMail.returnEnvelopes.retrieve(stringid, RequestOptionsoptions?): ReturnEnvelope { id, available, createdAt, 6 more }
GET/print-mail/v1/return_envelopes/{id}
ModelsExpand Collapse
One of the following:

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 Order
client.printMail.returnEnvelopes.orders.create(stringid, OrderCreateParams { quantityOrdered, description, metadata } body, RequestOptionsoptions?): ReturnEnvelopeOrder { id, createdAt, live, 8 more }
POST/print-mail/v1/return_envelopes/{id}/orders
List Return Envelope Orders
client.printMail.returnEnvelopes.orders.list(stringid, OrderListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<ReturnEnvelopeOrder { id, createdAt, live, 8 more } >
GET/print-mail/v1/return_envelopes/{id}/orders
Get Return Envelope Order
client.printMail.returnEnvelopes.orders.retrieve(stringorderID, OrderRetrieveParams { id, expand } params, RequestOptionsoptions?): ReturnEnvelopeOrder { id, createdAt, live, 8 more }
GET/print-mail/v1/return_envelopes/{id}/orders/{orderID}
Fill Test Return Envelope Order
client.printMail.returnEnvelopes.orders.fill(stringorderID, OrderFillParams { id } params, RequestOptionsoptions?): ReturnEnvelopeOrder { id, createdAt, live, 8 more }
POST/print-mail/v1/return_envelopes/{id}/orders/{orderID}/fills
Cancel Return Envelope Order
client.printMail.returnEnvelopes.orders.cancel(stringorderID, OrderCancelParams { id, expand } params, RequestOptionsoptions?): ReturnEnvelopeOrder { id, createdAt, live, 8 more }
DELETE/print-mail/v1/return_envelopes/{id}/orders/{orderID}
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:

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

Create Campaign
client.printMail.campaigns.create(CampaignCreateParams { mailingList, cheque, defaultSenderContact, 8 more } params, RequestOptionsoptions?): Campaign { id, createdAt, createdCount, 16 more }
POST/print-mail/v1/campaigns
List Campaigns
client.printMail.campaigns.list(CampaignListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<Campaign { id, createdAt, createdCount, 16 more } >
GET/print-mail/v1/campaigns
Get Campaign
client.printMail.campaigns.retrieve(stringid, RequestOptionsoptions?): Campaign { id, createdAt, createdCount, 16 more }
GET/print-mail/v1/campaigns/{id}
Update Campaign
client.printMail.campaigns.update(stringid, CampaignUpdateParams { cheque, defaultSenderContact, description, 6 more } body, RequestOptionsoptions?): Campaign { id, createdAt, createdCount, 16 more }
POST/print-mail/v1/campaigns/{id}
Delete Campaign
client.printMail.campaigns.delete(stringid, RequestOptionsoptions?): CampaignDeleteResponse { id, deleted }
DELETE/print-mail/v1/campaigns/{id}
Send Campaign
client.printMail.campaigns.send(stringid, CampaignSendParams { sendDate } body, RequestOptionsoptions?): Campaign { id, createdAt, createdCount, 16 more }
POST/print-mail/v1/campaigns/{id}/send
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:

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

Create Mailing List Import
client.printMail.mailingListImports.create(MailingListImportCreateParams { file, fileType, receiverAddressMapping, 6 more } params, RequestOptionsoptions?): MailingListImportResponse { id, createdAt, errors, 13 more }
POST/print-mail/v1/mailing_list_imports
List Mailing List Imports
client.printMail.mailingListImports.list(MailingListImportListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<MailingListImportResponse { id, createdAt, errors, 13 more } >
GET/print-mail/v1/mailing_list_imports
Update Mailing List Import
client.printMail.mailingListImports.update(stringid, MailingListImportUpdateParams { description, metadata } body, RequestOptionsoptions?): MailingListImportResponse { id, createdAt, errors, 13 more }
POST/print-mail/v1/mailing_list_imports/{id}
Get Mailing List Import
client.printMail.mailingListImports.retrieve(stringid, RequestOptionsoptions?): MailingListImportResponse { id, createdAt, errors, 13 more }
GET/print-mail/v1/mailing_list_imports/{id}
Delete Mailing List Import
client.printMail.mailingListImports.delete(stringid, RequestOptionsoptions?): MailingListImportDeleteResponse { id, deleted }
DELETE/print-mail/v1/mailing_list_imports/{id}
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:

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

Create Mailing List
client.printMail.mailingLists.create(MailingListCreateParams { description, metadata, idempotencyKey } params, RequestOptionsoptions?): MailingList { id, createdAt, live, 5 more }
POST/print-mail/v1/mailing_lists
List Mailing Lists
client.printMail.mailingLists.list(MailingListListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<MailingList { id, createdAt, live, 5 more } >
GET/print-mail/v1/mailing_lists
Get Mailing List
client.printMail.mailingLists.retrieve(stringid, RequestOptionsoptions?): MailingList { id, createdAt, live, 5 more }
GET/print-mail/v1/mailing_lists/{id}
Update Mailing List
client.printMail.mailingLists.update(stringid, MailingListUpdateParams { description, metadata } body, RequestOptionsoptions?): MailingListUpdate { description, metadata }
POST/print-mail/v1/mailing_lists/{id}
Delete Mailing List
client.printMail.mailingLists.delete(stringid, RequestOptionsoptions?): MailingListDeleteResponse { id, deleted }
DELETE/print-mail/v1/mailing_lists/{id}
Submit a Mailing List Job
client.printMail.mailingLists.jobs(stringid, MailingListJobsParams { addContacts, addMailingListImports, removeContacts, removeMailingListImports } body, RequestOptionsoptions?): MailingList { id, createdAt, live, 5 more }
POST/print-mail/v1/mailing_lists/{id}/jobs
ModelsExpand Collapse
One of the following:
One of the following:

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
client.printMail.reports.create(ReportCreateParams { sqlQuery, description, metadata } body, RequestOptionsoptions?): Report { id, createdAt, live, 5 more }
POST/print-mail/v1/reports
Run Ad-hoc Query
client.printMail.reports.sample(ReportSampleParams { sqlQuery, limit, params } body, RequestOptionsoptions?): ReportSample { id, records, report }
POST/print-mail/v1/reports/samples
Update Report
client.printMail.reports.update(stringid, ReportUpdateParams { description, metadata, sqlQuery } body, RequestOptionsoptions?): Report { id, createdAt, live, 5 more }
POST/print-mail/v1/reports/{id}
List Saved Reports
client.printMail.reports.list(ReportListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<Report { id, createdAt, live, 5 more } >
GET/print-mail/v1/reports
Retrieve Saved Report
client.printMail.reports.retrieve(stringid, RequestOptionsoptions?): Report { id, createdAt, live, 5 more }
GET/print-mail/v1/reports/{id}
Delete Saved Report
client.printMail.reports.delete(stringid, RequestOptionsoptions?): DeletedResponse { id, deleted }
DELETE/print-mail/v1/reports/{id}
ModelsExpand Collapse

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]

Sample a Saved Report
client.printMail.reports.samples.create(stringid, SampleCreateParams { limit, params } body, RequestOptionsoptions?): ReportSample { id, records, report }
POST/print-mail/v1/reports/{id}/samples
ModelsExpand Collapse

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 a Report Export
client.printMail.reports.exports.create(stringreportID, ExportCreateParams { description, metadata, params } body, RequestOptionsoptions?): ReportExport { id, createdAt, live, 11 more }
POST/print-mail/v1/reports/{reportID}/exports
Get Report Export
client.printMail.reports.exports.retrieve(stringexportID, ExportRetrieveParams { reportID } params, RequestOptionsoptions?): ReportExport { id, createdAt, live, 11 more }
GET/print-mail/v1/reports/{reportID}/exports/{exportID}
Delete Report Export
client.printMail.reports.exports.delete(stringexportID, ExportDeleteParams { reportID } params, RequestOptionsoptions?): DeletedResponse { id, deleted }
DELETE/print-mail/v1/reports/{reportID}/exports/{exportID}
ModelsExpand Collapse

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.
client.printMail.subOrganizations.create(SubOrganizationCreateParams { countryCode, email, name, 3 more } body, RequestOptionsoptions?): SubOrganizationCreateResponse { subOrganization, user }
POST/print-mail/v1/sub_organizations
List sub-organizations.
client.printMail.subOrganizations.list(SubOrganizationListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<SubOrganization { id, countryCode, createdAt, 6 more } >
GET/print-mail/v1/sub_organizations
Get a sub-organization.
client.printMail.subOrganizations.retrieve(stringid, RequestOptionsoptions?): SubOrganization { id, countryCode, createdAt, 6 more }
GET/print-mail/v1/sub_organizations/{id}
List users for a sub-organization.
client.printMail.subOrganizations.retrieveUsers(stringid, SubOrganizationRetrieveUsersParams { limit, search, skip } query?, RequestOptionsoptions?): SubOrganizationRetrieveUsersResponse { id, email, name, 8 more }
GET/print-mail/v1/sub_organizations/{id}/users
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:

Create and manage box orders.

Create Box
client.printMail.boxes.create(BoxCreateParams { cheques, from, to, 5 more } body, RequestOptionsoptions?): BoxCreateResponse { id, cheques, createdAt, 17 more }
POST/print-mail/v1/boxes
List Boxes
client.printMail.boxes.list(BoxListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<BoxListResponse { id, cheques, createdAt, 17 more } >
GET/print-mail/v1/boxes
Get Box
client.printMail.boxes.retrieve(stringid, RequestOptionsoptions?): BoxRetrieveResponse { id, cheques, createdAt, 17 more }
GET/print-mail/v1/boxes/{id}
Cancel Box
client.printMail.boxes.delete(stringid, RequestOptionsoptions?): BoxDeleteResponse { id, cheques, createdAt, 17 more }
DELETE/print-mail/v1/boxes/{id}
Progress Status
client.printMail.boxes.progressions(stringid, RequestOptionsoptions?): BoxProgressionsResponse { id, cheques, createdAt, 17 more }
POST/print-mail/v1/boxes/{id}/progressions
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:

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
client.printMail.snapPacks.create(SnapPackCreateParamsparams, RequestOptionsoptions?): SnapPackCreateResponse
POST/print-mail/v1/snap_packs
List Snap Packs
client.printMail.snapPacks.list(SnapPackListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<SnapPack { id, createdAt, from, 22 more } >
GET/print-mail/v1/snap_packs
Capabilities
client.printMail.snapPacks.retrieveCapabilities(SnapPackRetrieveCapabilitiesParams { returnCountryCode, destinationCountryCode, mailingList } query, RequestOptionsoptions?): SnapPackRetrieveCapabilitiesResponse { mailingClasses, sizes }
GET/print-mail/v1/snap_packs/capabilities
Get Snap Pack
client.printMail.snapPacks.retrieve(stringid, RequestOptionsoptions?): SnapPack { id, createdAt, from, 22 more }
GET/print-mail/v1/snap_packs/{id}
Cancel
client.printMail.snapPacks.delete(stringid, RequestOptionsoptions?): SnapPack { id, createdAt, from, 22 more }
DELETE/print-mail/v1/snap_packs/{id}
Progress Status
client.printMail.snapPacks.progressions(stringid, RequestOptionsoptions?): SnapPack { id, createdAt, from, 22 more }
POST/print-mail/v1/snap_packs/{id}/progressions
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:

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
client.printMail.targetedListBuilds.create(TargetedListBuildCreateParams { description, limit, metadata, 3 more } params, RequestOptionsoptions?): TargetedListBuildCreateResponse { id, createdAt, live, 15 more }
POST/print-mail/v1/targeted_list_builds
List Targeted List Builds
client.printMail.targetedListBuilds.list(TargetedListBuildListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<TargetedListBuildListResponse { id, createdAt, live, 15 more } >
GET/print-mail/v1/targeted_list_builds
Get Targeted List Build
client.printMail.targetedListBuilds.retrieve(stringid, RequestOptionsoptions?): TargetedListBuildRetrieveResponse { id, createdAt, live, 15 more }
GET/print-mail/v1/targeted_list_builds/{id}
Update Targeted List Build
client.printMail.targetedListBuilds.update(stringid, TargetedListBuildUpdateParams { description, limit, metadata, 2 more } body, RequestOptionsoptions?): TargetedListBuildUpdateResponse { id, createdAt, live, 15 more }
POST/print-mail/v1/targeted_list_builds/{id}
Delete Targeted List Build
client.printMail.targetedListBuilds.delete(stringid, RequestOptionsoptions?): TargetedListBuildDeleteResponse { id, deleted }
DELETE/print-mail/v1/targeted_list_builds/{id}
Confirm Targeted List Build
client.printMail.targetedListBuilds.confirm(stringid, RequestOptionsoptions?): TargetedListBuildConfirmResponse { id, createdAt, live, 15 more }
POST/print-mail/v1/targeted_list_builds/{id}/confirm
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:

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
client.printMail.targetedListBuilds.filters.autocomplete(FilterAutocompleteParams { field, size, text } body, RequestOptionsoptions?): FilterAutocompleteResponse { data, object }
POST/print-mail/v1/targeted_list_builds/filters/autocomplete
ModelsExpand Collapse

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
client.printMail.templateEditorSessions.create(TemplateEditorSessionCreateParams { template, backURL, styles, 2 more } body, RequestOptionsoptions?): TemplateEditorSessionCreateResponse { id, createdAt, live, 7 more }
POST/print-mail/v1/template_editor_sessions
List Sessions
client.printMail.templateEditorSessions.list(TemplateEditorSessionListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<TemplateEditorSessionListResponse { id, createdAt, live, 7 more } >
GET/print-mail/v1/template_editor_sessions
Delete Session
client.printMail.templateEditorSessions.delete(stringid, RequestOptionsoptions?): TemplateEditorSessionDeleteResponse { id, deleted, object }
DELETE/print-mail/v1/template_editor_sessions/{id}
ModelsExpand Collapse
One of the following:
One of the following:

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]

Create Virtual Mailbox
client.printMail.virtualMailboxes.create(VirtualMailboxCreateParams { countryCode, capabilities } body, RequestOptionsoptions?): VirtualMailboxCreateResponse { id, capabilities, countryCode, 7 more }
POST/print-mail/v1/virtual_mailboxes
List Virtual Mailboxes
client.printMail.virtualMailboxes.list(VirtualMailboxListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<VirtualMailboxListResponse { id, capabilities, countryCode, 7 more } >
GET/print-mail/v1/virtual_mailboxes
Retrieve Virtual Mailbox
client.printMail.virtualMailboxes.retrieve(stringid, RequestOptionsoptions?): VirtualMailboxRetrieveResponse { id, capabilities, countryCode, 7 more }
GET/print-mail/v1/virtual_mailboxes/{id}
Retrieve Physical Address
client.printMail.virtualMailboxes.retrieveAddress(stringid, RequestOptionsoptions?): VirtualMailboxRetrieveAddressResponse { addressLine1, countryCode, addressLine2, 3 more }
GET/print-mail/v1/virtual_mailboxes/{id}/address
ModelsExpand Collapse
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:

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]

List Virtual Mailbox Items
client.printMail.virtualMailboxes.items.list(stringid, ItemListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<ItemListResponse { id, createdAt, live, 7 more } >
GET/print-mail/v1/virtual_mailboxes/{id}/items
Create Test Virtual Mailbox Item
client.printMail.virtualMailboxes.items.create(stringid, ItemCreateParams { description, matchedLetter, metadata } body, RequestOptionsoptions?): ItemCreateResponse { id, createdAt, live, 7 more }
POST/print-mail/v1/virtual_mailboxes/{id}/items
Retrieve Virtual Mailbox Item
client.printMail.virtualMailboxes.items.retrieve(stringitemID, ItemRetrieveParams { id } params, RequestOptionsoptions?): ItemRetrieveResponse { id, createdAt, live, 7 more }
GET/print-mail/v1/virtual_mailboxes/{id}/items/{itemID}
ModelsExpand Collapse