Print Mail

ModelsExpand Collapse

class ContactCreateWithCompanyName: …

address_line1: str

The first line of the contact's address.

company_name: str

country_code: str

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

class ContactCreateWithFirstName: …

address_line1: str

The first line of the contact's address.

country_code: str

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

first_name: str

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

Print MailBank Accounts

Create Bank Account

print_mail.bank_accounts.create() -> BankAccount

POST/print-mail/v1/bank_accounts

List Bank Accounts

print_mail.bank_accounts.list() -> SyncSkipLimit[BankAccount]

GET/print-mail/v1/bank_accounts

Get Bank Account

print_mail.bank_accounts.retrieve() -> BankAccount

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

Delete Bank Account

print_mail.bank_accounts.delete() -> BankAccountDeleteResponse

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

ModelsExpand Collapse

class BankAccount: …

id: str

A unique ID prefixed with bank_account_

account_number: str

The account number of the bank account.

bank_country_code: 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"

bank_name: str

The name of the bank.

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["bank_account"]

Always bank_account.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

bank_primary_line: Optional[str]

The primary address line of the bank.

bank_secondary_line: Optional[str]

The secondary address line of the bank.

ca_designation_number: Optional[str]

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

description: Optional[str]

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

metadata: Optional[Dict[str, object]]

See the section on Metadata.

route_number: Optional[str]

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

routing_number: Optional[str]

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

signature_image: Optional[str]

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

formaturi

signature_text: Optional[str]

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

transit_number: Optional[str]

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

Literal["CA", "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

print_mail.campaigns.create() -> Campaign

POST/print-mail/v1/campaigns

List Campaigns

print_mail.campaigns.list() -> SyncSkipLimit[Campaign]

GET/print-mail/v1/campaigns

Get Campaign

print_mail.campaigns.retrieve() -> Campaign

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

Update Campaign

print_mail.campaigns.update(, ) -> Campaign

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

Delete Campaign

print_mail.campaigns.delete() -> CampaignDeleteResponse

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

Send Campaign

print_mail.campaigns.send(, ) -> Campaign

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

ModelsExpand Collapse

class Campaign: …

Represents a bulk mail campaign.

id: str

A unique ID prefixed with campaign_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

created_count: int

The number of orders successfully created for this campaign.

formatint32

live: bool

true if this is a live mode resource else false.

mailing_list: str

The ID of the mailing list associated with this campaign.

status: Literal["drafting", "changes_required", "creating_orders", 4 more]

Status of the campaign lifecycle.

One of the following:

"drafting"

"changes_required"

"creating_orders"

"draft"

"ready"

"printing"

"processed_for_delivery"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

cheque_profile: Optional[str]

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

default_sender_contact: Optional[str]

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

description: Optional[str]

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

errors: Optional[List[Error]]

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

message: str

A human-readable message describing the error.

type: Literal["processing_error", "internal_error"]

Type of error encountered during campaign processing.

One of the following:

"processing_error"

"internal_error"

letter_profile: Optional[str]

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

metadata: Optional[Dict[str, object]]

See the section on Metadata.

order_preview_url: Optional[str]

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

formaturi

postcard_profile: Optional[str]

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

report_url: Optional[str]

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

formaturi

self_mailer_profile: Optional[str]

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

send_date: Optional[datetime]

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

formatdate-time

Print MailCheques

Create Cheque

print_mail.cheques.create() -> Cheque

POST/print-mail/v1/cheques

List Cheques

print_mail.cheques.list() -> SyncSkipLimit[Cheque]

GET/print-mail/v1/cheques

Get Cheque

print_mail.cheques.retrieve() -> Cheque

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

Cancel Cheque

print_mail.cheques.delete() -> Cheque

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

Get Cheque Preview

print_mail.cheques.retrieve_url() -> ChequeRetrieveURLResponse

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

Retrieve Cheque Deposit-Ready PDF (Digital Only)

print_mail.cheques.retrieve_with_deposit_ready_pdf() -> Cheque

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

ModelsExpand Collapse

class Cheque: …

id: str

A unique ID prefixed with cheque_

amount: int

The amount of the cheque in cents.

formatint32

bank_account: str

The bank account (ID) associated with the cheque.

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

currency_code: Literal["USD", "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

The contact information of the sender.

id: str

A unique ID prefixed with contact_

address_line1: str

The first line of the contact's address.

address_status: Literal["verified", "corrected", "failed"]

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

country_code: str

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

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["contact"]

Always contact.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

address_errors: Optional[str]

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

live: bool

true if this is a live mode resource else false.

mailing_class: Literal["first_class", "standard_class", "express", 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: Literal["cheque"]

Always cheque.

send_date: datetime

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: Literal["ready", "printing", "processed_for_delivery", 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

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

id: str

A unique ID prefixed with contact_

address_line1: str

The first line of the contact's address.

address_status: Literal["verified", "corrected", "failed"]

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

country_code: str

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

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["contact"]

Always contact.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

address_errors: Optional[str]

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

cancellation: Optional[Cancellation]

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

reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]

The reason for the cancellation.

One of the following:

"user_initiated"

"invalid_content"

"invalid_order_mailing_class"

cancelled_by_user: Optional[str]

The user ID who cancelled the order.

note: Optional[str]

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

deposit_ready_pdfurl: Optional[str]

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

formaturi

description: Optional[str]

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

digital_only: Optional[DigitalOnly]

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

watermark: str

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

envelope: Optional[Union[Literal["standard"], str, null]]

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

One of the following:

Literal["standard"]

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

str

imb_date: Optional[datetime]

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

formatdate-time

imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "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"

imb_zip_code: Optional[str]

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

logo_url: Optional[str]

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[str]

The memo of the cheque.

merge_variables: Optional[Dict[str, object]]

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[str]

The message of the cheque.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

number: Optional[int]

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

tracking_number: Optional[str]

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

url: Optional[str]

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

Literal["us_letter", "us_legal"]

Enum representing the supported cheque sizes.

One of the following:

"us_letter"

"us_legal"

class DigitalOnly: …

watermark: str

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

Print MailContacts

Create Contact

print_mail.contacts.create() -> Contact

POST/print-mail/v1/contacts

List Contacts

print_mail.contacts.list() -> SyncSkipLimit[Contact]

GET/print-mail/v1/contacts

Get Contact

print_mail.contacts.retrieve() -> Contact

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

Delete Contact

print_mail.contacts.delete() -> ContactDeleteResponse

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

ModelsExpand Collapse

class Contact: …

id: str

A unique ID prefixed with contact_

address_line1: str

The first line of the contact's address.

address_status: Literal["verified", "corrected", "failed"]

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

country_code: str

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

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["contact"]

Always contact.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

address_errors: Optional[str]

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

ContactCreate

One of the following:

class ContactCreateWithFirstName: …

address_line1: str

The first line of the contact's address.

country_code: str

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

first_name: str

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

class ContactCreateWithCompanyName: …

address_line1: str

The first line of the contact's address.

company_name: str

country_code: str

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

Print MailLetters

Create Letter

print_mail.letters.create() -> Letter

POST/print-mail/v1/letters

List Letters

print_mail.letters.list() -> SyncSkipLimit[Letter]

GET/print-mail/v1/letters

Get Letter

print_mail.letters.retrieve() -> Letter

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

Cancel Letter

print_mail.letters.delete() -> Letter

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

Get Letter Preview

print_mail.letters.retrieve_url() -> LetterRetrieveURLResponse

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

ModelsExpand Collapse

Literal["top_first_page", "insert_blank_page"]

Enum representing the placement of the address on the letter.

One of the following:

"top_first_page"

"insert_blank_page"

class AttachedPdf: …

Model representing an attached PDF.

file: str

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

formaturi

placement: Literal["before_template", "after_template"]

Enum representing the placement of the attached PDF.

One of the following:

"before_template"

"after_template"

class Letter: …

id: str

A unique ID prefixed with letter_

address_placement: AddressPlacement

Enum representing the placement of the address on the letter.

One of the following:

"top_first_page"

"insert_blank_page"

color: bool

Indicates if the letter is in color.

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

double_sided: bool

Indicates if the letter is double-sided.

envelope: str

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

from_: Contact

The contact information of the sender.

id: str

A unique ID prefixed with contact_

address_line1: str

The first line of the contact's address.

address_status: Literal["verified", "corrected", "failed"]

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

country_code: str

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

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["contact"]

Always contact.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

address_errors: Optional[str]

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

live: bool

true if this is a live mode resource else false.

mailing_class: Literal["first_class", "standard_class", "express", 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: Literal["letter"]

Always letter.

send_date: datetime

formatdate-time

size: LetterSize

Enum representing the supported letter sizes.

One of the following:

"us_letter"

"a4"

status: Literal["ready", "printing", "processed_for_delivery", 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

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

id: str

A unique ID prefixed with contact_

address_line1: str

The first line of the contact's address.

address_status: Literal["verified", "corrected", "failed"]

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

country_code: str

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

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["contact"]

Always contact.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

address_errors: Optional[str]

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

attached_pdf: Optional[AttachedPdf]

Model representing an attached PDF.

file: str

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

formaturi

placement: Literal["before_template", "after_template"]

Enum representing the placement of the attached PDF.

One of the following:

"before_template"

"after_template"

cancellation: Optional[Cancellation]

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

reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]

The reason for the cancellation.

One of the following:

"user_initiated"

"invalid_content"

"invalid_order_mailing_class"

cancelled_by_user: Optional[str]

The user ID who cancelled the order.

note: Optional[str]

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

description: Optional[str]

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

html: Optional[str]

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

imb_date: Optional[datetime]

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

formatdate-time

imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "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"

imb_zip_code: Optional[str]

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

merge_variables: Optional[Dict[str, object]]

metadata: Optional[Dict[str, object]]

See the section on Metadata.

pdf_workflow_run: Optional[str]

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

perforated_page: Optional[Literal[1]]

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

plastic_card: Optional[PlasticCard]

Model representing a plastic card.

size: Literal["standard"]

Enum representing the size of the plastic card.

double_sided: Optional[DoubleSided]

Model representing a double-sided plastic card.

back_html: Optional[str]

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

back_template: Optional[str]

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

front_html: Optional[str]

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

front_template: Optional[str]

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

pdf: Optional[str]

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

formaturi

single_sided: Optional[SingleSided]

Model representing a single-sided plastic card.

html: Optional[str]

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

pdf: Optional[str]

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

formaturi

The template ID for the single-sided plastic card.

return_envelope: Optional[str]

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

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

tracking_number: Optional[str]

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

uploaded_pdf: Optional[str]

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

formaturi

url: Optional[str]

formaturi

Literal["us_letter", "a4"]

Enum representing the supported letter sizes.

One of the following:

"us_letter"

"a4"

class PlasticCard: …

Model representing a plastic card.

size: Literal["standard"]

Enum representing the size of the plastic card.

double_sided: Optional[DoubleSided]

Model representing a double-sided plastic card.

back_html: Optional[str]

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

back_template: Optional[str]

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

front_html: Optional[str]

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

front_template: Optional[str]

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

pdf: Optional[str]

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

formaturi

single_sided: Optional[SingleSided]

Model representing a single-sided plastic card.

html: Optional[str]

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

pdf: Optional[str]

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

formaturi

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

print_mail.mailing_list_imports.create() -> MailingListImportResponse

POST/print-mail/v1/mailing_list_imports

List Mailing List Imports

print_mail.mailing_list_imports.list() -> SyncSkipLimit[MailingListImportResponse]

GET/print-mail/v1/mailing_list_imports

Update Mailing List Import

print_mail.mailing_list_imports.update(, ) -> MailingListImportResponse

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

Get Mailing List Import

print_mail.mailing_list_imports.retrieve() -> MailingListImportResponse

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

Delete Mailing List Import

print_mail.mailing_list_imports.delete() -> MailingListImportDeleteResponse

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

ModelsExpand Collapse

Literal["csv"]

Type of file supported for mailing list imports.

class MailingListImportResponse: …

Read-only view of a MailingListImport

id: str

A unique ID prefixed with mailing_list_import_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

errors: List[Error]

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

message: str

A human-readable message describing the error.

type: Literal["no_valid_contacts_error", "multiple_countries_error", "invalid_contact_count_error", "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: File

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

file_type: FileType

Type of file supported for mailing list imports.

receiver_address_mapping: Dict[str, str]

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

The signed URL your controller generates.

formaturi

receiver_merge_variable_mapping: Optional[Dict[str, str]]

Optional mapping of columns for receiver merge variables.

sender_address_mapping: Optional[Dict[str, str]]

Optional mapping of columns for sender addresses.

sender_merge_variable_mapping: Optional[Dict[str, str]]

Optional mapping of columns for sender merge variables.

invalid_row_count: int

Number of invalid rows found in the file.

formatint32

live: bool

true if this is a live mode resource else false.

notes: List[Note]

Additional notes about the import process.

message: str

A human-readable message describing the note.

type: Literal["truncated_test_file", "skipped_invalid_contacts"]

Type of note attached to the import process.

One of the following:

"truncated_test_file"

"skipped_invalid_contacts"

organization: str

The organization that owns this import.

receiver_status_count: VerificationStatusCount

Count of contact verification statuses.

corrected_count: int

Number of contacts that were corrected during verification.

formatint32

failed_count: int

Number of contacts that failed verification.

formatint32

verified_count: int

Number of contacts that were verified without changes.

formatint32

status: Literal["validating", "completed", "changes_required"]

Status of the mailing list import process.

One of the following:

"validating"

"completed"

"changes_required"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

valid_row_count: int

Number of valid rows processed from the file.

formatint32

description: Optional[str]

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

metadata: Optional[Dict[str, object]]

See the section on Metadata.

report_url: Optional[str]

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

formaturi

sender_status_count: Optional[VerificationStatusCount]

Count of contact verification statuses.

corrected_count: int

Number of contacts that were corrected during verification.

formatint32

failed_count: int

Number of contacts that failed verification.

formatint32

verified_count: int

Number of contacts that were verified without changes.

formatint32

class VerificationStatusCount: …

Count of contact verification statuses.

corrected_count: int

Number of contacts that were corrected during verification.

formatint32

failed_count: int

Number of contacts that failed verification.

formatint32

verified_count: int

Number of contacts that were verified without changes.

formatint32

Print MailMailing Lists

Create Mailing List

print_mail.mailing_lists.create() -> MailingList

POST/print-mail/v1/mailing_lists

List Mailing Lists

print_mail.mailing_lists.list() -> SyncSkipLimit[MailingList]

GET/print-mail/v1/mailing_lists

Get Mailing List

print_mail.mailing_lists.retrieve() -> MailingList

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

Update Mailing List

print_mail.mailing_lists.update(, ) -> MailingListUpdate

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

Delete Mailing List

print_mail.mailing_lists.delete() -> MailingListDeleteResponse

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

Submit a Mailing List Job

print_mail.mailing_lists.jobs(, ) -> MailingList

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

ModelsExpand Collapse

class MailingList: …

Represents a mailing list.

id: str

A unique ID prefixed with mailing_list_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]

Status of the mailing list processing.

One of the following:

"creating_contacts"

"removing_contacts"

"counting_recipient_country_codes"

"completed"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

description: Optional[str]

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

errors: Optional[List[Error]]

A list of processing errors encountered, if any.

message: str

A human-readable message describing the error.

type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "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[Dict[str, object]]

See the section on Metadata.

class MailingListUpdate: …

Parameters for updating an existing mailing list.

description: Optional[str]

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

metadata: Optional[Dict[str, object]]

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

print_mail.order_profiles.cheques.create() -> ChequeProfile

POST/print-mail/v1/order_profiles/cheques

List Cheque Profiles

print_mail.order_profiles.cheques.list() -> SyncSkipLimit[ChequeListResponse]

GET/print-mail/v1/order_profiles/cheques

Retrieve Cheque Profile

print_mail.order_profiles.cheques.retrieve(, ) -> ChequeProfile

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

Update Cheque Profile

print_mail.order_profiles.cheques.update(, ) -> ChequeProfile

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

Delete Cheque Profile

print_mail.order_profiles.cheques.delete() -> ChequeDeleteResponse

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

ModelsExpand Collapse

class ChequeProfile: …

id: str

Unique identifier for the order profile.

bank_account: str

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

created_at: datetime

Timestamp when the profile was created.

formatdate-time

currency_code: CurrencyCode

Enum representing the supported currency codes.

One of the following:

"CAD"

"USD"

live: bool

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

object: Literal["cheque_profile"]

Always cheque_profile.

size: ChequeSize

Enum representing the supported cheque sizes.

One of the following:

"us_letter"

"us_legal"

updated_at: datetime

Timestamp when the profile was last updated.

formatdate-time

description: Optional[str]

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

letter_template: Optional[str]

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

letter_uploaded_pdf: Optional[str]

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

formaturi

logo: Optional[str]

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

formaturi

mailing_class: Optional[Literal["first_class", "standard_class", "express", 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[str]

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

merge_variables: Optional[Dict[str, object]]

Default merge variables for orders created using this profile.

message: Optional[str]

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

metadata: Optional[Dict[str, str]]

Optional key-value metadata.

Literal["CAD", "USD"]

Enum representing the supported currency codes.

One of the following:

"CAD"

"USD"

Print MailOrder ProfilesLetters

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

Create Letter Profile

print_mail.order_profiles.letters.create() -> LetterProfile

POST/print-mail/v1/order_profiles/letters

List Letter Profiles

print_mail.order_profiles.letters.list() -> SyncSkipLimit[LetterProfile]

GET/print-mail/v1/order_profiles/letters

Retrieve Letter Profile

print_mail.order_profiles.letters.retrieve(, ) -> LetterProfile

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

Update Letter Profile

print_mail.order_profiles.letters.update(, ) -> LetterProfile

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

Delete Letter Profile

print_mail.order_profiles.letters.delete() -> LetterDeleteResponse

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

ModelsExpand Collapse

class LetterProfile: …

id: str

Unique identifier for the order profile.

created_at: datetime

Timestamp when the profile was created.

formatdate-time

live: bool

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

object: Literal["letter_profile"]

Always letter_profile.

size: LetterSize

Enum representing the supported letter sizes.

One of the following:

"us_letter"

"a4"

updated_at: datetime

Timestamp when the profile was last updated.

formatdate-time

address_placement: Optional[AddressPlacement]

Enum representing the placement of the address on the letter.

One of the following:

"top_first_page"

"insert_blank_page"

attached_pdf: Optional[AttachedPdf]

Model representing an attached PDF.

file: str

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

formaturi

placement: Literal["before_template", "after_template"]

Enum representing the placement of the attached PDF.

One of the following:

"before_template"

"after_template"

color: Optional[bool]

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

description: Optional[str]

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

double_sided: Optional[bool]

Specifies whether to print on both sides of the paper.

envelope: Optional[str]

ID of a custom envelope to use.

mailing_class: Optional[Literal["first_class", "standard_class", "express", 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"

merge_variables: Optional[Dict[str, object]]

Default merge variables for orders created using this profile.

metadata: Optional[Dict[str, str]]

Optional key-value metadata.

perforated_page: Optional[Literal[1]]

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

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

uploaded_pdf: Optional[str]

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

formaturi

Print MailOrder ProfilesPostcards

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

Create Postcard Profile

print_mail.order_profiles.postcards.create() -> PostcardProfile

POST/print-mail/v1/order_profiles/postcards

List Postcard Profiles

print_mail.order_profiles.postcards.list() -> SyncSkipLimit[PostcardProfile]

GET/print-mail/v1/order_profiles/postcards

Retrieve Postcard Profile

print_mail.order_profiles.postcards.retrieve(, ) -> PostcardProfile

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

Update Postcard Profile

print_mail.order_profiles.postcards.update(, ) -> PostcardProfile

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

Delete Postcard Profile

print_mail.order_profiles.postcards.delete() -> PostcardDeleteResponse

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

ModelsExpand Collapse

class PostcardProfile: …

id: str

Unique identifier for the order profile.

created_at: datetime

Timestamp when the profile was created.

formatdate-time

live: bool

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

object: Literal["postcard_profile"]

Always postcard_profile.

size: PostcardSize

Enum representing the supported postcard sizes.

One of the following:

"6x4"

"9x6"

"11x6"

updated_at: datetime

Timestamp when the profile was last updated.

formatdate-time

back_template: Optional[str]

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

description: Optional[str]

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

front_template: Optional[str]

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

mailing_class: Optional[Literal["first_class", "standard_class", "express", 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"

merge_variables: Optional[Dict[str, object]]

Default merge variables for orders created using this profile.

metadata: Optional[Dict[str, str]]

Optional key-value metadata.

uploaded_pdf: Optional[str]

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

formaturi

Literal["6x4", "9x6", "11x6"]

Enum representing the supported postcard sizes.

One of the following:

"6x4"

"9x6"

"11x6"

Print MailOrder ProfilesSelf Mailers

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

Create Self-Mailer Profile

print_mail.order_profiles.self_mailers.create() -> SelfMailerProfile

POST/print-mail/v1/order_profiles/self_mailers

List Self-Mailer Profiles

print_mail.order_profiles.self_mailers.list() -> SyncSkipLimit[SelfMailerProfile]

GET/print-mail/v1/order_profiles/self_mailers

Retrieve Self-Mailer Profile

print_mail.order_profiles.self_mailers.retrieve(, ) -> SelfMailerProfile

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

Update Self-Mailer Profile

print_mail.order_profiles.self_mailers.update(, ) -> SelfMailerProfile

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

Delete Self-Mailer Profile

print_mail.order_profiles.self_mailers.delete() -> SelfMailerDeleteResponse

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

ModelsExpand Collapse

class SelfMailerProfile: …

Represents a Self-Mailer Profile resource.

id: str

Unique identifier for the order profile.

created_at: datetime

Timestamp when the profile was created.

formatdate-time

live: bool

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

object: Literal["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"

updated_at: datetime

Timestamp when the profile was last updated.

formatdate-time

description: Optional[str]

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

inside_template: Optional[str]

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

mailing_class: Optional[Literal["first_class", "standard_class", "express", 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"

merge_variables: Optional[Dict[str, object]]

Default merge variables for orders created using this profile.

metadata: Optional[Dict[str, str]]

Optional key-value metadata.

outside_template: Optional[str]

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

uploaded_pdf: Optional[str]

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

formaturi

Literal["8.5x11_bifold", "8.5x11_trifold", "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

print_mail.postcards.create() -> Postcard

POST/print-mail/v1/postcards

List Postcards

print_mail.postcards.list() -> SyncSkipLimit[Postcard]

GET/print-mail/v1/postcards

Get Postcard

print_mail.postcards.retrieve() -> Postcard

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

Cancel Postcard

print_mail.postcards.delete() -> Postcard

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

Get Postcard Preview

print_mail.postcards.retrieve_url() -> PostcardRetrieveURLResponse

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

ModelsExpand Collapse

class Postcard: …

id: str

A unique ID prefixed with postcard_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

mailing_class: Literal["first_class", "standard_class", "express", 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: Literal["postcard"]

Always postcard.

send_date: datetime

formatdate-time

size: PostcardSize

Enum representing the supported postcard sizes.

One of the following:

"6x4"

"9x6"

"11x6"

status: Literal["ready", "printing", "processed_for_delivery", 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

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

id: str

A unique ID prefixed with contact_

address_line1: str

The first line of the contact's address.

address_status: Literal["verified", "corrected", "failed"]

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

country_code: str

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

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["contact"]

Always contact.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

address_errors: Optional[str]

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

cancellation: Optional[Cancellation]

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

reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]

The reason for the cancellation.

One of the following:

"user_initiated"

"invalid_content"

"invalid_order_mailing_class"

cancelled_by_user: Optional[str]

The user ID who cancelled the order.

note: Optional[str]

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

description: Optional[str]

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

from_: Optional[Contact]

The contact information of the sender.

id: str

A unique ID prefixed with contact_

address_line1: str

The first line of the contact's address.

address_status: Literal["verified", "corrected", "failed"]

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

country_code: str

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

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["contact"]

Always contact.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

address_errors: Optional[str]

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

imb_date: Optional[datetime]

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

formatdate-time

imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "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"

imb_zip_code: Optional[str]

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

merge_variables: Optional[Dict[str, object]]

metadata: Optional[Dict[str, object]]

See the section on Metadata.

tracking_number: Optional[str]

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

url: Optional[str]

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

print_mail.reports.create() -> Report

POST/print-mail/v1/reports

Run Ad-hoc Query

print_mail.reports.sample() -> ReportSample

POST/print-mail/v1/reports/samples

Update Report

print_mail.reports.update(, ) -> Report

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

List Saved Reports

print_mail.reports.list() -> SyncSkipLimit[Report]

GET/print-mail/v1/reports

Retrieve Saved Report

print_mail.reports.retrieve() -> Report

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

Delete Saved Report

print_mail.reports.delete() -> DeletedResponse

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

ModelsExpand Collapse

class DeletedResponse: …

Generic response for delete operations.

id: str

The ID of the deleted resource.

deleted: Literal[true]

Indicates the resource was successfully deleted.

class Report: …

Represents a saved Report definition.

id: str

Unique identifier for the report.

created_at: datetime

Timestamp when the report was created.

formatdate-time

live: bool

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

object: Literal["report"]

Always report.

sql_query: str

The SQL query defining the report.

updated_at: datetime

Timestamp when the report was last updated.

formatdate-time

description: Optional[str]

An optional user-friendly description for the report.

metadata: Optional[Dict[str, str]]

Optional key-value metadata associated with the report.

Print MailReportsSamples

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

Sample a Saved Report

print_mail.reports.samples.create(, ) -> ReportSample

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

ModelsExpand Collapse

class ReportSample: …

Represents the result of a report sample query.

id: str

Unique identifier for the sample query result.

records: List[Dict[str, object]]

The actual data records returned by the sample query.

report: Optional[str]

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

class ReportSampleCreateBase: …

Base properties for creating a report sample.

limit: Optional[int]

Maximum number of rows to return in the sample.

formatint32

maximum1000

params: Optional[List[str]]

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

Print MailReportsExports

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

Create a Report Export

print_mail.reports.exports.create(, ) -> ReportExport

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

Get Report Export

print_mail.reports.exports.retrieve(, ) -> ReportExport

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

Delete Report Export

print_mail.reports.exports.delete(, ) -> DeletedResponse

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

ModelsExpand Collapse

class ReportExport: …

Represents a report export job and its results.

id: str

Unique identifier for the report export.

created_at: datetime

Timestamp when the export was created.

formatdate-time

live: bool

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

object: Literal["report_export"]

Always report_export.

report: Report

Details of the report this export was generated from.

id: str

The ID of the report.

sql_query: str

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

updated_at: datetime

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

formatdate-time

description: Optional[str]

An optional user-friendly description for the export.

failure_message: Optional[str]

If export generation failed, this contains the error message.

metadata: Optional[Dict[str, str]]

Optional key-value metadata associated with the export.

output_url: Optional[str]

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

formaturi

params: Optional[List[str]]

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

row_count: Optional[int]

The number of rows in the exported data.

formatint64

size_in_bytes: Optional[int]

The size of the generated export file in bytes.

formatint64

truncated_to_bytes: Optional[int]

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

formatint64

Print MailSelf Mailers

Create Self Mailer

print_mail.self_mailers.create() -> SelfMailer

POST/print-mail/v1/self_mailers

List Self Mailers

print_mail.self_mailers.list() -> SyncSkipLimit[SelfMailer]

GET/print-mail/v1/self_mailers

Get Self Mailer

print_mail.self_mailers.retrieve() -> SelfMailer

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

Cancel Self Mailer

print_mail.self_mailers.delete() -> SelfMailer

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

Get Self Mailer Preview

print_mail.self_mailers.retrieve_url() -> SelfMailerRetrieveURLResponse

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

ModelsExpand Collapse

class SelfMailer: …

id: str

A unique ID prefixed with self_mailer_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

from_: Contact

The contact information of the sender.

id: str

A unique ID prefixed with contact_

address_line1: str

The first line of the contact's address.

address_status: Literal["verified", "corrected", "failed"]

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

country_code: str

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

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["contact"]

Always contact.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

address_errors: Optional[str]

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

live: bool

true if this is a live mode resource else false.

mailing_class: Literal["first_class", "standard_class", "express", 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: Literal["self_mailer"]

Always self_mailer.

send_date: datetime

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: Literal["ready", "printing", "processed_for_delivery", 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

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

id: str

A unique ID prefixed with contact_

address_line1: str

The first line of the contact's address.

address_status: Literal["verified", "corrected", "failed"]

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

country_code: str

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

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["contact"]

Always contact.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

address_errors: Optional[str]

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact's address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact's address.

skip_verification: Optional[bool]

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

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

cancellation: Optional[Cancellation]

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

reason: Literal["user_initiated", "invalid_content", "invalid_order_mailing_class"]

The reason for the cancellation.

One of the following:

"user_initiated"

"invalid_content"

"invalid_order_mailing_class"

cancelled_by_user: Optional[str]

The user ID who cancelled the order.

note: Optional[str]

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

description: Optional[str]

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

imb_date: Optional[datetime]

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

formatdate-time

imb_status: Optional[Literal["entered_mail_stream", "out_for_delivery", "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"

imb_zip_code: Optional[str]

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

merge_variables: Optional[Dict[str, object]]

metadata: Optional[Dict[str, object]]

See the section on Metadata.

tracking_number: Optional[str]

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

url: Optional[str]

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]

ModelsExpand Collapse

class EmailPreferences: …

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

order_preview_send_preference: Optional[Literal["do_not_send", "send_live_only", "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"

class SubOrganization: …

The Sub-Organization object.

id: str

A unique ID prefixed with sub_org_.

country_code: str

The country code of the sub-organization.

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

limit: int

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

The name of the sub-organization.

object: Literal["sub_org"]

Always sub_org.

spend: int

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

updated_at: datetime

The UTC time at which this resource was last update.

formatdate-time

usage: int

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

ModelsExpand Collapse

class Template: …

id: str

A unique ID prefixed with template_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["template"]

Always template.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

description: Optional[str]

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

html: Optional[str]

The HTML content of this template.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

Print Mail

ModelsExpand Collapse

Print MailBank Accounts

ModelsExpand Collapse

Print MailCampaigns

ModelsExpand Collapse

Print MailCheques

ModelsExpand Collapse

Print MailContacts

ModelsExpand Collapse

Print MailLetters

ModelsExpand Collapse

Print MailMailing List Imports

ModelsExpand Collapse

Print MailMailing Lists

ModelsExpand Collapse

Print MailOrder Profiles

Print MailOrder ProfilesCheques

ModelsExpand Collapse

Print MailOrder ProfilesLetters

ModelsExpand Collapse

Print MailOrder ProfilesPostcards

ModelsExpand Collapse

Print MailOrder ProfilesSelf Mailers

ModelsExpand Collapse

Print MailPostcards

ModelsExpand Collapse

Print MailReports

ModelsExpand Collapse

Print MailReportsSamples

ModelsExpand Collapse

Print MailReportsExports

ModelsExpand Collapse

Print MailSelf Mailers

ModelsExpand Collapse

Print MailSub Organizations

ModelsExpand Collapse

Print MailTemplates

ModelsExpand Collapse

What can I help you with?

Suggestions