API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Print Mail

ModelsExpand Collapse

ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }

addressLine1: string

The first line of the contact's address.

companyName: string

countryCode: string

The ISO 3611-1 country code of the contact's address.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }

addressLine1: string

The first line of the contact's address.

countryCode: string

The ISO 3611-1 country code of the contact's address.

firstName: string

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

Print MailBank Accounts

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}

ModelsExpand Collapse

BankAccount = object { id, accountNumber, bankCountryCode, 15 more }

id: string

A unique ID prefixed with bank_account_

accountNumber: string

The account number of the bank account.

bankCountryCode: BankAccountCountryCode

Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports.

One of the following:

"CA"

"US"

bankName: string

The name of the bank.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "bank_account"

Always bank_account.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

bankPrimaryLine: optional string

The primary address line of the bank.

bankSecondaryLine: optional string

The secondary address line of the bank.

caDesignationNumber: optional string

The designation number of the bank account (for CA).

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

metadata: optional map[unknown]

See the section on Metadata.

routeNumber: optional string

The route number of the bank account (for CA).

routingNumber: optional string

The routing number of the bank account (for US).

signatureImage: optional string

A signed link to the signature image uploaded when this bank account was created. This is omitted if signatureText is present.

formaturi

signatureText: optional string

The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if signatureImage is present.

transitNumber: optional string

The transit number of the bank account (for CA).

BankAccountCountryCode = "CA" or "US"

Countries typically have different bank account formats and standards. These are the countries which PostGrid's bank accounts API supports.

One of the following:

"CA"

"US"

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

ModelsExpand Collapse

Campaign = object { id, createdAt, createdCount, 15 more }

Represents a bulk mail campaign.

id: string

A unique ID prefixed with campaign_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

createdCount: number

The number of orders successfully created for this campaign.

formatint32

live: boolean

true if this is a live mode resource else false.

mailingList: string

The ID of the mailing list associated with this campaign.

status: "drafting" or "changes_required" or "creating_orders" or 4 more

Status of the campaign lifecycle.

One of the following:

"drafting"

"changes_required"

"creating_orders"

"draft"

"ready"

"printing"

"processed_for_delivery"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

chequeProfile: optional string

The ID of the cheque profile used for this campaign, if applicable.

defaultSenderContact: optional string

The ID of the default sender contact to use for orders if not specified per recipient.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

errors: optional array of object { message, type }

A list of processing errors encountered, if any. Present when status is 'changes_required'.

message: string

A human-readable message describing the error.

type: "processing_error" or "internal_error"

Type of error encountered during campaign processing.

One of the following:

"processing_error"

"internal_error"

letterProfile: optional string

The ID of the letter profile used for this campaign, if applicable.

metadata: optional map[unknown]

See the section on Metadata.

orderPreviewURL: optional string

A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.

formaturi

postcardProfile: optional string

The ID of the postcard profile used for this campaign, if applicable.

reportURL: optional string

A temporary URL to download the processing report, available once the campaign is in the ready status.

formaturi

selfMailerProfile: optional string

The ID of the self-mailer profile used for this campaign, if applicable.

sendDate: optional string

The scheduled date and time for the campaign to be sent.

formatdate-time

Print MailCheques

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

ModelsExpand Collapse

Cheque = object { id, amount, bankAccount, 27 more }

id: string

A unique ID prefixed with cheque_

amount: number

The amount of the cheque in cents.

formatint32

bankAccount: string

The bank account (ID) associated with the cheque.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

currencyCode: "USD" or "CAD"

The currency code of the cheque. This can be USD even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified.

One of the following:

"USD"

"CAD"

from: Contact { id, addressLine1, addressStatus, 20 more }

The contact information of the sender.

id: string

A unique ID prefixed with contact_

addressLine1: string

The first line of the contact's address.

addressStatus: "verified" or "corrected" or "failed"

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

countryCode: string

The ISO 3611-1 country code of the contact's address.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors: optional string

A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

live: boolean

true if this is a live mode resource else false.

mailingClass: "first_class" or "standard_class" or "express" or 23 more

The mailing class of this order. This determines the speed and cost of delivery. See OrderMailingClass for more details.

One of the following:

"first_class"

"standard_class"

"express"

"certified"

"certified_return_receipt"

"registered"

"usps_first_class"

"usps_standard_class"

"usps_eddm"

"usps_express_2_day"

"usps_express_3_day"

"usps_first_class_certified"

"usps_first_class_certified_return_receipt"

"usps_first_class_registered"

"usps_express_3_day_signature_confirmation"

"usps_express_3_day_certified"

"usps_express_3_day_certified_return_receipt"

"ca_post_lettermail"

"ca_post_personalized"

"ca_post_neighbourhood_mail"

"ups_express_overnight"

"ups_express_2_day"

"ups_express_3_day"

"royal_mail_first_class"

"royal_mail_second_class"

"au_post_second_class"

object: "cheque"

Always cheque.

sendDate: string

This order will transition from ready to printing on the day after this date. For example, if this is a date on Tuesday, the order will transition to printing on Wednesday at midnight eastern time.

formatdate-time

size: ChequeSize

Enum representing the supported cheque sizes.

One of the following:

"us_letter"

"us_legal"

status: "ready" or "printing" or "processed_for_delivery" or 2 more

See OrderStatus for more details on the status of this order.

One of the following:

"ready"

"printing"

"processed_for_delivery"

"completed"

"cancelled"

to: Contact { id, addressLine1, addressStatus, 20 more }

The recipient of this order. This will be provided even if you delete the underlying contact.

id: string

A unique ID prefixed with contact_

addressLine1: string

The first line of the contact's address.

addressStatus: "verified" or "corrected" or "failed"

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

countryCode: string

The ISO 3611-1 country code of the contact's address.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors: optional string

A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

cancellation: optional object { reason, cancelledByUser, note }

The cancellation details of this order. Populated if the order has been cancelled.

reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"

The reason for the cancellation.

One of the following:

"user_initiated"

"invalid_content"

"invalid_order_mailing_class"

cancelledByUser: optional string

The user ID who cancelled the order.

note: optional string

An optional note provided by the user who cancelled the order.

depositReadyPDFURL: optional string

A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available.

formaturi

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

digitalOnly: optional DigitalOnly { watermark }

The digitalOnly object contains data for digital-only cheques. A watermark must be provided.

watermark: string

Text to be displayed as a watermark on the digital cheque.

envelope: optional "standard" or string

The envelope of the cheque. If a custom envelope ID is not specified, defaults to standard.

One of the following:

"standard"

The envelope of the cheque. If a custom envelope ID is not specified, defaults to standard.

string

imbDate: optional string

The last date that the IMB status was updated. See imbStatus for more details.

formatdate-time

imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"

The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

One of the following:

"entered_mail_stream"

"out_for_delivery"

"returned_to_sender"

imbZIPCode: optional string

The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an imbStatus is present.

logoURL: optional string

An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file).

formaturi

memo: optional string

The memo of the cheque.

mergeVariables: optional map[unknown]

These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template exactly as they are case-sensitive. Note that these do not apply to PDFs uploaded with the order.

message: optional string

The message of the cheque.

metadata: optional map[unknown]

See the section on Metadata.

number: optional number

The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number.

formatint32

trackingNumber: optional string

The tracking number of this order. Populated after an express/certified order has been processed for delivery.

url: optional string

PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all GET endpoints which produce this order.

This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the GET endpoint again.

formaturi

ChequeSize = "us_letter" or "us_legal"

Enum representing the supported cheque sizes.

One of the following:

"us_letter"

"us_legal"

DigitalOnly = object { watermark }

watermark: string

Text to be displayed as a watermark on the digital cheque.

Print MailContacts

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}

ModelsExpand Collapse

Contact = object { id, addressLine1, addressStatus, 20 more }

id: string

A unique ID prefixed with contact_

addressLine1: string

The first line of the contact's address.

addressStatus: "verified" or "corrected" or "failed"

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

countryCode: string

The ISO 3611-1 country code of the contact's address.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors: optional string

A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

ContactCreate = ContactCreateWithFirstName { addressLine1, countryCode, firstName, 13 more } or ContactCreateWithCompanyName { addressLine1, companyName, countryCode, 13 more }

One of the following:

ContactCreateWithFirstName = object { addressLine1, countryCode, firstName, 13 more }

addressLine1: string

The first line of the contact's address.

countryCode: string

The ISO 3611-1 country code of the contact's address.

firstName: string

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

ContactCreateWithCompanyName = object { addressLine1, companyName, countryCode, 13 more }

addressLine1: string

The first line of the contact's address.

companyName: string

countryCode: string

The ISO 3611-1 country code of the contact's address.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

Print MailLetters

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

ModelsExpand Collapse

AddressPlacement = "top_first_page" or "insert_blank_page"

Enum representing the placement of the address on the letter.

One of the following:

"top_first_page"

"insert_blank_page"

AttachedPdf = object { file, placement }

Model representing an attached PDF.

file: string

The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

formaturi

placement: "before_template" or "after_template"

Enum representing the placement of the attached PDF.

One of the following:

"before_template"

"after_template"

Letter = object { id, addressPlacement, color, 29 more }

id: string

A unique ID prefixed with letter_

addressPlacement: AddressPlacement

Enum representing the placement of the address on the letter.

One of the following:

"top_first_page"

"insert_blank_page"

color: boolean

Indicates if the letter is in color.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

doubleSided: boolean

Indicates if the letter is double-sided.

envelope: string

The envelope (ID) for the letter or the default standard envelope.

from: Contact { id, addressLine1, addressStatus, 20 more }

The contact information of the sender.

id: string

A unique ID prefixed with contact_

addressLine1: string

The first line of the contact's address.

addressStatus: "verified" or "corrected" or "failed"

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

countryCode: string

The ISO 3611-1 country code of the contact's address.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors: optional string

A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

live: boolean

true if this is a live mode resource else false.

mailingClass: "first_class" or "standard_class" or "express" or 23 more

The mailing class of this order. This determines the speed and cost of delivery. See OrderMailingClass for more details.

One of the following:

"first_class"

"standard_class"

"express"

"certified"

"certified_return_receipt"

"registered"

"usps_first_class"

"usps_standard_class"

"usps_eddm"

"usps_express_2_day"

"usps_express_3_day"

"usps_first_class_certified"

"usps_first_class_certified_return_receipt"

"usps_first_class_registered"

"usps_express_3_day_signature_confirmation"

"usps_express_3_day_certified"

"usps_express_3_day_certified_return_receipt"

"ca_post_lettermail"

"ca_post_personalized"

"ca_post_neighbourhood_mail"

"ups_express_overnight"

"ups_express_2_day"

"ups_express_3_day"

"royal_mail_first_class"

"royal_mail_second_class"

"au_post_second_class"

object: "letter"

Always letter.

sendDate: string

This order will transition from ready to printing on the day after this date. For example, if this is a date on Tuesday, the order will transition to printing on Wednesday at midnight eastern time.

formatdate-time

size: LetterSize

Enum representing the supported letter sizes.

One of the following:

"us_letter"

"a4"

status: "ready" or "printing" or "processed_for_delivery" or 2 more

See OrderStatus for more details on the status of this order.

One of the following:

"ready"

"printing"

"processed_for_delivery"

"completed"

"cancelled"

to: Contact { id, addressLine1, addressStatus, 20 more }

The recipient of this order. This will be provided even if you delete the underlying contact.

id: string

A unique ID prefixed with contact_

addressLine1: string

The first line of the contact's address.

addressStatus: "verified" or "corrected" or "failed"

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

countryCode: string

The ISO 3611-1 country code of the contact's address.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors: optional string

A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

attachedPDF: optional AttachedPdf { file, placement }

Model representing an attached PDF.

file: string

The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

formaturi

placement: "before_template" or "after_template"

Enum representing the placement of the attached PDF.

One of the following:

"before_template"

"after_template"

cancellation: optional object { reason, cancelledByUser, note }

The cancellation details of this order. Populated if the order has been cancelled.

reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"

The reason for the cancellation.

One of the following:

"user_initiated"

"invalid_content"

"invalid_order_mailing_class"

cancelledByUser: optional string

The user ID who cancelled the order.

note: optional string

An optional note provided by the user who cancelled the order.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

html: optional string

The HTML content for the letter. You can supply either this or template but not both.

imbDate: optional string

The last date that the IMB status was updated. See imbStatus for more details.

formatdate-time

imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"

The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

One of the following:

"entered_mail_stream"

"out_for_delivery"

"returned_to_sender"

imbZIPCode: optional string

The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an imbStatus is present.

mergeVariables: optional map[unknown]

These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template exactly as they are case-sensitive. Note that these do not apply to PDFs uploaded with the order.

metadata: optional map[unknown]

See the section on Metadata.

pdfWorkflowRun: optional string

The ID of the PDF workflow run that created the letter, if any.

perforatedPage: optional 1

If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.

plasticCard: optional PlasticCard { size, doubleSided, singleSided }

Model representing a plastic card.

size: "standard"

Enum representing the size of the plastic card.

doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }

Model representing a double-sided plastic card.

backHTML: optional string

The HTML content for the back side of the double-sided plastic card.

backTemplate: optional string

The template ID for the back side of the double-sided plastic card.

frontHTML: optional string

The HTML content for the front side of the double-sided plastic card.

frontTemplate: optional string

The template ID for the front side of the double-sided plastic card.

pdf: optional string

A URL pointing to a PDF file for the double-sided plastic card or the file itself.

formaturi

singleSided: optional object { html, pdf, template }

Model representing a single-sided plastic card.

html: optional string

The HTML content for the single-sided plastic card. Can specify one of this, template, or pdf.

pdf: optional string

A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.

formaturi

template: optional string

The template ID for the single-sided plastic card.

returnEnvelope: optional string

The return envelope (ID) sent out with the letter, if any.

template: optional string

The template ID used for the letter. You can supply either this or html but not both.

trackingNumber: optional string

The tracking number of this order. Populated after an express/certified order has been processed for delivery.

uploadedPDF: optional string

If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF.

formaturi

url: optional string

PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all GET endpoints which produce this order.

This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the GET endpoint again.

formaturi

LetterSize = "us_letter" or "a4"

Enum representing the supported letter sizes.

One of the following:

"us_letter"

"a4"

PlasticCard = object { size, doubleSided, singleSided }

Model representing a plastic card.

size: "standard"

Enum representing the size of the plastic card.

doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }

Model representing a double-sided plastic card.

backHTML: optional string

The HTML content for the back side of the double-sided plastic card.

backTemplate: optional string

The template ID for the back side of the double-sided plastic card.

frontHTML: optional string

The HTML content for the front side of the double-sided plastic card.

frontTemplate: optional string

The template ID for the front side of the double-sided plastic card.

pdf: optional string

A URL pointing to a PDF file for the double-sided plastic card or the file itself.

formaturi

singleSided: optional object { html, pdf, template }

Model representing a single-sided plastic card.

html: optional string

The HTML content for the single-sided plastic card. Can specify one of this, template, or pdf.

pdf: optional string

A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.

formaturi

template: optional string

The template ID for the single-sided plastic card.

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}

ModelsExpand Collapse

FileType = "csv"

Type of file supported for mailing list imports.

MailingListImportResponse = object { id, createdAt, errors, 13 more }

Read-only view of a MailingListImport

id: string

A unique ID prefixed with mailing_list_import_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

errors: array of object { message, type }

A list of processing errors encountered, if any. Present when status is 'changes_required'.

message: string

A human-readable message describing the error.

type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "internal_service_error"

Type of error encountered during import processing.

One of the following:

"no_valid_contacts_error"

"multiple_countries_error"

"invalid_contact_count_error"

"internal_service_error"

file: object { fileType, receiverAddressMapping, url, 3 more }

The file object your controller returns: all the mappings plus a signed URL.

fileType: FileType

Type of file supported for mailing list imports.

receiverAddressMapping: map[string]

Mapping of columns for receiver addresses. Contact fields to file columns. Possible Contact fields:

• description
• firstName
• lastName
• email
• phoneNumber
• companyName
• addressLine1
• addressLine2
• jobTitle
• city
• postalOrZip
• provinceOrState
• countryCode

url: string

The signed URL your controller generates.

formaturi

receiverMergeVariableMapping: optional map[string]

Optional mapping of columns for receiver merge variables.

senderAddressMapping: optional map[string]

Optional mapping of columns for sender addresses.

senderMergeVariableMapping: optional map[string]

Optional mapping of columns for sender merge variables.

invalidRowCount: number

Number of invalid rows found in the file.

formatint32

live: boolean

true if this is a live mode resource else false.

notes: array of object { message, type }

Additional notes about the import process.

message: string

A human-readable message describing the note.

type: "truncated_test_file" or "skipped_invalid_contacts"

Type of note attached to the import process.

One of the following:

"truncated_test_file"

"skipped_invalid_contacts"

organization: string

The organization that owns this import.

receiverStatusCount: VerificationStatusCount { correctedCount, failedCount, verifiedCount }

Count of contact verification statuses.

correctedCount: number

Number of contacts that were corrected during verification.

formatint32

failedCount: number

Number of contacts that failed verification.

formatint32

verifiedCount: number

Number of contacts that were verified without changes.

formatint32

status: "validating" or "completed" or "changes_required"

Status of the mailing list import process.

One of the following:

"validating"

"completed"

"changes_required"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

validRowCount: number

Number of valid rows processed from the file.

formatint32

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

metadata: optional map[unknown]

See the section on Metadata.

reportURL: optional string

A temporary URL to download the processing report, available once the import is completed.

formaturi

senderStatusCount: optional VerificationStatusCount { correctedCount, failedCount, verifiedCount }

Count of contact verification statuses.

correctedCount: number

Number of contacts that were corrected during verification.

formatint32

failedCount: number

Number of contacts that failed verification.

formatint32

verifiedCount: number

Number of contacts that were verified without changes.

formatint32

VerificationStatusCount = object { correctedCount, failedCount, verifiedCount }

Count of contact verification statuses.

correctedCount: number

Number of contacts that were corrected during verification.

formatint32

failedCount: number

Number of contacts that failed verification.

formatint32

verifiedCount: number

Number of contacts that were verified without changes.

formatint32

Print MailMailing Lists

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

ModelsExpand Collapse

MailingList = object { id, createdAt, live, 5 more }

Represents a mailing list.

id: string

A unique ID prefixed with mailing_list_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"

Status of the mailing list processing.

One of the following:

"creating_contacts"

"removing_contacts"

"counting_recipient_country_codes"

"completed"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

errors: optional array of object { message, type }

A list of processing errors encountered, if any.

message: string

A human-readable message describing the error.

type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "internal_service_error"

Type of error encountered during mailing list processing.

One of the following:

"mailing_list_imports_not_found_error"

"download_file_error"

"operational_error"

"internal_service_error"

metadata: optional map[unknown]

See the section on Metadata.

MailingListUpdate = object { description, metadata }

Parameters for updating an existing mailing list.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

metadata: optional map[unknown]

See the section on Metadata.

Print MailOrder Profiles

Print MailOrder ProfilesCheques

Order Profiles are reusable blueprints for creating print and mail orders (Letters, Postcards, Cheques, Self-Mailers). They define common properties like size, content (via templates or uploaded PDFs), mailing class, and metadata. Using profiles simplifies order creation, especially for recurring mailings or campaigns, by pre-filling many parameters.

Profiles are environment-specific (live vs. test).

Create Cheque Profile

POST/print-mail/v1/order_profiles/cheques

List Cheque Profiles

GET/print-mail/v1/order_profiles/cheques

Retrieve Cheque Profile

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

Update Cheque Profile

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

Delete Cheque Profile

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

ModelsExpand Collapse

ChequeProfile = object { id, bankAccount, createdAt, 14 more }

id: string

Unique identifier for the order profile.

bankAccount: string

ID of the bank account to use for the cheque. Required for creation.

createdAt: string

Timestamp when the profile was created.

formatdate-time

currencyCode: CurrencyCode

Enum representing the supported currency codes.

One of the following:

"CAD"

"USD"

live: boolean

Indicates if the profile is associated with the live or test environment.

object: "cheque_profile"

Always cheque_profile.

size: ChequeSize

Enum representing the supported cheque sizes.

One of the following:

"us_letter"

"us_legal"

updatedAt: string

Timestamp when the profile was last updated.

formatdate-time

description: optional string

An optional description for the profile. Set to null to remove during update.

letterTemplate: optional string

ID of a template for an optional attached letter. Cannot be used with letterHTML or letterPDF.

letterUploadedPDF: optional string

A temporary, signed URL to view the attached letter PDF, if any. Output only.

formaturi

logo: optional string

A publicly accessible URL for the logo to print on the cheque. Set to null to remove during update.

formaturi

mailingClass: optional "first_class" or "standard_class" or "express" or 23 more

Mailing class. Generally must be first class (or equivalent for destination country) for cheques.

One of the following:

"first_class"

"standard_class"

"express"

"certified"

"certified_return_receipt"

"registered"

"usps_first_class"

"usps_standard_class"

"usps_eddm"

"usps_express_2_day"

"usps_express_3_day"

"usps_first_class_certified"

"usps_first_class_certified_return_receipt"

"usps_first_class_registered"

"usps_express_3_day_signature_confirmation"

"usps_express_3_day_certified"

"usps_express_3_day_certified_return_receipt"

"ca_post_lettermail"

"ca_post_personalized"

"ca_post_neighbourhood_mail"

"ups_express_overnight"

"ups_express_2_day"

"ups_express_3_day"

"royal_mail_first_class"

"royal_mail_second_class"

"au_post_second_class"

memo: optional string

Memo line text for the cheque. Set to null to remove during update.

mergeVariables: optional map[unknown]

Default merge variables for orders created using this profile.

message: optional string

Message included on the cheque stub. Set to null to remove during update.

metadata: optional map[string]

Optional key-value metadata.

CurrencyCode = "CAD" or "USD"

Enum representing the supported currency codes.

One of the following:

"CAD"

"USD"

Print MailOrder ProfilesLetters

Order Profiles are reusable blueprints for creating print and mail orders (Letters, Postcards, Cheques, Self-Mailers). They define common properties like size, content (via templates or uploaded PDFs), mailing class, and metadata. Using profiles simplifies order creation, especially for recurring mailings or campaigns, by pre-filling many parameters.

Profiles are environment-specific (live vs. test).

Create Letter Profile

POST/print-mail/v1/order_profiles/letters

List Letter Profiles

GET/print-mail/v1/order_profiles/letters

Retrieve Letter Profile

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

Update Letter Profile

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

Delete Letter Profile

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

ModelsExpand Collapse

LetterProfile = object { id, createdAt, live, 15 more }

id: string

Unique identifier for the order profile.

createdAt: string

Timestamp when the profile was created.

formatdate-time

live: boolean

Indicates if the profile is associated with the live or test environment.

object: "letter_profile"

Always letter_profile.

size: LetterSize

Enum representing the supported letter sizes.

One of the following:

"us_letter"

"a4"

updatedAt: string

Timestamp when the profile was last updated.

formatdate-time

addressPlacement: optional AddressPlacement

Enum representing the placement of the address on the letter.

One of the following:

"top_first_page"

"insert_blank_page"

attachedPDF: optional AttachedPdf { file, placement }

Model representing an attached PDF.

file: string

The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

formaturi

placement: "before_template" or "after_template"

Enum representing the placement of the attached PDF.

One of the following:

"before_template"

"after_template"

color: optional boolean

Specifies whether to print in color (true) or black and white (false).

description: optional string

An optional description for the profile. Set to null to remove during update.

doubleSided: optional boolean

Specifies whether to print on both sides of the paper.

envelope: optional string

ID of a custom envelope to use.

mailingClass: optional "first_class" or "standard_class" or "express" or 23 more

Mailing class.

One of the following:

"first_class"

"standard_class"

"express"

"certified"

"certified_return_receipt"

"registered"

"usps_first_class"

"usps_standard_class"

"usps_eddm"

"usps_express_2_day"

"usps_express_3_day"

"usps_first_class_certified"

"usps_first_class_certified_return_receipt"

"usps_first_class_registered"

"usps_express_3_day_signature_confirmation"

"usps_express_3_day_certified"

"usps_express_3_day_certified_return_receipt"

"ca_post_lettermail"

"ca_post_personalized"

"ca_post_neighbourhood_mail"

"ups_express_overnight"

"ups_express_2_day"

"ups_express_3_day"

"royal_mail_first_class"

"royal_mail_second_class"

"au_post_second_class"

mergeVariables: optional map[unknown]

Default merge variables for orders created using this profile.

metadata: optional map[string]

Optional key-value metadata.

perforatedPage: optional 1

Specifies which page number should be perforated (if any).

template: optional string

ID of a template to use for the letter content. Cannot be used with pdf.

uploadedPDF: optional string

A temporary, signed URL to view the uploaded PDF, if any.

formaturi

Print MailOrder ProfilesPostcards

Order Profiles are reusable blueprints for creating print and mail orders (Letters, Postcards, Cheques, Self-Mailers). They define common properties like size, content (via templates or uploaded PDFs), mailing class, and metadata. Using profiles simplifies order creation, especially for recurring mailings or campaigns, by pre-filling many parameters.

Profiles are environment-specific (live vs. test).

Create Postcard Profile

POST/print-mail/v1/order_profiles/postcards

List Postcard Profiles

GET/print-mail/v1/order_profiles/postcards

Retrieve Postcard Profile

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

Update Postcard Profile

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

Delete Postcard Profile

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

ModelsExpand Collapse

PostcardProfile = object { id, createdAt, live, 10 more }

id: string

Unique identifier for the order profile.

createdAt: string

Timestamp when the profile was created.

formatdate-time

live: boolean

Indicates if the profile is associated with the live or test environment.

object: "postcard_profile"

Always postcard_profile.

size: PostcardSize

Enum representing the supported postcard sizes.

One of the following:

"6x4"

"9x6"

"11x6"

updatedAt: string

Timestamp when the profile was last updated.

formatdate-time

backTemplate: optional string

ID of the template for the back side. Required unless pdf is provided.

description: optional string

An optional description for the profile. Set to null to remove during update.

frontTemplate: optional string

ID of the template for the front side. Required unless pdf is provided.

mailingClass: optional "first_class" or "standard_class" or "express" or 23 more

Mailing class (cannot include extra services like certified or registered for postcards, though).

One of the following:

"first_class"

"standard_class"

"express"

"certified"

"certified_return_receipt"

"registered"

"usps_first_class"

"usps_standard_class"

"usps_eddm"

"usps_express_2_day"

"usps_express_3_day"

"usps_first_class_certified"

"usps_first_class_certified_return_receipt"

"usps_first_class_registered"

"usps_express_3_day_signature_confirmation"

"usps_express_3_day_certified"

"usps_express_3_day_certified_return_receipt"

"ca_post_lettermail"

"ca_post_personalized"

"ca_post_neighbourhood_mail"

"ups_express_overnight"

"ups_express_2_day"

"ups_express_3_day"

"royal_mail_first_class"

"royal_mail_second_class"

"au_post_second_class"

mergeVariables: optional map[unknown]

Default merge variables for orders created using this profile.

metadata: optional map[string]

Optional key-value metadata.

uploadedPDF: optional string

A temporary, signed URL to view the uploaded PDF content, if any.

formaturi

PostcardSize = "6x4" or "9x6" or "11x6"

Enum representing the supported postcard sizes.

One of the following:

"6x4"

"9x6"

"11x6"

Print MailOrder ProfilesSelf Mailers

Order Profiles are reusable blueprints for creating print and mail orders (Letters, Postcards, Cheques, Self-Mailers). They define common properties like size, content (via templates or uploaded PDFs), mailing class, and metadata. Using profiles simplifies order creation, especially for recurring mailings or campaigns, by pre-filling many parameters.

Profiles are environment-specific (live vs. test).

Create Self-Mailer Profile

POST/print-mail/v1/order_profiles/self_mailers

List Self-Mailer Profiles

GET/print-mail/v1/order_profiles/self_mailers

Retrieve Self-Mailer Profile

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

Update Self-Mailer Profile

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

Delete Self-Mailer Profile

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

ModelsExpand Collapse

SelfMailerProfile = object { id, createdAt, live, 10 more }

Represents a Self-Mailer Profile resource.

id: string

Unique identifier for the order profile.

createdAt: string

Timestamp when the profile was created.

formatdate-time

live: boolean

Indicates if the profile is associated with the live or test environment.

object: "self_mailer_profile"

Always self_mailer_profile.

size: SelfMailerSize

Enum representing the supported self-mailer sizes.

One of the following:

"8.5x11_bifold"

"8.5x11_trifold"

"9.5x16_trifold"

updatedAt: string

Timestamp when the profile was last updated.

formatdate-time

description: optional string

An optional description for the profile. Set to null to remove during update.

insideTemplate: optional string

ID of the template for the inside. Required unless pdf is provided.

mailingClass: optional "first_class" or "standard_class" or "express" or 23 more

Mailing class (cannot include extra services for self-mailers).

One of the following:

"first_class"

"standard_class"

"express"

"certified"

"certified_return_receipt"

"registered"

"usps_first_class"

"usps_standard_class"

"usps_eddm"

"usps_express_2_day"

"usps_express_3_day"

"usps_first_class_certified"

"usps_first_class_certified_return_receipt"

"usps_first_class_registered"

"usps_express_3_day_signature_confirmation"

"usps_express_3_day_certified"

"usps_express_3_day_certified_return_receipt"

"ca_post_lettermail"

"ca_post_personalized"

"ca_post_neighbourhood_mail"

"ups_express_overnight"

"ups_express_2_day"

"ups_express_3_day"

"royal_mail_first_class"

"royal_mail_second_class"

"au_post_second_class"

mergeVariables: optional map[unknown]

Default merge variables for orders created using this profile.

metadata: optional map[string]

Optional key-value metadata.

outsideTemplate: optional string

ID of the template for the outside. Required unless pdf is provided.

uploadedPDF: optional string

A temporary, signed URL to view the uploaded PDF, if any.

formaturi

SelfMailerSize = "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"

Enum representing the supported self-mailer sizes.

One of the following:

"8.5x11_bifold"

"8.5x11_trifold"

"9.5x16_trifold"

Print MailPostcards

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

ModelsExpand Collapse

Postcard = object { id, createdAt, live, 17 more }

id: string

A unique ID prefixed with postcard_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

mailingClass: "first_class" or "standard_class" or "express" or 23 more

The mailing class of this order. This determines the speed and cost of delivery. See OrderMailingClass for more details.

One of the following:

"first_class"

"standard_class"

"express"

"certified"

"certified_return_receipt"

"registered"

"usps_first_class"

"usps_standard_class"

"usps_eddm"

"usps_express_2_day"

"usps_express_3_day"

"usps_first_class_certified"

"usps_first_class_certified_return_receipt"

"usps_first_class_registered"

"usps_express_3_day_signature_confirmation"

"usps_express_3_day_certified"

"usps_express_3_day_certified_return_receipt"

"ca_post_lettermail"

"ca_post_personalized"

"ca_post_neighbourhood_mail"

"ups_express_overnight"

"ups_express_2_day"

"ups_express_3_day"

"royal_mail_first_class"

"royal_mail_second_class"

"au_post_second_class"

object: "postcard"

Always postcard.

sendDate: string

This order will transition from ready to printing on the day after this date. For example, if this is a date on Tuesday, the order will transition to printing on Wednesday at midnight eastern time.

formatdate-time

size: PostcardSize

Enum representing the supported postcard sizes.

One of the following:

"6x4"

"9x6"

"11x6"

status: "ready" or "printing" or "processed_for_delivery" or 2 more

See OrderStatus for more details on the status of this order.

One of the following:

"ready"

"printing"

"processed_for_delivery"

"completed"

"cancelled"

to: Contact { id, addressLine1, addressStatus, 20 more }

The recipient of this order. This will be provided even if you delete the underlying contact.

id: string

A unique ID prefixed with contact_

addressLine1: string

The first line of the contact's address.

addressStatus: "verified" or "corrected" or "failed"

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

countryCode: string

The ISO 3611-1 country code of the contact's address.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors: optional string

A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

cancellation: optional object { reason, cancelledByUser, note }

The cancellation details of this order. Populated if the order has been cancelled.

reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"

The reason for the cancellation.

One of the following:

"user_initiated"

"invalid_content"

"invalid_order_mailing_class"

cancelledByUser: optional string

The user ID who cancelled the order.

note: optional string

An optional note provided by the user who cancelled the order.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

from: optional Contact { id, addressLine1, addressStatus, 20 more }

The contact information of the sender.

id: string

A unique ID prefixed with contact_

addressLine1: string

The first line of the contact's address.

addressStatus: "verified" or "corrected" or "failed"

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

countryCode: string

The ISO 3611-1 country code of the contact's address.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors: optional string

A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

imbDate: optional string

The last date that the IMB status was updated. See imbStatus for more details.

formatdate-time

imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"

The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

One of the following:

"entered_mail_stream"

"out_for_delivery"

"returned_to_sender"

imbZIPCode: optional string

The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an imbStatus is present.

mergeVariables: optional map[unknown]

These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template exactly as they are case-sensitive. Note that these do not apply to PDFs uploaded with the order.

metadata: optional map[unknown]

See the section on Metadata.

trackingNumber: optional string

The tracking number of this order. Populated after an express/certified order has been processed for delivery.

url: optional string

PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all GET endpoints which produce this order.

This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the GET endpoint again.

formaturi

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}

ModelsExpand Collapse

DeletedResponse = object { id, deleted }

Generic response for delete operations.

id: string

The ID of the deleted resource.

deleted: true

Indicates the resource was successfully deleted.

Report = object { id, createdAt, live, 5 more }

Represents a saved Report definition.

id: string

Unique identifier for the report.

createdAt: string

Timestamp when the report was created.

formatdate-time

live: boolean

Indicates if the report is associated with the live or test environment.

object: "report"

Always report.

sqlQuery: string

The SQL query defining the report.

updatedAt: string

Timestamp when the report was last updated.

formatdate-time

description: optional string

An optional user-friendly description for the report.

metadata: optional map[string]

Optional key-value metadata associated with the report.

Print MailReportsSamples

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

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

ModelsExpand Collapse

ReportSample = object { id, records, report }

Represents the result of a report sample query.

id: string

Unique identifier for the sample query result.

records: array of map[unknown]

The actual data records returned by the sample query.

report: string

The ID of the report this sample was generated from, or null for ad-hoc samples.

ReportSampleCreateBase = object { limit, params }

Base properties for creating a report sample.

limit: optional number

Maximum number of rows to return in the sample.

formatint32

maximum1000

params: optional array of string

Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).

Print MailReportsExports

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

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}

ModelsExpand Collapse

ReportExport = object { id, createdAt, live, 11 more }

Represents a report export job and its results.

id: string

Unique identifier for the report export.

createdAt: string

Timestamp when the export was created.

formatdate-time

live: boolean

Indicates if the export is associated with the live or test environment.

object: "report_export"

Always report_export.

report: object { id, sqlQuery }

Details of the report this export was generated from.

id: string

The ID of the report.

sqlQuery: string

The SQL query used for this export (snapshotted at creation time).

updatedAt: string

Timestamp when the export was last updated (e.g., finished generation).

formatdate-time

description: optional string

An optional user-friendly description for the export.

failureMessage: optional string

If export generation failed, this contains the error message.

metadata: optional map[string]

Optional key-value metadata associated with the export.

outputURL: optional string

A signed URL to download the exported data (CSV format). Available when generation is complete and successful.

formaturi

params: optional array of string

Optional parameters to bind to the SQL query of the associated report.

rowCount: optional number

The number of rows in the exported data.

formatint64

sizeInBytes: optional number

The size of the generated export file in bytes.

formatint64

truncatedToBytes: optional number

If the output was truncated, indicates the byte limit reached.

formatint64

Print MailSelf Mailers

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

ModelsExpand Collapse

SelfMailer = object { id, createdAt, from, 17 more }

id: string

A unique ID prefixed with self_mailer_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

from: Contact { id, addressLine1, addressStatus, 20 more }

The contact information of the sender.

id: string

A unique ID prefixed with contact_

addressLine1: string

The first line of the contact's address.

addressStatus: "verified" or "corrected" or "failed"

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

countryCode: string

The ISO 3611-1 country code of the contact's address.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors: optional string

A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

live: boolean

true if this is a live mode resource else false.

mailingClass: "first_class" or "standard_class" or "express" or 23 more

The mailing class of this order. This determines the speed and cost of delivery. See OrderMailingClass for more details.

One of the following:

"first_class"

"standard_class"

"express"

"certified"

"certified_return_receipt"

"registered"

"usps_first_class"

"usps_standard_class"

"usps_eddm"

"usps_express_2_day"

"usps_express_3_day"

"usps_first_class_certified"

"usps_first_class_certified_return_receipt"

"usps_first_class_registered"

"usps_express_3_day_signature_confirmation"

"usps_express_3_day_certified"

"usps_express_3_day_certified_return_receipt"

"ca_post_lettermail"

"ca_post_personalized"

"ca_post_neighbourhood_mail"

"ups_express_overnight"

"ups_express_2_day"

"ups_express_3_day"

"royal_mail_first_class"

"royal_mail_second_class"

"au_post_second_class"

object: "self_mailer"

Always self_mailer.

sendDate: string

This order will transition from ready to printing on the day after this date. For example, if this is a date on Tuesday, the order will transition to printing on Wednesday at midnight eastern time.

formatdate-time

size: SelfMailerSize

Enum representing the supported self-mailer sizes.

One of the following:

"8.5x11_bifold"

"8.5x11_trifold"

"9.5x16_trifold"

status: "ready" or "printing" or "processed_for_delivery" or 2 more

See OrderStatus for more details on the status of this order.

One of the following:

"ready"

"printing"

"processed_for_delivery"

"completed"

"cancelled"

to: Contact { id, addressLine1, addressStatus, 20 more }

The recipient of this order. This will be provided even if you delete the underlying contact.

id: string

A unique ID prefixed with contact_

addressLine1: string

The first line of the contact's address.

addressStatus: "verified" or "corrected" or "failed"

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

countryCode: string

The ISO 3611-1 country code of the contact's address.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors: optional string

A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

addressLine2: optional string

Second line of the contact's address, if applicable.

city: optional string

The city of the contact's address.

companyName: optional string

Company name of the contact.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

email: optional string

Email of the contact.

firstName: optional string

First name of the contact.

forceVerifiedStatus: optional boolean

If true, PostGrid will force this contact to have an addressStatus of verified even if our address verification system says otherwise.

jobTitle: optional string

Job title of the contact.

lastName: optional string

Last name of the contact.

metadata: optional map[unknown]

See the section on Metadata.

phoneNumber: optional string

Phone number of the contact.

postalOrZip: optional string

The postal or ZIP code of the contact's address.

provinceOrState: optional string

Province or state of the contact's address.

skipVerification: optional boolean

If true, PostGrid will skip running this contact's address through our address verification system.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

cancellation: optional object { reason, cancelledByUser, note }

The cancellation details of this order. Populated if the order has been cancelled.

reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"

The reason for the cancellation.

One of the following:

"user_initiated"

"invalid_content"

"invalid_order_mailing_class"

cancelledByUser: optional string

The user ID who cancelled the order.

note: optional string

An optional note provided by the user who cancelled the order.

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

imbDate: optional string

The last date that the IMB status was updated. See imbStatus for more details.

formatdate-time

imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"

The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

One of the following:

"entered_mail_stream"

"out_for_delivery"

"returned_to_sender"

imbZIPCode: optional string

The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an imbStatus is present.

mergeVariables: optional map[unknown]

These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template exactly as they are case-sensitive. Note that these do not apply to PDFs uploaded with the order.

metadata: optional map[unknown]

See the section on Metadata.

trackingNumber: optional string

The tracking number of this order. Populated after an express/certified order has been processed for delivery.

url: optional string

PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all GET endpoints which produce this order.

This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the GET endpoint again.

formaturi

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

ModelsExpand Collapse

EmailPreferences = object { orderPreviewSendPreference }

A set of preferences for how a user should receive emails.

orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"

The list of preferences for receiving order preview emails.

One of the following:

"do_not_send"

"send_live_only"

"send_live_and_test"

SubOrganization = object { id, countryCode, createdAt, 6 more }

The Sub-Organization object.

id: string

A unique ID prefixed with sub_org_.

countryCode: string

The country code of the sub-organization.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

limit: number

The limit of mailings the sub-organization can send before being charged overages for the month.

name: string

The name of the sub-organization.

object: "sub_org"

Always sub_org.

spend: number

The current rolling charge for the sub-organization for the month, in cents.

updatedAt: string

The UTC time at which this resource was last update.

formatdate-time

usage: number

The amount of mail the sub-organization has sent out this month.

Print MailTemplates

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}

ModelsExpand Collapse

Template = object { id, createdAt, live, 5 more }

id: string

A unique ID prefixed with template_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "template"

Always template.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

html: optional string

The HTML content of this template.

metadata: optional map[unknown]

See the section on Metadata.