API Reference

Print Mail

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Contacts

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

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

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

Create Contact

print_mail.contacts.create(ContactCreateParams**kwargs) -> Contact

POST/print-mail/v1/contacts

List Contacts

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

GET/print-mail/v1/contacts

Get Contact

print_mail.contacts.retrieve(strid) -> Contact

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

Delete Contact

print_mail.contacts.delete(strid) -> 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.

secret: Optional[bool]

If true, the contact’s details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

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.

secret: Optional[bool]

If true, the contact’s details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

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.

secret: Optional[bool]

If true, the contact’s details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

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.

secret: Optional[bool]

If true, the contact’s details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

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.

secret: Optional[bool]

If true, the contact’s details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

skip_verification: Optional[bool]

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

class ContactDeleteResponse: …

id: str

A unique ID prefixed with contact_

deleted: Literal[true]

object: Literal["contact"]

Always contact.