# Print Mail
# Contacts
## Create Contact
`print_mail.contacts.create(ContactCreateParams**kwargs) -> Contact`
**post** `/print-mail/v1/contacts`
Creates a contact. This will also verify the contact's address **if you create it using a live API key**. To sucessfully create a contact, either a `firstName`, a `companyName`, or both are required. You can supply both, but you **cannot** supply neither.
You have the option to supply the entire address (except for `countryCode`) via `addressLine1`, in which case PostGrid will parse it automatically. However, this is **not guaranteed to be correct**, so we recommend passing along the structured address fields (`city`, `provinceOrState`, etc) if you have them.
_Note that if you create a contact that has identical information to another contact, this will simply update the description of the existing contact and return it. This avoids creating duplicate contacts._
### Parameters
- `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.
### Returns
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
contact = client.print_mail.contacts.create(
address_line1="90 Canal St Suite 600, Boston MA 90210",
country_code="US",
first_name="Kevin",
company_name="PostGrid",
)
print(contact.id)
```
#### Response
```json
{
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
}
```
## List Contacts
`print_mail.contacts.list(ContactListParams**kwargs) -> SyncSkipLimit[Contact]`
**get** `/print-mail/v1/contacts`
Get a list of contacts.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.contacts.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"skip": 0,
"limit": 10,
"totalCount": 1,
"object": "list",
"data": [
{
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
}
]
}
```
## Get Contact
`print_mail.contacts.retrieve(strid) -> Contact`
**get** `/print-mail/v1/contacts/{id}`
Retrieve a contact.
### Parameters
- `id: str`
### Returns
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
contact = client.print_mail.contacts.retrieve(
"id",
)
print(contact.id)
```
#### Response
```json
{
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
}
```
## Delete Contact
`print_mail.contacts.delete(strid) -> ContactDeleteResponse`
**delete** `/print-mail/v1/contacts/{id}`
Delete a contact. Note that this will not affect orders that were sent to this contact.
### Parameters
- `id: str`
### Returns
- `class ContactDeleteResponse: …`
- `id: str`
A unique ID prefixed with contact_
- `deleted: Literal[true]`
- `true`
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
contact = client.print_mail.contacts.delete(
"id",
)
print(contact.id)
```
#### Response
```json
{
"id": "contact_sqF12lZ1VlBb",
"deleted": true,
"object": "contact"
}
```
## Domain Types
### Contact
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Contact Create
- `ContactCreate`
- `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.
### Contact Create With Company Name
- `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.
### Contact Create With First Name
- `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.
### Contact Delete Response
- `class ContactDeleteResponse: …`
- `id: str`
A unique ID prefixed with contact_
- `deleted: Literal[true]`
- `true`
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
# Templates
## Create Template
`print_mail.templates.create(TemplateCreateParams**kwargs) -> Template`
**post** `/print-mail/v1/templates`
Create a template. Note that if you want to create a template that works with our template editor, you must use our dashboard.
### Parameters
- `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.
### Returns
- `class Template: …`
- `id: str`
A unique ID prefixed with template_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["template"]`
Always `template`.
- `"template"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
template = client.print_mail.templates.create(
description="Test",
html="Hello {{to.firstName}}",
)
print(template.id)
```
#### Response
```json
{
"id": "template_tBnVEzz878mXLbHQaz86j8",
"object": "template",
"live": false,
"description": "Test",
"html": "Hello {{to.firstName}}!",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z"
}
```
## List Templates
`print_mail.templates.list(TemplateListParams**kwargs) -> SyncSkipLimit[Template]`
**get** `/print-mail/v1/templates`
Get a list of templates.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class Template: …`
- `id: str`
A unique ID prefixed with template_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["template"]`
Always `template`.
- `"template"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.templates.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "template_tBnVEzz878mXLbHQaz86j8",
"object": "template",
"live": false,
"description": "Test",
"html": "Hello {{to.firstName}}!",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z"
}
]
}
```
## Get Template
`print_mail.templates.retrieve(strid) -> Template`
**get** `/print-mail/v1/templates/{id}`
Retrieve a template by ID.
### Parameters
- `id: str`
### Returns
- `class Template: …`
- `id: str`
A unique ID prefixed with template_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["template"]`
Always `template`.
- `"template"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
template = client.print_mail.templates.retrieve(
"id",
)
print(template.id)
```
#### Response
```json
{
"id": "template_tBnVEzz878mXLbHQaz86j8",
"object": "template",
"live": false,
"description": "Test",
"html": "Hello {{to.firstName}}!",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z"
}
```
## Update Template
`print_mail.templates.update(strid, TemplateUpdateParams**kwargs) -> Template`
**post** `/print-mail/v1/templates/{id}`
Update a template by ID.
### Parameters
- `id: str`
- `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.
### Returns
- `class Template: …`
- `id: str`
A unique ID prefixed with template_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["template"]`
Always `template`.
- `"template"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
template = client.print_mail.templates.update(
id="id",
description="Test",
html="Hello {{to.firstName}}!",
)
print(template.id)
```
#### Response
```json
{
"id": "template_tBnVEzz878mXLbHQaz86j8",
"object": "template",
"live": false,
"description": "Test",
"html": "Hello {{to.firstName}}!",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z"
}
```
## Delete Template
`print_mail.templates.delete(strid) -> TemplateDeleteResponse`
**delete** `/print-mail/v1/templates/{id}`
Delete a template by ID. Note that this operation cannot be undone.
### Parameters
- `id: str`
### Returns
- `class TemplateDeleteResponse: …`
- `id: str`
A unique ID prefixed with template_
- `deleted: Literal[true]`
- `true`
- `object: Literal["template"]`
Always `template`.
- `"template"`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
template = client.print_mail.templates.delete(
"id",
)
print(template.id)
```
#### Response
```json
{
"id": "template_sqF12lZ1VlBb",
"deleted": true,
"object": "template"
}
```
## Domain Types
### Template
- `class Template: …`
- `id: str`
A unique ID prefixed with template_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["template"]`
Always `template`.
- `"template"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Template Delete Response
- `class TemplateDeleteResponse: …`
- `id: str`
A unique ID prefixed with template_
- `deleted: Literal[true]`
- `true`
- `object: Literal["template"]`
Always `template`.
- `"template"`
# Trackers
## Create Tracker
`print_mail.trackers.create(TrackerCreateParams**kwargs) -> TrackerCreateResponse`
**post** `/print-mail/v1/trackers`
Create a Tracker.
### Parameters
- `redirect_url_template: str`
The base template for URLs generated by this Tracker.
- `url_expire_after_days: Literal[30, 60, 90, 2 more]`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `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.
### Returns
- `class TrackerCreateResponse: …`
- `id: str`
A unique ID prefixed with tracker_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["tracker"]`
Always `tracker`.
- `"tracker"`
- `redirect_url_template: str`
The base template for URLs generated by this Tracker.
- `unique_visit_count: int`
The unique number of interactions the Tracker has had.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `url_expire_after_days: Literal[30, 60, 90, 2 more]`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visit_count: int`
The total number of interactions the Tracker has had.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
tracker = client.print_mail.trackers.create(
redirect_url_template="https://postgrid.com?name={{to.firstName}}",
url_expire_after_days=30,
)
print(tracker.id)
```
#### Response
```json
{
"id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
"object": "tracker",
"live": false,
"redirectURLTemplate": "https://postgrid.com?name={{to.firstName}}",
"urlExpireAfterDays": 30,
"visitCount": 0,
"uniqueVisitCount": 0,
"createdAt": "2020-11-12T23:30:12.581Z",
"updatedAt": "2020-11-12T23:30:12.581Z"
}
```
## List Trackers
`print_mail.trackers.list(TrackerListParams**kwargs) -> SyncSkipLimit[TrackerListResponse]`
**get** `/print-mail/v1/trackers`
Retrieve a paginated list of Trackers.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class TrackerListResponse: …`
- `id: str`
A unique ID prefixed with tracker_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["tracker"]`
Always `tracker`.
- `"tracker"`
- `redirect_url_template: str`
The base template for URLs generated by this Tracker.
- `unique_visit_count: int`
The unique number of interactions the Tracker has had.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `url_expire_after_days: Literal[30, 60, 90, 2 more]`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visit_count: int`
The total number of interactions the Tracker has had.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.trackers.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
"object": "tracker",
"live": false,
"redirectURLTemplate": "https://postgrid.com?firstName={{to.firstName}}",
"urlExpireAfterDays": 90,
"visitCount": 0,
"uniqueVisitCount": 0,
"createdAt": "2020-11-12T23:30:12.581Z",
"updatedAt": "2020-11-12T23:31:12.581Z"
}
]
}
```
## Update Tracker
`print_mail.trackers.update(strid, TrackerUpdateParams**kwargs) -> TrackerUpdateResponse`
**post** `/print-mail/v1/trackers/{id}`
Update a Tracker by ID.
### Parameters
- `id: str`
- `redirect_url_template: str`
The base template for URLs generated by this Tracker.
- `url_expire_after_days: Literal[30, 60, 90, 2 more]`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `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.
### Returns
- `class TrackerUpdateResponse: …`
- `id: str`
A unique ID prefixed with tracker_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["tracker"]`
Always `tracker`.
- `"tracker"`
- `redirect_url_template: str`
The base template for URLs generated by this Tracker.
- `unique_visit_count: int`
The unique number of interactions the Tracker has had.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `url_expire_after_days: Literal[30, 60, 90, 2 more]`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visit_count: int`
The total number of interactions the Tracker has had.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
tracker = client.print_mail.trackers.update(
id="id",
redirect_url_template="https://postgrid.com?firstName={{to.firstName}}",
url_expire_after_days=90,
)
print(tracker.id)
```
#### Response
```json
{
"id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
"object": "tracker",
"live": false,
"redirectURLTemplate": "https://postgrid.com?firstName={{to.firstName}}",
"urlExpireAfterDays": 90,
"visitCount": 0,
"uniqueVisitCount": 0,
"createdAt": "2020-11-12T23:30:12.581Z",
"updatedAt": "2020-11-12T23:31:12.581Z"
}
```
## Get Tracker
`print_mail.trackers.retrieve(strid) -> TrackerRetrieveResponse`
**get** `/print-mail/v1/trackers/{id}`
Retrieve a Tracker by ID.
### Parameters
- `id: str`
### Returns
- `class TrackerRetrieveResponse: …`
- `id: str`
A unique ID prefixed with tracker_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["tracker"]`
Always `tracker`.
- `"tracker"`
- `redirect_url_template: str`
The base template for URLs generated by this Tracker.
- `unique_visit_count: int`
The unique number of interactions the Tracker has had.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `url_expire_after_days: Literal[30, 60, 90, 2 more]`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visit_count: int`
The total number of interactions the Tracker has had.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
tracker = client.print_mail.trackers.retrieve(
"id",
)
print(tracker.id)
```
#### Response
```json
{
"id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
"object": "tracker",
"live": false,
"redirectURLTemplate": "https://postgrid.com?firstName={{to.firstName}}",
"urlExpireAfterDays": 90,
"visitCount": 0,
"uniqueVisitCount": 0,
"createdAt": "2020-11-12T23:30:12.581Z",
"updatedAt": "2020-11-12T23:31:12.581Z"
}
```
## Delete Tracker
`print_mail.trackers.delete(strid) -> TrackerDeleteResponse`
**delete** `/print-mail/v1/trackers/{id}`
Delete a Tracker by ID. Note that this operation cannot be undone.
### Parameters
- `id: str`
### Returns
- `class TrackerDeleteResponse: …`
- `id: str`
A unique ID prefixed with tracker_
- `deleted: Literal[true]`
- `true`
- `object: Literal["tracker"]`
Always `tracker`.
- `"tracker"`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
tracker = client.print_mail.trackers.delete(
"id",
)
print(tracker.id)
```
#### Response
```json
{
"id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
"object": "tracker",
"deleted": true
}
```
## List Tracker Visits
`print_mail.trackers.retrieve_visits(strid, TrackerRetrieveVisitsParams**kwargs) -> SyncSkipLimit[TrackerRetrieveVisitsResponse]`
**get** `/print-mail/v1/trackers/{id}/visits`
Retrieve a paginated list of visits for a Tracker.
### Parameters
- `id: str`
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class TrackerRetrieveVisitsResponse: …`
- `id: str`
A unique ID prefixed with `tracker_visit_`.
- `created_at: datetime`
The UTC time at which this visit was created.
- `device: str`
The type of device associated with the visit.
- `ip_address: str`
The IP address associated with the visit.
- `live: bool`
Indicates if the visit was used in a live order or not.
- `object: Literal["tracker_visit"]`
Always `tracker_visit`.
- `"tracker_visit"`
- `order_id: str`
The ID of the order where the interaction occurred.
- `tracker: str`
The ID of the tracker related to this visit.
- `updated_at: datetime`
The UTC time at which this visit was last updated.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.trackers.retrieve_visits(
id="id",
)
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "tracker_visit_123456789abcdefghijklmnopqrstuvwxyz",
"object": "tracker_visit",
"live": false,
"tracker": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
"orderID": "order_123456789abcdefghijklmnopqrstuvwxyz",
"device": "Device Unknown",
"ipAddress": "Unknown IP Address",
"createdAt": "2020-11-12T23:30:12.581Z",
"updatedAt": "2020-11-12T23:31:12.581Z"
}
]
}
```
## Domain Types
### Tracker Create Response
- `class TrackerCreateResponse: …`
- `id: str`
A unique ID prefixed with tracker_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["tracker"]`
Always `tracker`.
- `"tracker"`
- `redirect_url_template: str`
The base template for URLs generated by this Tracker.
- `unique_visit_count: int`
The unique number of interactions the Tracker has had.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `url_expire_after_days: Literal[30, 60, 90, 2 more]`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visit_count: int`
The total number of interactions the Tracker has had.
- `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.
### Tracker List Response
- `class TrackerListResponse: …`
- `id: str`
A unique ID prefixed with tracker_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["tracker"]`
Always `tracker`.
- `"tracker"`
- `redirect_url_template: str`
The base template for URLs generated by this Tracker.
- `unique_visit_count: int`
The unique number of interactions the Tracker has had.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `url_expire_after_days: Literal[30, 60, 90, 2 more]`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visit_count: int`
The total number of interactions the Tracker has had.
- `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.
### Tracker Update Response
- `class TrackerUpdateResponse: …`
- `id: str`
A unique ID prefixed with tracker_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["tracker"]`
Always `tracker`.
- `"tracker"`
- `redirect_url_template: str`
The base template for URLs generated by this Tracker.
- `unique_visit_count: int`
The unique number of interactions the Tracker has had.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `url_expire_after_days: Literal[30, 60, 90, 2 more]`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visit_count: int`
The total number of interactions the Tracker has had.
- `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.
### Tracker Retrieve Response
- `class TrackerRetrieveResponse: …`
- `id: str`
A unique ID prefixed with tracker_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["tracker"]`
Always `tracker`.
- `"tracker"`
- `redirect_url_template: str`
The base template for URLs generated by this Tracker.
- `unique_visit_count: int`
The unique number of interactions the Tracker has had.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `url_expire_after_days: Literal[30, 60, 90, 2 more]`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visit_count: int`
The total number of interactions the Tracker has had.
- `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.
### Tracker Delete Response
- `class TrackerDeleteResponse: …`
- `id: str`
A unique ID prefixed with tracker_
- `deleted: Literal[true]`
- `true`
- `object: Literal["tracker"]`
Always `tracker`.
- `"tracker"`
### Tracker Retrieve Visits Response
- `class TrackerRetrieveVisitsResponse: …`
- `id: str`
A unique ID prefixed with `tracker_visit_`.
- `created_at: datetime`
The UTC time at which this visit was created.
- `device: str`
The type of device associated with the visit.
- `ip_address: str`
The IP address associated with the visit.
- `live: bool`
Indicates if the visit was used in a live order or not.
- `object: Literal["tracker_visit"]`
Always `tracker_visit`.
- `"tracker_visit"`
- `order_id: str`
The ID of the order where the interaction occurred.
- `tracker: str`
The ID of the tracker related to this visit.
- `updated_at: datetime`
The UTC time at which this visit was last updated.
# Letters
## Create Letter
`print_mail.letters.create(LetterCreateParams**kwargs) -> Letter`
**post** `/print-mail/v1/letters`
Create a letter. Note that you can supply one of the following:
- HTML content for the letter
- A template ID for the letter
- A URL or file for a PDF for the letter
- Upload the aforementioned PDF file via a multipart form upload request
### Parameters
- `from_: LetterCreateWithHTMLFrom`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `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.
- `str`
- `html: str`
The HTML content for the letter. You can supply _either_ this or `template` but not both.
- `to: LetterCreateWithHTMLTo`
The recipient of this order. You can either supply the contact information inline here or provide a contact ID. PostGrid will automatically deduplicate contacts regardless of whether you provide the information inline here or call the contact creation endpoint.
- `class ContactCreateWithFirstName: …`
- `class ContactCreateWithCompanyName: …`
- `str`
- `address_placement: Optional[AddressPlacement]`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attached_pdf: Optional[AttachedPdfParam]`
Model representing an attached PDF.
- `file: str`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: Optional[bool]`
Indicates if the letter is in color.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `double_sided: Optional[bool]`
Indicates if the letter is double-sided.
- `envelope: Optional[str]`
The envelope (ID) for the letter. You can either specify a custom envelope ID or use the default `standard` envelope.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
The mailing class of this order. If not provided, automatically set to `first_class`.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str]]`
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforated_page: Optional[Literal[1]]`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plastic_card: Optional[PlasticCardParam]`
Model representing a plastic card.
- `size: Literal["standard"]`
Enum representing the size of the plastic card.
- `"standard"`
- `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.
- `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.
- `template: Optional[str]`
The template ID for the single-sided plastic card.
- `return_envelope: Optional[str]`
The return envelope (ID) sent out with the letter, if any.
- `send_date: Optional[Union[str, datetime]]`
This order will transition from `ready` to `printing` on the day after this date. You can use this parameter to schedule orders for a future date.
- `size: Optional[LetterSize]`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
### Returns
- `class Letter: …`
- `id: str`
A unique ID prefixed with letter_
- `address_placement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"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.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"letter"`
- `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.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"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.
- `"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.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
- `1`
- `plastic_card: Optional[PlasticCard]`
Model representing a plastic card.
- `size: Literal["standard"]`
Enum representing the size of the plastic card.
- `"standard"`
- `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.
- `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.
- `template: Optional[str]`
The template ID for the single-sided plastic card.
- `return_envelope: Optional[str]`
The return envelope (ID) sent out with the letter, if any.
- `template: Optional[str]`
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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
letter = client.print_mail.letters.create(
from_="contact_123",
html="Content",
to="contact_123",
paper="standard",
)
print(letter.id)
```
#### Response
```json
{
"id": "letter_123456",
"object": "letter",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "us_letter",
"doubleSided": true,
"color": false,
"paper": "standard",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"envelope": "standard",
"addressPlacement": "top_first_page",
"html": "Content"
}
```
## List Letters
`print_mail.letters.list(LetterListParams**kwargs) -> SyncSkipLimit[Letter]`
**get** `/print-mail/v1/letters`
Get a list of letters.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class Letter: …`
- `id: str`
A unique ID prefixed with letter_
- `address_placement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"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.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"letter"`
- `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.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"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.
- `"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.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
- `1`
- `plastic_card: Optional[PlasticCard]`
Model representing a plastic card.
- `size: Literal["standard"]`
Enum representing the size of the plastic card.
- `"standard"`
- `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.
- `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.
- `template: Optional[str]`
The template ID for the single-sided plastic card.
- `return_envelope: Optional[str]`
The return envelope (ID) sent out with the letter, if any.
- `template: Optional[str]`
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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.letters.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "letter_123456",
"object": "letter",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "us_letter",
"doubleSided": true,
"color": false,
"paper": "standard",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"envelope": "standard",
"addressPlacement": "top_first_page",
"html": "Content"
}
]
}
```
## Get Letter
`print_mail.letters.retrieve(strid) -> Letter`
**get** `/print-mail/v1/letters/{id}`
Retrieve a letter by ID.
### Parameters
- `id: str`
### Returns
- `class Letter: …`
- `id: str`
A unique ID prefixed with letter_
- `address_placement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"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.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"letter"`
- `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.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"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.
- `"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.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
- `1`
- `plastic_card: Optional[PlasticCard]`
Model representing a plastic card.
- `size: Literal["standard"]`
Enum representing the size of the plastic card.
- `"standard"`
- `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.
- `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.
- `template: Optional[str]`
The template ID for the single-sided plastic card.
- `return_envelope: Optional[str]`
The return envelope (ID) sent out with the letter, if any.
- `template: Optional[str]`
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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
letter = client.print_mail.letters.retrieve(
"id",
)
print(letter.id)
```
#### Response
```json
{
"id": "letter_123456",
"object": "letter",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "us_letter",
"doubleSided": true,
"color": false,
"paper": "standard",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"envelope": "standard",
"addressPlacement": "top_first_page",
"html": "Content"
}
```
## Cancel Letter
`print_mail.letters.delete(strid) -> Letter`
**delete** `/print-mail/v1/letters/{id}`
Cancel a letter by ID. Note that this operation cannot be undone.
### Parameters
- `id: str`
### Returns
- `class Letter: …`
- `id: str`
A unique ID prefixed with letter_
- `address_placement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"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.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"letter"`
- `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.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"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.
- `"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.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
- `1`
- `plastic_card: Optional[PlasticCard]`
Model representing a plastic card.
- `size: Literal["standard"]`
Enum representing the size of the plastic card.
- `"standard"`
- `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.
- `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.
- `template: Optional[str]`
The template ID for the single-sided plastic card.
- `return_envelope: Optional[str]`
The return envelope (ID) sent out with the letter, if any.
- `template: Optional[str]`
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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
letter = client.print_mail.letters.delete(
"id",
)
print(letter.id)
```
#### Response
```json
{
"id": "letter_123456",
"object": "letter",
"status": "cancelled",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "us_letter",
"doubleSided": true,
"color": false,
"paper": "standard",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"envelope": "standard",
"addressPlacement": "top_first_page",
"html": "Content"
}
```
## Get Letter Preview
`print_mail.letters.retrieve_url(strid) -> LetterRetrieveURLResponse`
**get** `/print-mail/v1/letters/{id}/url`
Retrieve a letter preview URL.
This is only available for customers with our document management addon, which offers
document generation and hosting capabilities. This endpoint has a much higher rate limit
than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases.
### Parameters
- `id: str`
### Returns
- `class LetterRetrieveURLResponse: …`
- `id: str`
A unique ID prefixed with letter_
- `object: str`
- `url: str`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.letters.retrieve_url(
"id",
)
print(response.id)
```
#### Response
```json
{
"id": "letter_123456",
"object": "letter_url",
"url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/letter_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D"
}
```
## Cancel Letter With Note
`print_mail.letters.cancel(strid, LetterCancelParams**kwargs) -> Letter`
**post** `/print-mail/v1/letters/{id}/cancellation`
Cancel a letter by ID with a note. Note that this operation
cannot be undone and that only letters with a status of `ready` can be
cancelled.
### Parameters
- `id: str`
- `note: str`
### Returns
- `class Letter: …`
- `id: str`
A unique ID prefixed with letter_
- `address_placement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"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.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"letter"`
- `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.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"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.
- `"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.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
- `1`
- `plastic_card: Optional[PlasticCard]`
Model representing a plastic card.
- `size: Literal["standard"]`
Enum representing the size of the plastic card.
- `"standard"`
- `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.
- `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.
- `template: Optional[str]`
The template ID for the single-sided plastic card.
- `return_envelope: Optional[str]`
The return envelope (ID) sent out with the letter, if any.
- `template: Optional[str]`
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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
letter = client.print_mail.letters.cancel(
id="id",
note="Cancelling this letter",
)
print(letter.id)
```
#### Response
```json
{
"id": "letter_123456",
"object": "letter",
"status": "cancelled",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "us_letter",
"doubleSided": true,
"color": false,
"paper": "standard",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"envelope": "standard",
"addressPlacement": "top_first_page",
"html": "Content"
}
```
## Progress Status
`print_mail.letters.progress(strid) -> Letter`
**post** `/print-mail/v1/letters/{id}/progressions`
Progresses a letter's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
### Parameters
- `id: str`
### Returns
- `class Letter: …`
- `id: str`
A unique ID prefixed with letter_
- `address_placement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"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.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"letter"`
- `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.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"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.
- `"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.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
- `1`
- `plastic_card: Optional[PlasticCard]`
Model representing a plastic card.
- `size: Literal["standard"]`
Enum representing the size of the plastic card.
- `"standard"`
- `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.
- `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.
- `template: Optional[str]`
The template ID for the single-sided plastic card.
- `return_envelope: Optional[str]`
The return envelope (ID) sent out with the letter, if any.
- `template: Optional[str]`
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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
letter = client.print_mail.letters.progress(
"id",
)
print(letter.id)
```
#### Response
```json
{
"id": "letter_123456",
"object": "letter",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "us_letter",
"doubleSided": true,
"color": false,
"paper": "standard",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"envelope": "standard",
"addressPlacement": "top_first_page",
"html": "Content"
}
```
## Domain Types
### Address Placement
- `Literal["top_first_page", "insert_blank_page"]`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
### Attached Pdf
- `class AttachedPdf: …`
Model representing an attached PDF.
- `file: str`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
### Letter
- `class Letter: …`
- `id: str`
A unique ID prefixed with letter_
- `address_placement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"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.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"letter"`
- `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.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"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.
- `"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.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection used for this letter.
Available values include:
- `standard`
- `premium_paper_letter_standard_white_70lb`
- `premium_paper_letter_standard_white_80lb`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default letter paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
- `1`
- `plastic_card: Optional[PlasticCard]`
Model representing a plastic card.
- `size: Literal["standard"]`
Enum representing the size of the plastic card.
- `"standard"`
- `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.
- `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.
- `template: Optional[str]`
The template ID for the single-sided plastic card.
- `return_envelope: Optional[str]`
The return envelope (ID) sent out with the letter, if any.
- `template: Optional[str]`
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.
- `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.
### Letter Size
- `Literal["us_letter", "a4"]`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
### Plastic Card
- `class PlasticCard: …`
Model representing a plastic card.
- `size: Literal["standard"]`
Enum representing the size of the plastic card.
- `"standard"`
- `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.
- `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.
- `template: Optional[str]`
The template ID for the single-sided plastic card.
### Letter Retrieve URL Response
- `class LetterRetrieveURLResponse: …`
- `id: str`
A unique ID prefixed with letter_
- `object: str`
- `url: str`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
# Postcards
## Create Postcard
`print_mail.postcards.create(PostcardCreateParams**kwargs) -> Postcard`
**post** `/print-mail/v1/postcards`
Create a postcard. Note that you can supply one of the following:
- HTML content for the front and back of the postcard
- A template ID for the front and back of the postcard
- A URL or file for a 2 page PDF where the first page is the front of the postcard and the second page is the back
- Upload the aforementioned PDF file via a multipart form upload request
### Parameters
- `back_html: str`
The HTML content for the back of the postcard. You can supply _either_ this or `backTemplate` but not both.
- `front_html: str`
The HTML content for the front of the postcard. You can supply _either_ this or `frontTemplate` but not both.
- `size: Literal["6x4", "9x6", "11x6"]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `to: PostcardCreateWithHTMLTo`
The recipient of this order. You can either supply the contact information inline here or provide a contact ID. PostGrid will automatically deduplicate contacts regardless of whether you provide the information inline here or call the contact creation endpoint.
- `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.
- `str`
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from_: Optional[PostcardCreateWithHTMLFrom]`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`. Unlike other order types, the sender address is optional for postcards.
- `class ContactCreateWithFirstName: …`
- `class ContactCreateWithCompanyName: …`
- `str`
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
The mailing class of this order. If not provided, automatically set to `first_class`.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str]]`
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `send_date: Optional[Union[str, datetime]]`
This order will transition from `ready` to `printing` on the day after this date. You can use this parameter to schedule orders for a future date.
### Returns
- `class Postcard: …`
- `id: str`
A unique ID prefixed with postcard_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"postcard"`
- `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.
- `size: Literal["6x4", "9x6", "11x6"]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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.
- `"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.
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
postcard = client.print_mail.postcards.create(
back_html="Back",
front_html="Front",
size="6x4",
to="contact_456",
from_="contact_123",
paper="standard",
)
print(postcard.id)
```
#### Response
```json
{
"id": "postcard_123456",
"object": "postcard",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "6x4",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"paper": "standard"
}
```
## List Postcards
`print_mail.postcards.list(PostcardListParams**kwargs) -> SyncSkipLimit[Postcard]`
**get** `/print-mail/v1/postcards`
Get a list of postcards.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class Postcard: …`
- `id: str`
A unique ID prefixed with postcard_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"postcard"`
- `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.
- `size: Literal["6x4", "9x6", "11x6"]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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.
- `"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.
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.postcards.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "postcard_123456",
"object": "postcard",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "6x4",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"paper": "standard"
}
]
}
```
## Get Postcard
`print_mail.postcards.retrieve(strid) -> Postcard`
**get** `/print-mail/v1/postcards/{id}`
Retrieve a postcard by ID.
### Parameters
- `id: str`
### Returns
- `class Postcard: …`
- `id: str`
A unique ID prefixed with postcard_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"postcard"`
- `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.
- `size: Literal["6x4", "9x6", "11x6"]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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.
- `"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.
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
postcard = client.print_mail.postcards.retrieve(
"id",
)
print(postcard.id)
```
#### Response
```json
{
"id": "postcard_123456",
"object": "postcard",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "6x4",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"paper": "standard"
}
```
## Cancel Postcard
`print_mail.postcards.delete(strid) -> Postcard`
**delete** `/print-mail/v1/postcards/{id}`
Cancel a postcard by ID. Note that this operation cannot be undone.
### Parameters
- `id: str`
### Returns
- `class Postcard: …`
- `id: str`
A unique ID prefixed with postcard_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"postcard"`
- `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.
- `size: Literal["6x4", "9x6", "11x6"]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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.
- `"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.
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
postcard = client.print_mail.postcards.delete(
"id",
)
print(postcard.id)
```
#### Response
```json
{
"id": "postcard_123456",
"object": "postcard",
"status": "cancelled",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "6x4",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"paper": "standard"
}
```
## Get Postcard Preview
`print_mail.postcards.retrieve_url(strid) -> PostcardRetrieveURLResponse`
**get** `/print-mail/v1/postcards/{id}/url`
Retrieve a postcard preview URL.
This is only available for customers with our document management addon, which offers
document generation and hosting capabilities. This endpoint has a much higher rate limit
than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases.
### Parameters
- `id: str`
### Returns
- `class PostcardRetrieveURLResponse: …`
- `id: str`
A unique ID prefixed with postcard_
- `object: str`
- `url: str`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.postcards.retrieve_url(
"id",
)
print(response.id)
```
#### Response
```json
{
"id": "postcard_123456",
"object": "postcard_url",
"url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/postcard_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D"
}
```
## Cancel Postcard With Note
`print_mail.postcards.cancel(strid, PostcardCancelParams**kwargs) -> Postcard`
**post** `/print-mail/v1/postcards/{id}/cancellation`
Cancel a postcard by ID with a note. Note that this operation
cannot be undone and that only postcards with a status of `ready` can be
cancelled.
### Parameters
- `id: str`
- `note: str`
### Returns
- `class Postcard: …`
- `id: str`
A unique ID prefixed with postcard_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"postcard"`
- `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.
- `size: Literal["6x4", "9x6", "11x6"]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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.
- `"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.
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
postcard = client.print_mail.postcards.cancel(
id="id",
note="Cancelling this postcard",
)
print(postcard.id)
```
#### Response
```json
{
"id": "postcard_123456",
"object": "postcard",
"status": "cancelled",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "6x4",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"paper": "standard"
}
```
## Progress Status
`print_mail.postcards.progress(strid) -> Postcard`
**post** `/print-mail/v1/postcards/{id}/progressions`
Progresses a postcard's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
### Parameters
- `id: str`
### Returns
- `class Postcard: …`
- `id: str`
A unique ID prefixed with postcard_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"postcard"`
- `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.
- `size: Literal["6x4", "9x6", "11x6"]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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.
- `"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.
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
postcard = client.print_mail.postcards.progress(
"id",
)
print(postcard.id)
```
#### Response
```json
{
"id": "postcard_123456",
"object": "postcard",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "6x4",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"paper": "standard"
}
```
## Domain Types
### Postcard
- `class Postcard: …`
- `id: str`
A unique ID prefixed with postcard_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"postcard"`
- `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.
- `size: Literal["6x4", "9x6", "11x6"]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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.
- `"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.
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection used for this postcard.
Available values include:
- `standard`
- `premium_paper_heavy_1_glossy`
- `premium_paper_postcard_uv_glossy_ss`
- `premium_paper_postcard_uv_glossy_ss_120lb`
- `premium_paper_postcard_satin_ds`
Not all premium paper options are enabled for all organizations.
If omitted, the organization default postcard paper is used when configured; otherwise `standard`.
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `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.
### Postcard Retrieve URL Response
- `class PostcardRetrieveURLResponse: …`
- `id: str`
A unique ID prefixed with postcard_
- `object: str`
- `url: str`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
# Bank Accounts
## Create Bank Account
`print_mail.bank_accounts.create(BankAccountCreateParams**kwargs) -> BankAccount`
**post** `/print-mail/v1/bank_accounts`
Create a bank account. A US bank account is created by setting `bankCountryCode` to `US` and providing `accountNumber` and `routingNumber`. A canadian bank account can be created by specifying `bankCountryCode` as `CA` and setting `accountNumber`, `routeNumber`, and `transitNumber` accordingly.
You must specify _either_ `signatureImage` or `signatureText`. The image can be supplied as either a URL or a multipart file upload.
### Parameters
- `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.
- `"CA"`
- `"US"`
- `bank_name: str`
The name of the bank.
- `signature_text: str`
The signature text of the bank account.
- `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).
- `transit_number: Optional[str]`
The transit number of the bank account (for CA).
### Returns
- `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.
- `"CA"`
- `"US"`
- `bank_name: str`
The name of the bank.
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["bank_account"]`
Always `bank_account`.
- `"bank_account"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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).
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
bank_account = client.print_mail.bank_accounts.create(
account_number="1234567",
bank_country_code="US",
bank_name="Test Bank",
signature_text="Example",
bank_primary_line="145 mulberry st",
bank_secondary_line="new york ny 10013",
routing_number="123456789",
)
print(bank_account.id)
```
#### Response
```json
{
"id": "bank_account_12345",
"object": "bank_account",
"live": false,
"bankName": "Test Bank",
"bankPrimaryLine": "145 mulberry st",
"bankSecondaryLine": "new york ny 10013",
"bankCountryCode": "US",
"accountNumber": "1234567",
"routingNumber": "123456789",
"signatureText": "Signature",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z"
}
```
## List Bank Accounts
`print_mail.bank_accounts.list(BankAccountListParams**kwargs) -> SyncSkipLimit[BankAccount]`
**get** `/print-mail/v1/bank_accounts`
Get a list of bank accounts.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `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.
- `"CA"`
- `"US"`
- `bank_name: str`
The name of the bank.
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["bank_account"]`
Always `bank_account`.
- `"bank_account"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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).
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.bank_accounts.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "bank_account_12345",
"object": "bank_account",
"live": false,
"bankName": "Test Bank",
"bankPrimaryLine": "145 mulberry st",
"bankSecondaryLine": "new york ny 10013",
"bankCountryCode": "US",
"accountNumber": "1234567",
"routingNumber": "123456789",
"signatureText": "Signature",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z"
}
]
}
```
## Get Bank Account
`print_mail.bank_accounts.retrieve(strid) -> BankAccount`
**get** `/print-mail/v1/bank_accounts/{id}`
Retrieve a bank account by ID.
### Parameters
- `id: str`
### Returns
- `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.
- `"CA"`
- `"US"`
- `bank_name: str`
The name of the bank.
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["bank_account"]`
Always `bank_account`.
- `"bank_account"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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).
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
bank_account = client.print_mail.bank_accounts.retrieve(
"id",
)
print(bank_account.id)
```
#### Response
```json
{
"id": "bank_account_12345",
"object": "bank_account",
"live": false,
"bankName": "Test Bank",
"bankPrimaryLine": "145 mulberry st",
"bankSecondaryLine": "new york ny 10013",
"bankCountryCode": "US",
"accountNumber": "1234567",
"routingNumber": "123456789",
"signatureText": "Signature",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z"
}
```
## Delete Bank Account
`print_mail.bank_accounts.delete(strid) -> BankAccountDeleteResponse`
**delete** `/print-mail/v1/bank_accounts/{id}`
Delete a bank account by ID. Note that this operation cannot be undone.
### Parameters
- `id: str`
### Returns
- `class BankAccountDeleteResponse: …`
- `id: str`
A unique ID prefixed with bank_account_
- `deleted: Literal[true]`
- `true`
- `object: Literal["bank_account"]`
Always `bank_account`.
- `"bank_account"`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
bank_account = client.print_mail.bank_accounts.delete(
"id",
)
print(bank_account.id)
```
#### Response
```json
{
"id": "bank_account_sqF12lZ1VlBb",
"deleted": true,
"object": "bank_account"
}
```
## Domain Types
### Bank Account
- `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.
- `"CA"`
- `"US"`
- `bank_name: str`
The name of the bank.
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["bank_account"]`
Always `bank_account`.
- `"bank_account"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `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).
### Bank Account Country Code
- `Literal["CA", "US"]`
Countries typically have different bank account formats and standards. These are the countries
which PostGrid's bank accounts API supports.
- `"CA"`
- `"US"`
### Bank Account Delete Response
- `class BankAccountDeleteResponse: …`
- `id: str`
A unique ID prefixed with bank_account_
- `deleted: Literal[true]`
- `true`
- `object: Literal["bank_account"]`
Always `bank_account`.
- `"bank_account"`
# Cheques
## Create Cheque
`print_mail.cheques.create(ChequeCreateParams**kwargs) -> Cheque`
**post** `/print-mail/v1/cheques`
Create a cheque.
This endpoint allows you to create a new cheque with the specified details.
If you would like to create a digitalOnly cheque, the digitalOnly object with the watermark
will need to be passed in. Feature is available on request, e-mail support@postgrid.com for access.
Example request body:
```json
{
"from": "contact_123",
"bankAccount": "bank_123",
"amount": 1000,
"currencyCode": "USD",
"number": 123456,
"size": "us_letter",
"digitalOnly": {
"watermark": "VOID"
}
}
```
### Parameters
- `amount: int`
The amount of the cheque in cents.
- `bank_account: str`
The bank account (ID) associated with the cheque.
- `from_: From`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `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.
- `str`
- `to: To`
The recipient of this order. You can either supply the contact information inline here or provide a contact ID. PostGrid will automatically deduplicate contacts regardless of whether you provide the information inline here or call the contact creation endpoint.
- `class ContactCreateWithFirstName: …`
- `class ContactCreateWithCompanyName: …`
- `str`
- `currency_code: Optional[Literal["USD", "CAD"]]`
The currency code of the cheque. This will be set to the default currency of the bank account (`USD` for US bank accounts and `CAD` for Canadian bank accounts) if not provided. You can set this value to `USD` if you want to draw USD from a Canadian bank account or vice versa.
- `"USD"`
- `"CAD"`
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `digital_only: Optional[DigitalOnlyParam]`
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]]`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `Literal["standard"]`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `str`
- `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).
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
The mailing class of this order. If not provided, automatically set to `first_class`.
- `"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]`
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.
- `redirect_to: Optional[RedirectTo]`
Providing this inserts a blank page at the start of the cheque with the recipient you provide here. This leaves the cheque that follows intact, which means you can use this to intercept at cheque at the redirected address and then mail it forward to the final recipient yourself. One use case for this is signing cheques at your office before mailing them out yourself.
- `class ContactCreateWithFirstName: …`
- `class ContactCreateWithCompanyName: …`
- `str`
- `send_date: Optional[Union[str, datetime]]`
This order will transition from `ready` to `printing` on the day after this date. You can use this parameter to schedule orders for a future date.
- `size: Optional[ChequeSize]`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
### Returns
- `class Cheque: …`
- `id: str`
A unique ID prefixed with cheque_
- `amount: int`
The amount of the cheque in cents.
- `bank_account: str`
The bank account (ID) associated with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"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.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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`.
- `Literal["standard"]`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `str`
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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).
- `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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
cheque = client.print_mail.cheques.create(
amount=1000,
bank_account="bank_123",
from_="contact_123",
to="contact_123",
currency_code="USD",
number=123456,
size="us_letter",
)
print(cheque.id)
```
#### Response
```json
{
"id": "cheque_123456",
"object": "cheque",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 1000,
"currencyCode": "USD",
"number": 123456,
"size": "us_letter",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
```
## List Cheques
`print_mail.cheques.list(ChequeListParams**kwargs) -> SyncSkipLimit[Cheque]`
**get** `/print-mail/v1/cheques`
Get a list of cheques.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class Cheque: …`
- `id: str`
A unique ID prefixed with cheque_
- `amount: int`
The amount of the cheque in cents.
- `bank_account: str`
The bank account (ID) associated with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"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.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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`.
- `Literal["standard"]`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `str`
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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).
- `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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.cheques.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "cheque_123456",
"object": "cheque",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 1000,
"currencyCode": "USD",
"number": 123456,
"size": "us_letter",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
]
}
```
## Get Cheque
`print_mail.cheques.retrieve(strid) -> Cheque`
**get** `/print-mail/v1/cheques/{id}`
Retrieve a cheque by ID.
### Parameters
- `id: str`
### Returns
- `class Cheque: …`
- `id: str`
A unique ID prefixed with cheque_
- `amount: int`
The amount of the cheque in cents.
- `bank_account: str`
The bank account (ID) associated with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"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.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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`.
- `Literal["standard"]`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `str`
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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).
- `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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
cheque = client.print_mail.cheques.retrieve(
"id",
)
print(cheque.id)
```
#### Response
```json
{
"id": "cheque_123456",
"object": "cheque",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 1000,
"currencyCode": "USD",
"number": 123456,
"size": "us_letter",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
```
## Cancel Cheque
`print_mail.cheques.delete(strid) -> Cheque`
**delete** `/print-mail/v1/cheques/{id}`
Cancel a cheque by ID. Note that this operation cannot be undone.
### Parameters
- `id: str`
### Returns
- `class Cheque: …`
- `id: str`
A unique ID prefixed with cheque_
- `amount: int`
The amount of the cheque in cents.
- `bank_account: str`
The bank account (ID) associated with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"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.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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`.
- `Literal["standard"]`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `str`
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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).
- `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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
cheque = client.print_mail.cheques.delete(
"id",
)
print(cheque.id)
```
#### Response
```json
{
"id": "cheque_123456",
"object": "cheque",
"status": "cancelled",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 1000,
"currencyCode": "USD",
"number": 123456,
"size": "us_letter",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
```
## Get Cheque Preview
`print_mail.cheques.retrieve_url(strid) -> ChequeRetrieveURLResponse`
**get** `/print-mail/v1/cheques/{id}/url`
Retrieve a cheque preview URL.
This is only available for customers with our document management addon, which offers
document generation and hosting capabilities. This endpoint has a much higher rate limit
than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases.
### Parameters
- `id: str`
### Returns
- `class ChequeRetrieveURLResponse: …`
- `id: str`
A unique ID prefixed with cheque_
- `object: str`
- `url: str`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.cheques.retrieve_url(
"id",
)
print(response.id)
```
#### Response
```json
{
"id": "cheque_123456",
"object": "cheque_url",
"url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/cheque_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D"
}
```
## Retrieve Cheque Deposit-Ready PDF (Digital Only)
`print_mail.cheques.retrieve_with_deposit_ready_pdf(strid) -> Cheque`
**get** `/print-mail/v1/cheques/{id}/with_deposit_ready_pdf`
Retrieve the deposit-ready PDF for a digital-only cheque. The endpoint can only be called by users with 'Admin' role.
In test mode, the preview PDF of the digitalOnly cheque and the deposit-ready PDF are the same.
In live mode, the deposit-ready will have the full account number.
### Parameters
- `id: str`
### Returns
- `class Cheque: …`
- `id: str`
A unique ID prefixed with cheque_
- `amount: int`
The amount of the cheque in cents.
- `bank_account: str`
The bank account (ID) associated with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"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.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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`.
- `Literal["standard"]`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `str`
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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).
- `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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
cheque = client.print_mail.cheques.retrieve_with_deposit_ready_pdf(
"id",
)
print(cheque.id)
```
#### Response
```json
{
"id": "cheque_123456",
"object": "cheque",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 1000,
"currencyCode": "USD",
"number": 123456,
"size": "us_letter",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class",
"digitalOnly": {
"watermark": "TEST"
},
"depositReadyPDFURL": "https://example.s3.amazonaws.com/deposit_ready.pdf"
}
```
## Cancel Cheque With Note
`print_mail.cheques.cancel(strid, ChequeCancelParams**kwargs) -> Cheque`
**post** `/print-mail/v1/cheques/{id}/cancellation`
Cancel a cheque by ID with a note. Note that this operation
cannot be undone and that only cheques with a status of `ready` can be
cancelled.
### Parameters
- `id: str`
- `note: str`
### Returns
- `class Cheque: …`
- `id: str`
A unique ID prefixed with cheque_
- `amount: int`
The amount of the cheque in cents.
- `bank_account: str`
The bank account (ID) associated with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"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.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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`.
- `Literal["standard"]`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `str`
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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).
- `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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
cheque = client.print_mail.cheques.cancel(
id="id",
note="Cancelling this cheque",
)
print(cheque.id)
```
#### Response
```json
{
"id": "cheque_123456",
"object": "cheque",
"status": "cancelled",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 1000,
"currencyCode": "USD",
"number": 123456,
"size": "us_letter",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
```
## Progress Status
`print_mail.cheques.progress(strid) -> Cheque`
**post** `/print-mail/v1/cheques/{id}/progressions`
Progresses a cheque's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
### Parameters
- `id: str`
### Returns
- `class Cheque: …`
- `id: str`
A unique ID prefixed with cheque_
- `amount: int`
The amount of the cheque in cents.
- `bank_account: str`
The bank account (ID) associated with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"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.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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`.
- `Literal["standard"]`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `str`
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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).
- `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.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
cheque = client.print_mail.cheques.progress(
"id",
)
print(cheque.id)
```
#### Response
```json
{
"id": "cheque_123456",
"object": "cheque",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 1000,
"currencyCode": "USD",
"number": 123456,
"size": "us_letter",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
```
## Domain Types
### Cheque
- `class Cheque: …`
- `id: str`
A unique ID prefixed with cheque_
- `amount: int`
The amount of the cheque in cents.
- `bank_account: str`
The bank account (ID) associated with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `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.
- `"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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"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.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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`.
- `Literal["standard"]`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `str`
- `imb_date: Optional[datetime]`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `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.
- `"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).
- `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.
- `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.
### Cheque Size
- `Literal["us_letter", "us_legal"]`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
### Digital Only
- `class DigitalOnly: …`
- `watermark: str`
Text to be displayed as a watermark on the digital cheque.
### Cheque Retrieve URL Response
- `class ChequeRetrieveURLResponse: …`
- `id: str`
A unique ID prefixed with cheque_
- `object: str`
- `url: str`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
# Self Mailers
## Create Self Mailer
`print_mail.self_mailers.create(SelfMailerCreateParams**kwargs) -> SelfMailer`
**post** `/print-mail/v1/self_mailers`
Create a self-mailer. Note that you can supply one of the following:
- HTML content for the inside and outside of the self-mailer
- A template ID for the inside and outside of the self-mailer
- A URL or file for a 2 page PDF where the first page is the outside of the self-mailer and the second page is the inside
- Upload the aforementioned PDF file via a multipart form upload request
### Parameters
- `from_: SelfMailerCreateWithHTMLFrom`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `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.
- `str`
- `inside_html: str`
The HTML content for the inside of the self-mailer. You can supply _either_ this or `insideTemplate` but not both.
- `outside_html: str`
The HTML content for the outside of the self-mailer. You can supply _either_ this or `outsideTemplate` but not both.
- `size: Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `to: SelfMailerCreateWithHTMLTo`
The recipient of this order. You can either supply the contact information inline here or provide a contact ID. PostGrid will automatically deduplicate contacts regardless of whether you provide the information inline here or call the contact creation endpoint.
- `class ContactCreateWithFirstName: …`
- `class ContactCreateWithCompanyName: …`
- `str`
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
The mailing class of this order. If not provided, automatically set to `first_class`.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `send_date: Optional[Union[str, datetime]]`
This order will transition from `ready` to `printing` on the day after this date. You can use this parameter to schedule orders for a future date.
### Returns
- `class SelfMailer: …`
- `id: str`
A unique ID prefixed with self_mailer_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"self_mailer"`
- `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.
- `size: Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]`
Enum representing the supported self-mailer sizes.
- `"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.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
self_mailer = client.print_mail.self_mailers.create(
from_="contact_123",
inside_html="Inside",
outside_html="Outside",
size="8.5x11_bifold",
to="contact_456",
)
print(self_mailer.id)
```
#### Response
```json
{
"id": "self_mailer_123456",
"object": "self_mailer",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "8.5x11_bifold",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
```
## List Self Mailers
`print_mail.self_mailers.list(SelfMailerListParams**kwargs) -> SyncSkipLimit[SelfMailer]`
**get** `/print-mail/v1/self_mailers`
Get a list of self-mailers.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class SelfMailer: …`
- `id: str`
A unique ID prefixed with self_mailer_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"self_mailer"`
- `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.
- `size: Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]`
Enum representing the supported self-mailer sizes.
- `"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.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.self_mailers.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "self_mailer_123456",
"object": "self_mailer",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "8.5x11_bifold",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
]
}
```
## Get Self Mailer
`print_mail.self_mailers.retrieve(strid) -> SelfMailer`
**get** `/print-mail/v1/self_mailers/{id}`
Retrieve a self-mailer by ID.
### Parameters
- `id: str`
### Returns
- `class SelfMailer: …`
- `id: str`
A unique ID prefixed with self_mailer_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"self_mailer"`
- `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.
- `size: Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]`
Enum representing the supported self-mailer sizes.
- `"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.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
self_mailer = client.print_mail.self_mailers.retrieve(
"id",
)
print(self_mailer.id)
```
#### Response
```json
{
"id": "self_mailer_123456",
"object": "self_mailer",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "8.5x11_bifold",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
```
## Cancel Self Mailer
`print_mail.self_mailers.delete(strid) -> SelfMailer`
**delete** `/print-mail/v1/self_mailers/{id}`
Cancel a self-mailer by ID. Note that this operation cannot be undone.
### Parameters
- `id: str`
### Returns
- `class SelfMailer: …`
- `id: str`
A unique ID prefixed with self_mailer_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"self_mailer"`
- `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.
- `size: Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]`
Enum representing the supported self-mailer sizes.
- `"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.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
self_mailer = client.print_mail.self_mailers.delete(
"id",
)
print(self_mailer.id)
```
#### Response
```json
{
"id": "self_mailer_123456",
"object": "self_mailer",
"status": "cancelled",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "8.5x11_bifold",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
```
## Get Self Mailer Preview
`print_mail.self_mailers.retrieve_url(strid) -> SelfMailerRetrieveURLResponse`
**get** `/print-mail/v1/self_mailers/{id}/url`
Retrieve a self-mailer preview URL.
This is only available for customers with our document management addon, which offers
document generation and hosting capabilities. This endpoint has a much higher rate limit
than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases.
### Parameters
- `id: str`
### Returns
- `class SelfMailerRetrieveURLResponse: …`
- `id: str`
A unique ID prefixed with self_mailer_
- `object: str`
- `url: str`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.self_mailers.retrieve_url(
"id",
)
print(response.id)
```
#### Response
```json
{
"id": "self_mailer_123456",
"object": "self_mailer_url",
"url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/self_mailer_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D"
}
```
## Progress Status
`print_mail.self_mailers.progress(strid) -> SelfMailer`
**post** `/print-mail/v1/self_mailers/{id}/progressions`
Progresses a self-mailer's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
### Parameters
- `id: str`
### Returns
- `class SelfMailer: …`
- `id: str`
A unique ID prefixed with self_mailer_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"self_mailer"`
- `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.
- `size: Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]`
Enum representing the supported self-mailer sizes.
- `"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.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
self_mailer = client.print_mail.self_mailers.progress(
"id",
)
print(self_mailer.id)
```
#### Response
```json
{
"id": "self_mailer_123456",
"object": "self_mailer",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "8.5x11_bifold",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "first_class"
}
```
## Domain Types
### Self Mailer
- `class SelfMailer: …`
- `id: str`
A unique ID prefixed with self_mailer_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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`.
- `"self_mailer"`
- `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.
- `size: Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]`
Enum representing the supported self-mailer sizes.
- `"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.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Self Mailer Retrieve URL Response
- `class SelfMailerRetrieveURLResponse: …`
- `id: str`
A unique ID prefixed with self_mailer_
- `object: str`
- `url: str`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
# Campaigns
## Create Campaign
`print_mail.campaigns.create(CampaignCreateParams**kwargs) -> Campaign`
**post** `/print-mail/v1/campaigns`
Create a new campaign.
A campaign links a mailing list with a specific mail piece configuration (letter, postcard, cheque, self-mailer, or snap pack)
to send bulk mail. Only one collateral type can be set per campaign.
Upon creation, the campaign enters the `drafting` status while assets are validated.
### Parameters
- `mailing_list: str`
The ID of the mailing list associated with this campaign.
- `cheque: Optional[Cheque]`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bank_account: Optional[str]`
ID of the bank account to use for the cheque.
- `currency_code: Optional[Literal["CAD", "USD"]]`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: Optional[str]`
An optional description.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `letter_pdf: Optional[Union[str, Base64FileInput]]`
PDF file for an optional attached letter. Cannot be used with `letterTemplate`.
- `letter_settings: Optional[ChequeLetterSettings]`
Settings for the attached letter (e.g., color printing).
- `color: Optional[bool]`
Whether to print the attached letter in color.
- `letter_template: Optional[str]`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `logo: Optional[str]`
A publicly accessible URL for the logo to print on the cheque.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the cheque.
- `"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.
- `merge_variables: Optional[Dict[str, object]]`
Default merge variables for the cheque.
- `message: Optional[str]`
Message included on the cheque stub.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[ChequeSize]`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `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.
- `letter: Optional[Letter]`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `address_placement: Optional[AddressPlacement]`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attached_pdf: Optional[AttachedPdfParam]`
Model representing an attached PDF.
- `file: str`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: Optional[bool]`
Whether to print in color.
- `description: Optional[str]`
An optional description.
- `double_sided: Optional[bool]`
Whether to print on both sides of the paper.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `envelope_type: Optional[Literal["standard_double_window", "flat"]]`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the letter.
- `"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 the letter.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdf: Optional[str]`
A PDF file or URL for the letter content. Cannot be used with `template`.
- `perforated_page: Optional[Literal[1]]`
Which page number should be perforated (if any).
- `1`
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[LetterSize]`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: Optional[str]`
ID of a template for the letter content. Cannot be used with `pdf`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `postcard: Optional[Postcard]`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `back_template: Optional[str]`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: Optional[str]`
An optional description.
- `front_template: Optional[str]`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the postcard.
- `"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 the postcard.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdf: Optional[str]`
A 2-page PDF file for the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`.
- `size: Optional[Literal["6x4", "9x6", "11x6"]]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `self_mailer: Optional[SelfMailer]`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the self-mailer.
- `"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 the self-mailer.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `pdf: Optional[str]`
A 2-page PDF file for the self-mailer content. Cannot be used with `insideTemplate`/`outsideTemplate`.
- `size: Optional[Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]]`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `send_date: Optional[Union[str, datetime]]`
The scheduled date and time for the campaign to be sent.
- `snap_pack: Optional[SnapPack]`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the snap pack.
- `"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 the snap pack.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `pdf: Optional[str]`
A 2-page PDF file for the snap pack content. Cannot be used with `insideTemplate`/`outsideTemplate`.
- `size: Optional[Literal["8.5x11_bifold_v"]]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `idempotency_key: Optional[str]`
### Returns
- `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.
- `created_count: int`
The number of orders successfully created for this campaign.
- `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.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `cheque: Optional[Cheque]`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bank_account: Optional[str]`
ID of the bank account to use for the cheque.
- `currency_code: Optional[Literal["CAD", "USD"]]`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: Optional[str]`
An optional description.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `letter_settings: Optional[ChequeLetterSettings]`
Settings for the attached letter (e.g., color printing).
- `color: Optional[bool]`
Whether to print the attached letter in color.
- `letter_template: Optional[str]`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letter_uploaded_pdf: Optional[str]`
A signed URL to the attached letter PDF, if any.
- `logo: Optional[str]`
A publicly accessible URL for the logo to print on the cheque.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the cheque.
- `"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.
- `merge_variables: Optional[Dict[str, object]]`
Default merge variables for the cheque.
- `message: Optional[str]`
Message included on the cheque stub.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[ChequeSize]`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `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.
- `"processing_error"`
- `"internal_error"`
- `letter: Optional[Letter]`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `address_placement: Optional[AddressPlacement]`
Enum representing the placement of the address on the letter.
- `"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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: Optional[bool]`
Whether to print in color.
- `description: Optional[str]`
An optional description.
- `double_sided: Optional[bool]`
Whether to print on both sides of the paper.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `envelope_type: Optional[Literal["standard_double_window", "flat"]]`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the letter.
- `"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 the letter.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforated_page: Optional[Literal[1]]`
Which page number should be perforated (if any).
- `1`
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[LetterSize]`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: Optional[str]`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `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.
- `postcard: Optional[Postcard]`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `back_template: Optional[str]`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: Optional[str]`
An optional description.
- `front_template: Optional[str]`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the postcard.
- `"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 the postcard.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `size: Optional[Literal["6x4", "9x6", "11x6"]]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `report_url: Optional[str]`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `self_mailer: Optional[SelfMailer]`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the self-mailer.
- `"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 the self-mailer.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]]`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `send_date: Optional[datetime]`
The scheduled date and time for the campaign to be sent.
- `snap_pack: Optional[SnapPack]`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the snap pack.
- `"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 the snap pack.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold_v"]]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
campaign = client.print_mail.campaigns.create(
mailing_list="mailingList",
)
print(campaign.id)
```
#### Response
```json
{
"id": "campaign_sqF12lZ1VlBb",
"createdAt": "2019-12-27T18:11:19.117Z",
"createdCount": 0,
"live": true,
"mailingList": "mailingList",
"status": "drafting",
"updatedAt": "2019-12-27T18:11:19.117Z",
"cheque": {
"bankAccount": "bankAccount",
"currencyCode": "CAD",
"description": "description",
"envelope": "envelope",
"letterSettings": {
"color": true
},
"letterTemplate": "letterTemplate",
"letterUploadedPDF": "https://example.com",
"logo": "https://example.com",
"mailingClass": "first_class",
"memo": "memo",
"mergeVariables": {
"foo": "bar"
},
"message": "message",
"metadata": {
"foo": "string"
},
"returnEnvelope": "returnEnvelope",
"size": "us_letter"
},
"defaultSenderContact": "defaultSenderContact",
"description": "description",
"errors": [
{
"message": "message",
"type": "processing_error"
}
],
"letter": {
"addressPlacement": "top_first_page",
"attachedPDF": {
"file": "https://example.com",
"placement": "before_template"
},
"color": true,
"description": "description",
"doubleSided": true,
"envelope": "envelope",
"envelopeType": "standard_double_window",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"paper": "standard",
"perforatedPage": 1,
"returnEnvelope": "returnEnvelope",
"size": "us_letter",
"template": "template",
"uploadedPDF": "https://example.com"
},
"metadata": {
"foo": "bar"
},
"orderPreviewURL": "https://example.com",
"postcard": {
"backTemplate": "backTemplate",
"description": "description",
"frontTemplate": "frontTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"paper": "standard",
"size": "6x4",
"uploadedPDF": "https://example.com"
},
"reportURL": "https://example.com",
"selfMailer": {
"description": "description",
"insideTemplate": "insideTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"outsideTemplate": "outsideTemplate",
"size": "8.5x11_bifold",
"uploadedPDF": "https://example.com"
},
"sendDate": "2019-12-27T18:11:19.117Z",
"snapPack": {
"description": "description",
"insideTemplate": "insideTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"outsideTemplate": "outsideTemplate",
"size": "8.5x11_bifold_v",
"uploadedPDF": "https://example.com"
}
}
```
## List Campaigns
`print_mail.campaigns.list(CampaignListParams**kwargs) -> SyncSkipLimit[Campaign]`
**get** `/print-mail/v1/campaigns`
Retrieve a list of campaigns.
Returns a paginated list of campaigns associated with the authenticated organization,
filterable by various parameters.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `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.
- `created_count: int`
The number of orders successfully created for this campaign.
- `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.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `cheque: Optional[Cheque]`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bank_account: Optional[str]`
ID of the bank account to use for the cheque.
- `currency_code: Optional[Literal["CAD", "USD"]]`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: Optional[str]`
An optional description.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `letter_settings: Optional[ChequeLetterSettings]`
Settings for the attached letter (e.g., color printing).
- `color: Optional[bool]`
Whether to print the attached letter in color.
- `letter_template: Optional[str]`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letter_uploaded_pdf: Optional[str]`
A signed URL to the attached letter PDF, if any.
- `logo: Optional[str]`
A publicly accessible URL for the logo to print on the cheque.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the cheque.
- `"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.
- `merge_variables: Optional[Dict[str, object]]`
Default merge variables for the cheque.
- `message: Optional[str]`
Message included on the cheque stub.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[ChequeSize]`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `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.
- `"processing_error"`
- `"internal_error"`
- `letter: Optional[Letter]`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `address_placement: Optional[AddressPlacement]`
Enum representing the placement of the address on the letter.
- `"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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: Optional[bool]`
Whether to print in color.
- `description: Optional[str]`
An optional description.
- `double_sided: Optional[bool]`
Whether to print on both sides of the paper.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `envelope_type: Optional[Literal["standard_double_window", "flat"]]`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the letter.
- `"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 the letter.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforated_page: Optional[Literal[1]]`
Which page number should be perforated (if any).
- `1`
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[LetterSize]`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: Optional[str]`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `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.
- `postcard: Optional[Postcard]`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `back_template: Optional[str]`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: Optional[str]`
An optional description.
- `front_template: Optional[str]`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the postcard.
- `"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 the postcard.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `size: Optional[Literal["6x4", "9x6", "11x6"]]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `report_url: Optional[str]`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `self_mailer: Optional[SelfMailer]`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the self-mailer.
- `"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 the self-mailer.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]]`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `send_date: Optional[datetime]`
The scheduled date and time for the campaign to be sent.
- `snap_pack: Optional[SnapPack]`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the snap pack.
- `"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 the snap pack.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold_v"]]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.campaigns.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"data": [
{
"id": "campaign_sqF12lZ1VlBb",
"createdAt": "2019-12-27T18:11:19.117Z",
"createdCount": 0,
"live": true,
"mailingList": "mailingList",
"status": "drafting",
"updatedAt": "2019-12-27T18:11:19.117Z",
"cheque": {
"bankAccount": "bankAccount",
"currencyCode": "CAD",
"description": "description",
"envelope": "envelope",
"letterSettings": {
"color": true
},
"letterTemplate": "letterTemplate",
"letterUploadedPDF": "https://example.com",
"logo": "https://example.com",
"mailingClass": "first_class",
"memo": "memo",
"mergeVariables": {
"foo": "bar"
},
"message": "message",
"metadata": {
"foo": "string"
},
"returnEnvelope": "returnEnvelope",
"size": "us_letter"
},
"defaultSenderContact": "defaultSenderContact",
"description": "description",
"errors": [
{
"message": "message",
"type": "processing_error"
}
],
"letter": {
"addressPlacement": "top_first_page",
"attachedPDF": {
"file": "https://example.com",
"placement": "before_template"
},
"color": true,
"description": "description",
"doubleSided": true,
"envelope": "envelope",
"envelopeType": "standard_double_window",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"paper": "standard",
"perforatedPage": 1,
"returnEnvelope": "returnEnvelope",
"size": "us_letter",
"template": "template",
"uploadedPDF": "https://example.com"
},
"metadata": {
"foo": "bar"
},
"orderPreviewURL": "https://example.com",
"postcard": {
"backTemplate": "backTemplate",
"description": "description",
"frontTemplate": "frontTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"paper": "standard",
"size": "6x4",
"uploadedPDF": "https://example.com"
},
"reportURL": "https://example.com",
"selfMailer": {
"description": "description",
"insideTemplate": "insideTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"outsideTemplate": "outsideTemplate",
"size": "8.5x11_bifold",
"uploadedPDF": "https://example.com"
},
"sendDate": "2019-12-27T18:11:19.117Z",
"snapPack": {
"description": "description",
"insideTemplate": "insideTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"outsideTemplate": "outsideTemplate",
"size": "8.5x11_bifold_v",
"uploadedPDF": "https://example.com"
}
}
],
"limit": 0,
"object": "list",
"skip": 0,
"totalCount": 0
}
```
## Get Campaign
`print_mail.campaigns.retrieve(strid) -> Campaign`
**get** `/print-mail/v1/campaigns/{id}`
Retrieve a specific campaign by its ID.
### Parameters
- `id: str`
### Returns
- `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.
- `created_count: int`
The number of orders successfully created for this campaign.
- `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.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `cheque: Optional[Cheque]`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bank_account: Optional[str]`
ID of the bank account to use for the cheque.
- `currency_code: Optional[Literal["CAD", "USD"]]`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: Optional[str]`
An optional description.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `letter_settings: Optional[ChequeLetterSettings]`
Settings for the attached letter (e.g., color printing).
- `color: Optional[bool]`
Whether to print the attached letter in color.
- `letter_template: Optional[str]`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letter_uploaded_pdf: Optional[str]`
A signed URL to the attached letter PDF, if any.
- `logo: Optional[str]`
A publicly accessible URL for the logo to print on the cheque.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the cheque.
- `"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.
- `merge_variables: Optional[Dict[str, object]]`
Default merge variables for the cheque.
- `message: Optional[str]`
Message included on the cheque stub.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[ChequeSize]`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `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.
- `"processing_error"`
- `"internal_error"`
- `letter: Optional[Letter]`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `address_placement: Optional[AddressPlacement]`
Enum representing the placement of the address on the letter.
- `"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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: Optional[bool]`
Whether to print in color.
- `description: Optional[str]`
An optional description.
- `double_sided: Optional[bool]`
Whether to print on both sides of the paper.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `envelope_type: Optional[Literal["standard_double_window", "flat"]]`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the letter.
- `"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 the letter.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforated_page: Optional[Literal[1]]`
Which page number should be perforated (if any).
- `1`
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[LetterSize]`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: Optional[str]`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `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.
- `postcard: Optional[Postcard]`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `back_template: Optional[str]`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: Optional[str]`
An optional description.
- `front_template: Optional[str]`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the postcard.
- `"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 the postcard.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `size: Optional[Literal["6x4", "9x6", "11x6"]]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `report_url: Optional[str]`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `self_mailer: Optional[SelfMailer]`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the self-mailer.
- `"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 the self-mailer.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]]`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `send_date: Optional[datetime]`
The scheduled date and time for the campaign to be sent.
- `snap_pack: Optional[SnapPack]`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the snap pack.
- `"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 the snap pack.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold_v"]]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
campaign = client.print_mail.campaigns.retrieve(
"id",
)
print(campaign.id)
```
#### Response
```json
{
"id": "campaign_sqF12lZ1VlBb",
"createdAt": "2019-12-27T18:11:19.117Z",
"createdCount": 0,
"live": true,
"mailingList": "mailingList",
"status": "drafting",
"updatedAt": "2019-12-27T18:11:19.117Z",
"cheque": {
"bankAccount": "bankAccount",
"currencyCode": "CAD",
"description": "description",
"envelope": "envelope",
"letterSettings": {
"color": true
},
"letterTemplate": "letterTemplate",
"letterUploadedPDF": "https://example.com",
"logo": "https://example.com",
"mailingClass": "first_class",
"memo": "memo",
"mergeVariables": {
"foo": "bar"
},
"message": "message",
"metadata": {
"foo": "string"
},
"returnEnvelope": "returnEnvelope",
"size": "us_letter"
},
"defaultSenderContact": "defaultSenderContact",
"description": "description",
"errors": [
{
"message": "message",
"type": "processing_error"
}
],
"letter": {
"addressPlacement": "top_first_page",
"attachedPDF": {
"file": "https://example.com",
"placement": "before_template"
},
"color": true,
"description": "description",
"doubleSided": true,
"envelope": "envelope",
"envelopeType": "standard_double_window",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"paper": "standard",
"perforatedPage": 1,
"returnEnvelope": "returnEnvelope",
"size": "us_letter",
"template": "template",
"uploadedPDF": "https://example.com"
},
"metadata": {
"foo": "bar"
},
"orderPreviewURL": "https://example.com",
"postcard": {
"backTemplate": "backTemplate",
"description": "description",
"frontTemplate": "frontTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"paper": "standard",
"size": "6x4",
"uploadedPDF": "https://example.com"
},
"reportURL": "https://example.com",
"selfMailer": {
"description": "description",
"insideTemplate": "insideTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"outsideTemplate": "outsideTemplate",
"size": "8.5x11_bifold",
"uploadedPDF": "https://example.com"
},
"sendDate": "2019-12-27T18:11:19.117Z",
"snapPack": {
"description": "description",
"insideTemplate": "insideTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"outsideTemplate": "outsideTemplate",
"size": "8.5x11_bifold_v",
"uploadedPDF": "https://example.com"
}
}
```
## Update Campaign
`print_mail.campaigns.update(strid, CampaignUpdateParams**kwargs) -> Campaign`
**post** `/print-mail/v1/campaigns/{id}`
Update an existing campaign.
Campaigns can only be updated if they are in the `draft` or `changes_required` status.
Updating a campaign will trigger reprocessing and set its status back to `drafting`.
### Parameters
- `id: str`
- `cheque: Optional[Cheque]`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bank_account: Optional[str]`
ID of the bank account to use for the cheque.
- `currency_code: Optional[Literal["CAD", "USD"]]`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: Optional[str]`
An optional description.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `letter_pdf: Optional[Union[str, Base64FileInput]]`
PDF file for an optional attached letter. Cannot be used with `letterTemplate`.
- `letter_settings: Optional[ChequeLetterSettings]`
Settings for the attached letter (e.g., color printing).
- `color: Optional[bool]`
Whether to print the attached letter in color.
- `letter_template: Optional[str]`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `logo: Optional[str]`
A publicly accessible URL for the logo to print on the cheque.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the cheque.
- `"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.
- `merge_variables: Optional[Dict[str, object]]`
Default merge variables for the cheque.
- `message: Optional[str]`
Message included on the cheque stub.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[ChequeSize]`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `default_sender_contact: Optional[str]`
The ID of the default sender contact. Set to `null` to remove.
- `description: Optional[str]`
An optional description for the campaign. Set to `null` to remove the existing description.
- `letter: Optional[Letter]`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `address_placement: Optional[AddressPlacement]`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attached_pdf: Optional[AttachedPdfParam]`
Model representing an attached PDF.
- `file: str`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: Optional[bool]`
Whether to print in color.
- `description: Optional[str]`
An optional description.
- `double_sided: Optional[bool]`
Whether to print on both sides of the paper.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `envelope_type: Optional[Literal["standard_double_window", "flat"]]`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the letter.
- `"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 the letter.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdf: Optional[str]`
A PDF file or URL for the letter content. Cannot be used with `template`.
- `perforated_page: Optional[Literal[1]]`
Which page number should be perforated (if any).
- `1`
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[LetterSize]`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: Optional[str]`
ID of a template for the letter content. Cannot be used with `pdf`.
- `mailing_list: Optional[str]`
The ID of the mailing list to associate with this campaign.
- `metadata: Optional[Dict[str, str]]`
Optional key-value data associated with the campaign. Set to `null` to remove existing metadata.
- `postcard: Optional[Postcard]`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `back_template: Optional[str]`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: Optional[str]`
An optional description.
- `front_template: Optional[str]`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the postcard.
- `"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 the postcard.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdf: Optional[str]`
A 2-page PDF file for the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`.
- `size: Optional[Literal["6x4", "9x6", "11x6"]]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `self_mailer: Optional[SelfMailer]`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the self-mailer.
- `"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 the self-mailer.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `pdf: Optional[str]`
A 2-page PDF file for the self-mailer content. Cannot be used with `insideTemplate`/`outsideTemplate`.
- `size: Optional[Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]]`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `snap_pack: Optional[SnapPack]`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the snap pack.
- `"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 the snap pack.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `pdf: Optional[str]`
A 2-page PDF file for the snap pack content. Cannot be used with `insideTemplate`/`outsideTemplate`.
- `size: Optional[Literal["8.5x11_bifold_v"]]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
### Returns
- `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.
- `created_count: int`
The number of orders successfully created for this campaign.
- `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.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `cheque: Optional[Cheque]`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bank_account: Optional[str]`
ID of the bank account to use for the cheque.
- `currency_code: Optional[Literal["CAD", "USD"]]`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: Optional[str]`
An optional description.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `letter_settings: Optional[ChequeLetterSettings]`
Settings for the attached letter (e.g., color printing).
- `color: Optional[bool]`
Whether to print the attached letter in color.
- `letter_template: Optional[str]`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letter_uploaded_pdf: Optional[str]`
A signed URL to the attached letter PDF, if any.
- `logo: Optional[str]`
A publicly accessible URL for the logo to print on the cheque.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the cheque.
- `"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.
- `merge_variables: Optional[Dict[str, object]]`
Default merge variables for the cheque.
- `message: Optional[str]`
Message included on the cheque stub.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[ChequeSize]`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `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.
- `"processing_error"`
- `"internal_error"`
- `letter: Optional[Letter]`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `address_placement: Optional[AddressPlacement]`
Enum representing the placement of the address on the letter.
- `"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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: Optional[bool]`
Whether to print in color.
- `description: Optional[str]`
An optional description.
- `double_sided: Optional[bool]`
Whether to print on both sides of the paper.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `envelope_type: Optional[Literal["standard_double_window", "flat"]]`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the letter.
- `"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 the letter.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforated_page: Optional[Literal[1]]`
Which page number should be perforated (if any).
- `1`
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[LetterSize]`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: Optional[str]`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `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.
- `postcard: Optional[Postcard]`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `back_template: Optional[str]`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: Optional[str]`
An optional description.
- `front_template: Optional[str]`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the postcard.
- `"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 the postcard.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `size: Optional[Literal["6x4", "9x6", "11x6"]]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `report_url: Optional[str]`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `self_mailer: Optional[SelfMailer]`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the self-mailer.
- `"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 the self-mailer.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]]`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `send_date: Optional[datetime]`
The scheduled date and time for the campaign to be sent.
- `snap_pack: Optional[SnapPack]`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the snap pack.
- `"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 the snap pack.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold_v"]]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
campaign = client.print_mail.campaigns.update(
id="id",
)
print(campaign.id)
```
#### Response
```json
{
"id": "campaign_sqF12lZ1VlBb",
"createdAt": "2019-12-27T18:11:19.117Z",
"createdCount": 0,
"live": true,
"mailingList": "mailingList",
"status": "drafting",
"updatedAt": "2019-12-27T18:11:19.117Z",
"cheque": {
"bankAccount": "bankAccount",
"currencyCode": "CAD",
"description": "description",
"envelope": "envelope",
"letterSettings": {
"color": true
},
"letterTemplate": "letterTemplate",
"letterUploadedPDF": "https://example.com",
"logo": "https://example.com",
"mailingClass": "first_class",
"memo": "memo",
"mergeVariables": {
"foo": "bar"
},
"message": "message",
"metadata": {
"foo": "string"
},
"returnEnvelope": "returnEnvelope",
"size": "us_letter"
},
"defaultSenderContact": "defaultSenderContact",
"description": "description",
"errors": [
{
"message": "message",
"type": "processing_error"
}
],
"letter": {
"addressPlacement": "top_first_page",
"attachedPDF": {
"file": "https://example.com",
"placement": "before_template"
},
"color": true,
"description": "description",
"doubleSided": true,
"envelope": "envelope",
"envelopeType": "standard_double_window",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"paper": "standard",
"perforatedPage": 1,
"returnEnvelope": "returnEnvelope",
"size": "us_letter",
"template": "template",
"uploadedPDF": "https://example.com"
},
"metadata": {
"foo": "bar"
},
"orderPreviewURL": "https://example.com",
"postcard": {
"backTemplate": "backTemplate",
"description": "description",
"frontTemplate": "frontTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"paper": "standard",
"size": "6x4",
"uploadedPDF": "https://example.com"
},
"reportURL": "https://example.com",
"selfMailer": {
"description": "description",
"insideTemplate": "insideTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"outsideTemplate": "outsideTemplate",
"size": "8.5x11_bifold",
"uploadedPDF": "https://example.com"
},
"sendDate": "2019-12-27T18:11:19.117Z",
"snapPack": {
"description": "description",
"insideTemplate": "insideTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"outsideTemplate": "outsideTemplate",
"size": "8.5x11_bifold_v",
"uploadedPDF": "https://example.com"
}
}
```
## Delete Campaign
`print_mail.campaigns.delete(strid) -> CampaignDeleteResponse`
**delete** `/print-mail/v1/campaigns/{id}`
Delete a campaign.
Campaigns can only be deleted if they are in `draft`, `changes_required`, or `ready` status.
This also permanently deletes associated resources. This operation cannot be undone.
### Parameters
- `id: str`
### Returns
- `class CampaignDeleteResponse: …`
- `id: str`
A unique ID prefixed with campaign_
- `deleted: Literal[true]`
- `true`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
campaign = client.print_mail.campaigns.delete(
"id",
)
print(campaign.id)
```
#### Response
```json
{
"id": "campaign_sqF12lZ1VlBb",
"deleted": true
}
```
## Send Campaign
`print_mail.campaigns.send(strid, CampaignSendParams**kwargs) -> Campaign`
**post** `/print-mail/v1/campaigns/{id}/send`
Send a campaign for processing.
This action transitions a campaign from the `draft` status to `creating_orders`.
You can optionally specify a future `sendDate`. Once sent, the campaign cannot be updated.
### Parameters
- `id: str`
- `send_date: Optional[Union[Union[str, datetime], str]]`
The date and time the campaign should be sent. Must be in the future. If omitted, defaults to the earliest possible processing date.
- `Union[str, datetime]`
- `str`
### Returns
- `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.
- `created_count: int`
The number of orders successfully created for this campaign.
- `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.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `cheque: Optional[Cheque]`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bank_account: Optional[str]`
ID of the bank account to use for the cheque.
- `currency_code: Optional[Literal["CAD", "USD"]]`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: Optional[str]`
An optional description.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `letter_settings: Optional[ChequeLetterSettings]`
Settings for the attached letter (e.g., color printing).
- `color: Optional[bool]`
Whether to print the attached letter in color.
- `letter_template: Optional[str]`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letter_uploaded_pdf: Optional[str]`
A signed URL to the attached letter PDF, if any.
- `logo: Optional[str]`
A publicly accessible URL for the logo to print on the cheque.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the cheque.
- `"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.
- `merge_variables: Optional[Dict[str, object]]`
Default merge variables for the cheque.
- `message: Optional[str]`
Message included on the cheque stub.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[ChequeSize]`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `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.
- `"processing_error"`
- `"internal_error"`
- `letter: Optional[Letter]`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `address_placement: Optional[AddressPlacement]`
Enum representing the placement of the address on the letter.
- `"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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: Optional[bool]`
Whether to print in color.
- `description: Optional[str]`
An optional description.
- `double_sided: Optional[bool]`
Whether to print on both sides of the paper.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `envelope_type: Optional[Literal["standard_double_window", "flat"]]`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the letter.
- `"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 the letter.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforated_page: Optional[Literal[1]]`
Which page number should be perforated (if any).
- `1`
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[LetterSize]`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: Optional[str]`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `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.
- `postcard: Optional[Postcard]`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `back_template: Optional[str]`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: Optional[str]`
An optional description.
- `front_template: Optional[str]`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the postcard.
- `"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 the postcard.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `size: Optional[Literal["6x4", "9x6", "11x6"]]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `report_url: Optional[str]`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `self_mailer: Optional[SelfMailer]`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the self-mailer.
- `"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 the self-mailer.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]]`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `send_date: Optional[datetime]`
The scheduled date and time for the campaign to be sent.
- `snap_pack: Optional[SnapPack]`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the snap pack.
- `"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 the snap pack.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold_v"]]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
campaign = client.print_mail.campaigns.send(
id="id",
)
print(campaign.id)
```
#### Response
```json
{
"id": "campaign_sqF12lZ1VlBb",
"createdAt": "2019-12-27T18:11:19.117Z",
"createdCount": 0,
"live": true,
"mailingList": "mailingList",
"status": "drafting",
"updatedAt": "2019-12-27T18:11:19.117Z",
"cheque": {
"bankAccount": "bankAccount",
"currencyCode": "CAD",
"description": "description",
"envelope": "envelope",
"letterSettings": {
"color": true
},
"letterTemplate": "letterTemplate",
"letterUploadedPDF": "https://example.com",
"logo": "https://example.com",
"mailingClass": "first_class",
"memo": "memo",
"mergeVariables": {
"foo": "bar"
},
"message": "message",
"metadata": {
"foo": "string"
},
"returnEnvelope": "returnEnvelope",
"size": "us_letter"
},
"defaultSenderContact": "defaultSenderContact",
"description": "description",
"errors": [
{
"message": "message",
"type": "processing_error"
}
],
"letter": {
"addressPlacement": "top_first_page",
"attachedPDF": {
"file": "https://example.com",
"placement": "before_template"
},
"color": true,
"description": "description",
"doubleSided": true,
"envelope": "envelope",
"envelopeType": "standard_double_window",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"paper": "standard",
"perforatedPage": 1,
"returnEnvelope": "returnEnvelope",
"size": "us_letter",
"template": "template",
"uploadedPDF": "https://example.com"
},
"metadata": {
"foo": "bar"
},
"orderPreviewURL": "https://example.com",
"postcard": {
"backTemplate": "backTemplate",
"description": "description",
"frontTemplate": "frontTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"paper": "standard",
"size": "6x4",
"uploadedPDF": "https://example.com"
},
"reportURL": "https://example.com",
"selfMailer": {
"description": "description",
"insideTemplate": "insideTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"outsideTemplate": "outsideTemplate",
"size": "8.5x11_bifold",
"uploadedPDF": "https://example.com"
},
"sendDate": "2019-12-27T18:11:19.117Z",
"snapPack": {
"description": "description",
"insideTemplate": "insideTemplate",
"mailingClass": "first_class",
"mergeVariables": {
"foo": "bar"
},
"metadata": {
"foo": "string"
},
"outsideTemplate": "outsideTemplate",
"size": "8.5x11_bifold_v",
"uploadedPDF": "https://example.com"
}
}
```
## Domain Types
### Campaign
- `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.
- `created_count: int`
The number of orders successfully created for this campaign.
- `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.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `cheque: Optional[Cheque]`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bank_account: Optional[str]`
ID of the bank account to use for the cheque.
- `currency_code: Optional[Literal["CAD", "USD"]]`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: Optional[str]`
An optional description.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `letter_settings: Optional[ChequeLetterSettings]`
Settings for the attached letter (e.g., color printing).
- `color: Optional[bool]`
Whether to print the attached letter in color.
- `letter_template: Optional[str]`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letter_uploaded_pdf: Optional[str]`
A signed URL to the attached letter PDF, if any.
- `logo: Optional[str]`
A publicly accessible URL for the logo to print on the cheque.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the cheque.
- `"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.
- `merge_variables: Optional[Dict[str, object]]`
Default merge variables for the cheque.
- `message: Optional[str]`
Message included on the cheque stub.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[ChequeSize]`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `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.
- `"processing_error"`
- `"internal_error"`
- `letter: Optional[Letter]`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `address_placement: Optional[AddressPlacement]`
Enum representing the placement of the address on the letter.
- `"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.
- `placement: Literal["before_template", "after_template"]`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: Optional[bool]`
Whether to print in color.
- `description: Optional[str]`
An optional description.
- `double_sided: Optional[bool]`
Whether to print on both sides of the paper.
- `envelope: Optional[str]`
The custom envelope ID or `"standard"`.
- `envelope_type: Optional[Literal["standard_double_window", "flat"]]`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the letter.
- `"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 the letter.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_letter_standard_white_70lb", "premium_paper_letter_standard_white_80lb"]`
Built-in paper IDs for letter products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_letter_standard_white_70lb"`
- `"premium_paper_letter_standard_white_80lb"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforated_page: Optional[Literal[1]]`
Which page number should be perforated (if any).
- `1`
- `return_envelope: Optional[str]`
ID of a return envelope to include.
- `size: Optional[LetterSize]`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: Optional[str]`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `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.
- `postcard: Optional[Postcard]`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `back_template: Optional[str]`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: Optional[str]`
An optional description.
- `front_template: Optional[str]`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the postcard.
- `"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 the postcard.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `paper: Optional[Union[Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more], str, null]]`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `Literal["standard", "premium_paper_heavy_1_glossy", "premium_paper_postcard_uv_glossy_ss", 2 more]`
Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
- `"standard"`
- `"premium_paper_heavy_1_glossy"`
- `"premium_paper_postcard_uv_glossy_ss"`
- `"premium_paper_postcard_uv_glossy_ss_120lb"`
- `"premium_paper_postcard_satin_ds"`
- `str`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `size: Optional[Literal["6x4", "9x6", "11x6"]]`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `report_url: Optional[str]`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `self_mailer: Optional[SelfMailer]`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the self-mailer.
- `"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 the self-mailer.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold", "8.5x11_trifold", "9.5x16_trifold"]]`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
- `send_date: Optional[datetime]`
The scheduled date and time for the campaign to be sent.
- `snap_pack: Optional[SnapPack]`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: Optional[str]`
An optional description.
- `inside_template: Optional[str]`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
Mailing class for the snap pack.
- `"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 the snap pack.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata.
- `outside_template: Optional[str]`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: Optional[Literal["8.5x11_bifold_v"]]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploaded_pdf: Optional[str]`
A signed URL to the uploaded PDF, if any.
### Campaign Delete Response
- `class CampaignDeleteResponse: …`
- `id: str`
A unique ID prefixed with campaign_
- `deleted: Literal[true]`
- `true`
# Mailing List Imports
## Create Mailing List Import
`print_mail.mailing_list_imports.create(MailingListImportCreateParams**kwargs) -> MailingListImportResponse`
**post** `/print-mail/v1/mailing_list_imports`
Create a new mailing list import.
Initiates the import process for a contact list file. The import enters the
`validating` status while contacts are processed and verified.
### Parameters
- `file: str`
The CSV file for this import.
- `file_type: FileType`
Type of file supported for mailing list imports.
- `"csv"`
- `receiver_address_mapping: Dict[str, str]`
Mapping of columns for receiver addresses.
- `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.
- `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.
If this is present, then all receivers should have a corresponding sender.
- `sender_merge_variable_mapping: Optional[Dict[str, str]]`
Optional mapping of columns for sender merge variables.
- `idempotency_key: Optional[str]`
### Returns
- `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.
- `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.
- `"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.
- `"csv"`
- `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.
- `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.
- `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.
- `"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.
- `failed_count: int`
Number of contacts that failed verification.
- `verified_count: int`
Number of contacts that were verified without changes.
- `status: Literal["validating", "completed", "changes_required"]`
Status of the mailing list import process.
- `"validating"`
- `"completed"`
- `"changes_required"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `valid_row_count: int`
Number of valid rows processed from the file.
- `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.
- `sender_status_count: Optional[VerificationStatusCount]`
Count of contact verification statuses.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
mailing_list_import_response = client.print_mail.mailing_list_imports.create(
file="https://signed-upload-url.csv",
file_type="csv",
receiver_address_mapping={
"description": "Description",
"firstName": "First Name",
"lastName": "Last Name",
"email": "Email",
"addressLine1": "Address",
"city": "City",
"postalOrZip": "Postal Code",
"provinceOrState": "State",
"countryCode": "Country",
},
)
print(mailing_list_import_response.id)
```
#### Response
```json
{
"id": "mailing_list_import_123",
"live": false,
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:05:00Z",
"status": "completed",
"reportURL": "https://signed-report-url.csv",
"errors": [],
"notes": [],
"validRowCount": 100,
"invalidRowCount": 0,
"receiverStatusCount": {
"verifiedCount": 100,
"correctedCount": 0,
"failedCount": 0
},
"senderStatusCount": {
"verifiedCount": 100,
"correctedCount": 0,
"failedCount": 0
},
"organization": "org_123",
"file": {
"fileType": "csv",
"receiverAddressMapping": {
"description": "Description",
"firstName": "First Name",
"lastName": "Last Name",
"email": "Email",
"addressLine1": "Address",
"addressLine2": "Address Line 2",
"city": "City",
"postalOrZip": "Postal Code",
"provinceOrState": "Province",
"countryCode": "Country"
},
"url": "https://signed.url/import_123.csv"
}
}
```
## List Mailing List Imports
`print_mail.mailing_list_imports.list(MailingListImportListParams**kwargs) -> SyncSkipLimit[MailingListImportResponse]`
**get** `/print-mail/v1/mailing_list_imports`
Retrieve a list of mailing list imports.
Returns a paginated list of imports associated with the authenticated organization,
filterable by various parameters.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `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.
- `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.
- `"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.
- `"csv"`
- `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.
- `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.
- `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.
- `"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.
- `failed_count: int`
Number of contacts that failed verification.
- `verified_count: int`
Number of contacts that were verified without changes.
- `status: Literal["validating", "completed", "changes_required"]`
Status of the mailing list import process.
- `"validating"`
- `"completed"`
- `"changes_required"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `valid_row_count: int`
Number of valid rows processed from the file.
- `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.
- `sender_status_count: Optional[VerificationStatusCount]`
Count of contact verification statuses.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.mailing_list_imports.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"totalCount": 1,
"skip": 0,
"limit": 10,
"data": [
{
"id": "mailing_list_import_123",
"live": false,
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:05:00Z",
"status": "completed",
"reportURL": "https://signed-report-url.csv",
"errors": [],
"notes": [],
"validRowCount": 100,
"invalidRowCount": 0,
"receiverStatusCount": {
"verifiedCount": 100,
"correctedCount": 0,
"failedCount": 0
},
"senderStatusCount": {
"verifiedCount": 100,
"correctedCount": 0,
"failedCount": 0
},
"organization": "org_123",
"file": {
"fileType": "csv",
"receiverAddressMapping": {
"description": "Description",
"firstName": "First Name",
"lastName": "Last Name",
"email": "Email",
"addressLine1": "Address",
"addressLine2": "Address Line 2",
"city": "City",
"postalOrZip": "Postal Code",
"provinceOrState": "Province",
"countryCode": "Country"
},
"url": "https://signed.url/import_123.csv"
}
}
]
}
```
## Update Mailing List Import
`print_mail.mailing_list_imports.update(strid, MailingListImportUpdateParams**kwargs) -> MailingListImportResponse`
**post** `/print-mail/v1/mailing_list_imports/{id}`
Update an existing mailing list import.
### Parameters
- `id: str`
- `description: Optional[str]`
An optional description for the import. Set to `null` to remove the existing description.
- `metadata: Optional[Dict[str, str]]`
Optional key-value data associated with the import. Set to `null` to remove existing metadata.
### Returns
- `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.
- `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.
- `"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.
- `"csv"`
- `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.
- `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.
- `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.
- `"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.
- `failed_count: int`
Number of contacts that failed verification.
- `verified_count: int`
Number of contacts that were verified without changes.
- `status: Literal["validating", "completed", "changes_required"]`
Status of the mailing list import process.
- `"validating"`
- `"completed"`
- `"changes_required"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `valid_row_count: int`
Number of valid rows processed from the file.
- `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.
- `sender_status_count: Optional[VerificationStatusCount]`
Count of contact verification statuses.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
mailing_list_import_response = client.print_mail.mailing_list_imports.update(
id="id",
description="Corrected description",
metadata={
"batch": "spring_sale"
},
)
print(mailing_list_import_response.id)
```
#### Response
```json
{
"id": "mailing_list_import_123",
"live": false,
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:05:00Z",
"status": "completed",
"reportURL": "https://signed-report-url.csv",
"errors": [],
"notes": [],
"validRowCount": 100,
"invalidRowCount": 0,
"receiverStatusCount": {
"verifiedCount": 100,
"correctedCount": 0,
"failedCount": 0
},
"senderStatusCount": {
"verifiedCount": 100,
"correctedCount": 0,
"failedCount": 0
},
"organization": "org_123",
"file": {
"fileType": "csv",
"receiverAddressMapping": {
"description": "Description",
"firstName": "First Name",
"lastName": "Last Name",
"email": "Email",
"addressLine1": "Address",
"addressLine2": "Address Line 2",
"city": "City",
"postalOrZip": "Postal Code",
"provinceOrState": "Province",
"countryCode": "Country"
},
"url": "https://signed.url/import_123.csv"
}
}
```
## Get Mailing List Import
`print_mail.mailing_list_imports.retrieve(strid) -> MailingListImportResponse`
**get** `/print-mail/v1/mailing_list_imports/{id}`
Retrieve a specific mailing list import by its ID.
### Parameters
- `id: str`
### Returns
- `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.
- `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.
- `"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.
- `"csv"`
- `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.
- `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.
- `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.
- `"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.
- `failed_count: int`
Number of contacts that failed verification.
- `verified_count: int`
Number of contacts that were verified without changes.
- `status: Literal["validating", "completed", "changes_required"]`
Status of the mailing list import process.
- `"validating"`
- `"completed"`
- `"changes_required"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `valid_row_count: int`
Number of valid rows processed from the file.
- `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.
- `sender_status_count: Optional[VerificationStatusCount]`
Count of contact verification statuses.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
mailing_list_import_response = client.print_mail.mailing_list_imports.retrieve(
"id",
)
print(mailing_list_import_response.id)
```
#### Response
```json
{
"id": "mailing_list_import_123",
"live": false,
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:05:00Z",
"status": "completed",
"reportURL": "https://signed-report-url.csv",
"errors": [],
"notes": [],
"validRowCount": 100,
"invalidRowCount": 0,
"receiverStatusCount": {
"verifiedCount": 100,
"correctedCount": 0,
"failedCount": 0
},
"senderStatusCount": {
"verifiedCount": 100,
"correctedCount": 0,
"failedCount": 0
},
"organization": "org_123",
"file": {
"fileType": "csv",
"receiverAddressMapping": {
"description": "Description",
"firstName": "First Name",
"lastName": "Last Name",
"email": "Email",
"addressLine1": "Address",
"addressLine2": "Address Line 2",
"city": "City",
"postalOrZip": "Postal Code",
"provinceOrState": "Province",
"countryCode": "Country"
},
"url": "https://signed.url/import_123.csv"
}
}
```
## Delete Mailing List Import
`print_mail.mailing_list_imports.delete(strid) -> MailingListImportDeleteResponse`
**delete** `/print-mail/v1/mailing_list_imports/{id}`
Delete a mailing list import.
This permanently deletes the import and its associated resources.
This operation cannot be undone.
### Parameters
- `id: str`
### Returns
- `class MailingListImportDeleteResponse: …`
- `id: str`
A unique ID prefixed with mailing_list_import_
- `deleted: Literal[true]`
- `true`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
mailing_list_import = client.print_mail.mailing_list_imports.delete(
"id",
)
print(mailing_list_import.id)
```
#### Response
```json
{
"id": "mailing_list_import_123",
"deleted": true
}
```
## Domain Types
### File Type
- `Literal["csv"]`
Type of file supported for mailing list imports.
- `"csv"`
### Mailing List Import Response
- `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.
- `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.
- `"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.
- `"csv"`
- `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.
- `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.
- `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.
- `"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.
- `failed_count: int`
Number of contacts that failed verification.
- `verified_count: int`
Number of contacts that were verified without changes.
- `status: Literal["validating", "completed", "changes_required"]`
Status of the mailing list import process.
- `"validating"`
- `"completed"`
- `"changes_required"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `valid_row_count: int`
Number of valid rows processed from the file.
- `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.
- `sender_status_count: Optional[VerificationStatusCount]`
Count of contact verification statuses.
### Verification Status Count
- `class VerificationStatusCount: …`
Count of contact verification statuses.
- `corrected_count: int`
Number of contacts that were corrected during verification.
- `failed_count: int`
Number of contacts that failed verification.
- `verified_count: int`
Number of contacts that were verified without changes.
### Mailing List Import Delete Response
- `class MailingListImportDeleteResponse: …`
- `id: str`
A unique ID prefixed with mailing_list_import_
- `deleted: Literal[true]`
- `true`
# Mailing Lists
## Create Mailing List
`print_mail.mailing_lists.create(MailingListCreateParams**kwargs) -> MailingList`
**post** `/print-mail/v1/mailing_lists`
Create a new mailing list.
### Parameters
- `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.
- `idempotency_key: Optional[str]`
### Returns
- `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.
- `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.
- `"creating_contacts"`
- `"removing_contacts"`
- `"counting_recipient_country_codes"`
- `"completed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"mailing_list_imports_not_found_error"`
- `"download_file_error"`
- `"operational_error"`
- `"internal_service_error"`
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
mailing_list = client.print_mail.mailing_lists.create(
description="Test Mailing List",
metadata={
"campaign": "launch"
},
)
print(mailing_list.id)
```
#### Response
```json
{
"id": "mailing_list_123",
"live": false,
"description": "Test Mailing List",
"metadata": {
"campaign": "launch"
},
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:00:00Z",
"status": "completed",
"errors": []
}
```
## List Mailing Lists
`print_mail.mailing_lists.list(MailingListListParams**kwargs) -> SyncSkipLimit[MailingList]`
**get** `/print-mail/v1/mailing_lists`
Retrieve a list of mailing lists.
Returns a paginated list of mailing lists associated with the authenticated organization,
filterable by various parameters.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `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.
- `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.
- `"creating_contacts"`
- `"removing_contacts"`
- `"counting_recipient_country_codes"`
- `"completed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"mailing_list_imports_not_found_error"`
- `"download_file_error"`
- `"operational_error"`
- `"internal_service_error"`
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.mailing_lists.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"totalCount": 1,
"skip": 0,
"limit": 10,
"data": [
{
"id": "mailing_list_123",
"live": false,
"description": "Test Mailing List",
"metadata": {
"campaign": "launch"
},
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:00:00Z",
"status": "completed",
"errors": []
}
]
}
```
## Get Mailing List
`print_mail.mailing_lists.retrieve(strid) -> MailingList`
**get** `/print-mail/v1/mailing_lists/{id}`
Retrieve a specific mailing list by its ID.
### Parameters
- `id: str`
### Returns
- `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.
- `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.
- `"creating_contacts"`
- `"removing_contacts"`
- `"counting_recipient_country_codes"`
- `"completed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"mailing_list_imports_not_found_error"`
- `"download_file_error"`
- `"operational_error"`
- `"internal_service_error"`
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
mailing_list = client.print_mail.mailing_lists.retrieve(
"id",
)
print(mailing_list.id)
```
#### Response
```json
{
"id": "mailing_list_123",
"live": false,
"description": "Test Mailing List",
"metadata": {
"campaign": "launch"
},
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:00:00Z",
"status": "completed",
"errors": []
}
```
## Update Mailing List
`print_mail.mailing_lists.update(strid, MailingListUpdateParams**kwargs) -> MailingListUpdate`
**post** `/print-mail/v1/mailing_lists/{id}`
Update an existing mailing list.
### Parameters
- `id: str`
- `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.
### Returns
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
mailing_list_update = client.print_mail.mailing_lists.update(
id="id",
description="Updated Mailing List Description",
)
print(mailing_list_update.description)
```
#### Response
```json
{
"description": "Test Mailing List",
"metadata": {
"campaign": "launch"
}
}
```
## Delete Mailing List
`print_mail.mailing_lists.delete(strid) -> MailingListDeleteResponse`
**delete** `/print-mail/v1/mailing_lists/{id}`
Delete a mailing list.
This permanently deletes the mailing list and its associations.
This operation cannot be undone.
### Parameters
- `id: str`
### Returns
- `class MailingListDeleteResponse: …`
- `id: str`
A unique ID prefixed with mailing_list_
- `deleted: Literal[true]`
- `true`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
mailing_list = client.print_mail.mailing_lists.delete(
"id",
)
print(mailing_list.id)
```
#### Response
```json
{
"id": "mailing_list_sqF12lZ1VlBb",
"deleted": true
}
```
## Submit a Mailing List Job
`print_mail.mailing_lists.jobs(strid, MailingListJobsParams**kwargs) -> MailingList`
**post** `/print-mail/v1/mailing_lists/{id}/jobs`
Runs a mailing list job. Mailing list jobs allow you to add or remove contacts
to your mailing list from mailing list imports or directly with contact IDs.
Only one job can be ran at a time and jobs are only able to be ran while the
mailing list has a `status` of "completed".
Once a job as successfully been kicked off, the mailing list will have a `status`
of either `creating_contacts` or `removing_contacts` depending on which job
was ran. After the job has finished, the mailing list will go back into the
`completed` state where more jobs can be ran. If there are any errors while
running a job, the `errors` field on the mailing list will contain a list of
error objects which describe the errors.
### Parameters
- `id: str`
- `add_contacts: Optional[Sequence[str]]`
List of contact IDs to add to the mailing list. Cannot be used with other operations.
- `add_mailing_list_imports: Optional[Sequence[str]]`
List of mailing list import IDs to add to the mailing list. Cannot be used with other operations.
- `remove_contacts: Optional[Sequence[str]]`
List of contact IDs to remove from the mailing list. Cannot be used with other operations.
- `remove_mailing_list_imports: Optional[Sequence[str]]`
List of mailing list import IDs to remove from the mailing list. Cannot be used with other operations.
### Returns
- `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.
- `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.
- `"creating_contacts"`
- `"removing_contacts"`
- `"counting_recipient_country_codes"`
- `"completed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"mailing_list_imports_not_found_error"`
- `"download_file_error"`
- `"operational_error"`
- `"internal_service_error"`
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
mailing_list = client.print_mail.mailing_lists.jobs(
id="id",
remove_mailing_list_imports=["mailing_list_import_123", "mailing_list_import_456"],
)
print(mailing_list.id)
```
#### Response
```json
{
"id": "mailing_list_123",
"live": false,
"description": "Test Mailing List",
"metadata": {
"campaign": "launch"
},
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:00:00Z",
"status": "completed",
"errors": []
}
```
## Domain Types
### Mailing List
- `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.
- `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.
- `"creating_contacts"`
- `"removing_contacts"`
- `"counting_recipient_country_codes"`
- `"completed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"mailing_list_imports_not_found_error"`
- `"download_file_error"`
- `"operational_error"`
- `"internal_service_error"`
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
### Mailing List Update
- `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.
### Mailing List Delete Response
- `class MailingListDeleteResponse: …`
- `id: str`
A unique ID prefixed with mailing_list_
- `deleted: Literal[true]`
- `true`
# Reports
## Create Saved Report
`print_mail.reports.create(ReportCreateParams**kwargs) -> Report`
**post** `/print-mail/v1/reports`
Create a new saved report definition. Saved reports are SQL queries that can be executed later to generate
full exports or samples.
If you just want to do ad-hoc queries, you should use the `/reports/samples` endpoint.
### Parameters
- `sql_query: str`
The SQL query defining the report.
- `description: Optional[str]`
An optional user-friendly description for the report.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata associated with the report.
### Returns
- `class Report: …`
Represents a saved Report definition.
- `id: str`
Unique identifier for the report.
- `created_at: datetime`
Timestamp when the report was created.
- `live: bool`
Indicates if the report is associated with the live or test environment.
- `object: Literal["report"]`
Always `report`.
- `"report"`
- `sql_query: str`
The SQL query defining the report.
- `updated_at: datetime`
Timestamp when the report was last updated.
- `description: Optional[str]`
An optional user-friendly description for the report.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata associated with the report.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
report = client.print_mail.reports.create(
sql_query="SELECT id, status FROM orders WHERE created_at > ?",
description="Recent Orders",
metadata={
"team": "Sales"
},
)
print(report.id)
```
#### Response
```json
{
"id": "report_123",
"object": "report",
"live": false,
"sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
"description": "Recent Orders",
"metadata": {
"team": "Sales"
},
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:00:00Z"
}
```
## Run Ad-hoc Query
`print_mail.reports.sample(ReportSampleParams**kwargs) -> ReportSample`
**post** `/print-mail/v1/reports/samples`
Run an ad-hoc SQL query against your data lake and get a sample of the results.
This is useful for quickly testing queries without saving them as a report.
The query execution time and result size are limited.
### Parameters
- `sql_query: str`
The SQL query to execute for the sample.
- `limit: Optional[int]`
Maximum number of rows to return in the sample.
- `params: Optional[Sequence[str]]`
Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).
### Returns
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
report_sample = client.print_mail.reports.sample(
sql_query="SELECT id FROM contacts LIMIT 5",
limit=5,
params=[],
)
print(report_sample.id)
```
#### Response
```json
{
"id": "sample_abc",
"report": "report_123",
"records": [
{
"id": "order_1"
},
{
"id": "order_2"
}
]
}
```
## Update Report
`print_mail.reports.update(strid, ReportUpdateParams**kwargs) -> Report`
**post** `/print-mail/v1/reports/{id}`
Update an existing saved report definition. You can change the query, description, or metadata.
### Parameters
- `id: str`
- `description: Optional[str]`
An optional user-friendly description for the report. Set to null to remove.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata associated with the report. Set to null to remove.
- `sql_query: Optional[str]`
The SQL query defining the report.
### Returns
- `class Report: …`
Represents a saved Report definition.
- `id: str`
Unique identifier for the report.
- `created_at: datetime`
Timestamp when the report was created.
- `live: bool`
Indicates if the report is associated with the live or test environment.
- `object: Literal["report"]`
Always `report`.
- `"report"`
- `sql_query: str`
The SQL query defining the report.
- `updated_at: datetime`
Timestamp when the report was last updated.
- `description: Optional[str]`
An optional user-friendly description for the report.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata associated with the report.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
report = client.print_mail.reports.update(
id="id",
description="Recent Orders (Updated)",
)
print(report.id)
```
#### Response
```json
{
"id": "report_123",
"object": "report",
"live": false,
"sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
"description": "Recent Orders",
"metadata": {
"team": "Sales"
},
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:00:00Z"
}
```
## List Saved Reports
`print_mail.reports.list(ReportListParams**kwargs) -> SyncSkipLimit[Report]`
**get** `/print-mail/v1/reports`
Retrieve a list of saved reports for your organization.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class Report: …`
Represents a saved Report definition.
- `id: str`
Unique identifier for the report.
- `created_at: datetime`
Timestamp when the report was created.
- `live: bool`
Indicates if the report is associated with the live or test environment.
- `object: Literal["report"]`
Always `report`.
- `"report"`
- `sql_query: str`
The SQL query defining the report.
- `updated_at: datetime`
Timestamp when the report was last updated.
- `description: Optional[str]`
An optional user-friendly description for the report.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata associated with the report.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.reports.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "report_123",
"object": "report",
"live": false,
"sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
"description": "Recent Orders",
"metadata": {
"team": "Sales"
},
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:00:00Z"
}
]
}
```
## Retrieve Saved Report
`print_mail.reports.retrieve(strid) -> Report`
**get** `/print-mail/v1/reports/{id}`
Retrieve the details of a specific saved report by its ID.
### Parameters
- `id: str`
### Returns
- `class Report: …`
Represents a saved Report definition.
- `id: str`
Unique identifier for the report.
- `created_at: datetime`
Timestamp when the report was created.
- `live: bool`
Indicates if the report is associated with the live or test environment.
- `object: Literal["report"]`
Always `report`.
- `"report"`
- `sql_query: str`
The SQL query defining the report.
- `updated_at: datetime`
Timestamp when the report was last updated.
- `description: Optional[str]`
An optional user-friendly description for the report.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata associated with the report.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
report = client.print_mail.reports.retrieve(
"id",
)
print(report.id)
```
#### Response
```json
{
"id": "report_123",
"object": "report",
"live": false,
"sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
"description": "Recent Orders",
"metadata": {
"team": "Sales"
},
"createdAt": "2023-10-27T10:00:00Z",
"updatedAt": "2023-10-27T10:00:00Z"
}
```
## Delete Saved Report
`print_mail.reports.delete(strid) -> DeletedResponse`
**delete** `/print-mail/v1/reports/{id}`
Delete a saved report definition. This action cannot be undone.
Associated exports are not automatically deleted.
### Parameters
- `id: str`
### Returns
- `class DeletedResponse: …`
Generic response for delete operations.
- `id: str`
The ID of the deleted resource.
- `deleted: Literal[true]`
Indicates the resource was successfully deleted.
- `true`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
deleted_response = client.print_mail.reports.delete(
"id",
)
print(deleted_response.id)
```
#### Response
```json
{
"id": "report_123",
"deleted": true
}
```
## Domain Types
### Deleted Response
- `class DeletedResponse: …`
Generic response for delete operations.
- `id: str`
The ID of the deleted resource.
- `deleted: Literal[true]`
Indicates the resource was successfully deleted.
- `true`
### Report
- `class Report: …`
Represents a saved Report definition.
- `id: str`
Unique identifier for the report.
- `created_at: datetime`
Timestamp when the report was created.
- `live: bool`
Indicates if the report is associated with the live or test environment.
- `object: Literal["report"]`
Always `report`.
- `"report"`
- `sql_query: str`
The SQL query defining the report.
- `updated_at: datetime`
Timestamp when the report was last updated.
- `description: Optional[str]`
An optional user-friendly description for the report.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata associated with the report.
# Samples
## Sample a Saved Report
`print_mail.reports.samples.create(strid, SampleCreateParams**kwargs) -> ReportSample`
**post** `/print-mail/v1/reports/{id}/samples`
Run the query associated with a saved report and get a sample of the results.
This allows getting up to 1000 rows of resutls but the runtime of the query is limited to 30 seconds.
If you need more rows or longer runtime, you should create an export from this report.
### Parameters
- `id: str`
- `limit: Optional[int]`
Maximum number of rows to return in the sample.
- `params: Optional[Sequence[str]]`
Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).
### Returns
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
report_sample = client.print_mail.reports.samples.create(
id="id",
limit=10,
params=["2023-10-01T00:00:00Z"],
)
print(report_sample.id)
```
#### Response
```json
{
"id": "sample_abc",
"report": "report_123",
"records": [
{
"id": "order_1"
},
{
"id": "order_2"
}
]
}
```
## Domain Types
### Report Sample
- `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.
### Report Sample Create Base
- `class ReportSampleCreateBase: …`
Base properties for creating a report sample.
- `limit: Optional[int]`
Maximum number of rows to return in the sample.
- `params: Optional[List[str]]`
Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).
# Exports
## Create a Report Export
`print_mail.reports.exports.create(strreport_id, ExportCreateParams**kwargs) -> ReportExport`
**post** `/print-mail/v1/reports/{reportID}/exports`
Create a new export job for a saved report. This runs the report's query
asynchronously and generates a downloadable CSV file with the full results.
Your queries can run for up to 13 minutes the resulting file can be up to 100mb large.
### Parameters
- `report_id: str`
- `description: Optional[str]`
An optional user-friendly description for the export.
- `metadata: Optional[Dict[str, str]]`
Optional key-value metadata associated with the export.
- `params: Optional[Sequence[str]]`
Optional parameters to bind to the SQL query of the associated report.
### Returns
- `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.
- `live: bool`
Indicates if the export is associated with the live or test environment.
- `object: Literal["report_export"]`
Always `report_export`.
- `"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).
- `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.
- `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.
- `size_in_bytes: Optional[int]`
The size of the generated export file in bytes.
- `truncated_to_bytes: Optional[int]`
If the output was truncated, indicates the byte limit reached.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
report_export = client.print_mail.reports.exports.create(
report_id="reportID",
description="October Orders Export",
params=["2023-10-01T00:00:00Z"],
)
print(report_export.id)
```
#### Response
```json
{
"id": "report_export_123",
"object": "report_export",
"live": false,
"report": {
"id": "report_123",
"sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?"
},
"params": [
"2023-10-01T00:00:00Z"
],
"description": "October Orders Export",
"outputURL": "https://s3.amazonaws.com/...",
"sizeInBytes": 1024,
"rowCount": 50,
"createdAt": "2023-10-27T11:00:00Z",
"updatedAt": "2023-10-27T11:05:00Z"
}
```
## Get Report Export
`print_mail.reports.exports.retrieve(strexport_id, ExportRetrieveParams**kwargs) -> ReportExport`
**get** `/print-mail/v1/reports/{reportID}/exports/{exportID}`
Retrieve the status and details of a specific report export job.
Check the `outputURL` property for the download link once generation is complete.
### Parameters
- `report_id: str`
- `export_id: str`
### Returns
- `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.
- `live: bool`
Indicates if the export is associated with the live or test environment.
- `object: Literal["report_export"]`
Always `report_export`.
- `"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).
- `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.
- `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.
- `size_in_bytes: Optional[int]`
The size of the generated export file in bytes.
- `truncated_to_bytes: Optional[int]`
If the output was truncated, indicates the byte limit reached.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
report_export = client.print_mail.reports.exports.retrieve(
export_id="exportID",
report_id="reportID",
)
print(report_export.id)
```
#### Response
```json
{
"id": "report_export_123",
"object": "report_export",
"live": false,
"report": {
"id": "report_123",
"sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?"
},
"params": [
"2023-10-01T00:00:00Z"
],
"description": "October Orders Export",
"outputURL": "https://s3.amazonaws.com/...",
"sizeInBytes": 1024,
"rowCount": 50,
"createdAt": "2023-10-27T11:00:00Z",
"updatedAt": "2023-10-27T11:05:00Z"
}
```
## Delete Report Export
`print_mail.reports.exports.delete(strexport_id, ExportDeleteParams**kwargs) -> DeletedResponse`
**delete** `/print-mail/v1/reports/{reportID}/exports/{exportID}`
Delete a completed or failed report export job and its associated output file (if any).
This action cannot be undone. You cannot delete an export that is still generating.
### Parameters
- `report_id: str`
- `export_id: str`
### Returns
- `class DeletedResponse: …`
Generic response for delete operations.
- `id: str`
The ID of the deleted resource.
- `deleted: Literal[true]`
Indicates the resource was successfully deleted.
- `true`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
deleted_response = client.print_mail.reports.exports.delete(
export_id="exportID",
report_id="reportID",
)
print(deleted_response.id)
```
#### Response
```json
{
"id": "report_export_123",
"deleted": true
}
```
## Domain Types
### Report Export
- `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.
- `live: bool`
Indicates if the export is associated with the live or test environment.
- `object: Literal["report_export"]`
Always `report_export`.
- `"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).
- `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.
- `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.
- `size_in_bytes: Optional[int]`
The size of the generated export file in bytes.
- `truncated_to_bytes: Optional[int]`
If the output was truncated, indicates the byte limit reached.
# Sub Organizations
## Create a sub-organization.
`print_mail.sub_organizations.create(SubOrganizationCreateParams**kwargs) -> SubOrganizationCreateResponse`
**post** `/print-mail/v1/sub_organizations`
When creating a user through the API, the verifiedEmail field will automatically be
set to true. However, if public signups are used, the email will need to be verified
by the user.
### Parameters
- `country_code: str`
The country code of the sub-organization.
- `email: str`
The email of the user to be created alongside the sub-organization.
- `name: str`
The name of the user to be created alongside the sub-organization.
- `organization_name: str`
The name of the sub-organization.
- `password: str`
The password of the user to be created alongside the sub-organization.
- `phone_number: Optional[str]`
The phone number of the user to be created alongside the
sub-organization.
### Returns
- `class SubOrganizationCreateResponse: …`
- `sub_organization: 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.
- `limit: int`
The limit of mailings the sub-organization can send before being charged
overages for the month.
- `name: str`
The name of the sub-organization.
- `object: Literal["sub_org"]`
Always `sub_org`.
- `"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.
- `usage: int`
The amount of mail the sub-organization has sent out this month.
- `user: User`
The user object.
- `id: str`
A unique ID prefixed with `user_`.
- `api_keys: List[UserAPIKey]`
The user's API keys. Contains live and test mode API keys.
- `value: str`
The value of the API key.
- `active_until: Optional[datetime]`
An optional date which the API key is active until. After this date, the
API key will no longer be valid.
- `email: str`
The email of the user.
- `name: str`
The name of the user.
- `organization: str`
A unique ID prefixed with `user_`.
- `pending_invite: bool`
Indicates if the user has a pending invite.
- `roles: List[str]`
The roles given to the user. Roles can be used to restrict access for
users.
- `verified_email: bool`
Indicates if the user has a verified email or not.
- `email_preferences: Optional[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.
- `"do_not_send"`
- `"send_live_only"`
- `"send_live_and_test"`
- `last_login_time: Optional[datetime]`
The date and time at which the user last logged in.
- `phone_number: Optional[str]`
The phone number of the user.
- `previous_emails: Optional[List[str]]`
A list of emails the user has previously had. If a user has changed their
email before, this list will be populated with all of the emails they
once had.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
sub_organization = client.print_mail.sub_organizations.create(
country_code="CA",
email="suborg@postgrid.com",
name="Calvin",
organization_name="PostGrid",
password="very-strong-password",
phone_number="9059059059",
)
print(sub_organization.sub_organization)
```
#### Response
```json
{
"user": {
"id": "user_abc123def456ghi6789",
"pendingInvite": false,
"organization": "org_abc123def456ghi6789",
"email": "user@postgrid.com",
"name": "Calvin",
"apiKeys": [
{
"value": "live_abcdefg"
},
{
"value": "test_abcdefg"
}
],
"verifiedEmail": true,
"roles": [
"role_abc123def456ghi6789"
]
},
"subOrganization": {
"usage": 0,
"limit": 500,
"spend": 0,
"name": "PostGrid",
"countryCode": "CA",
"id": "sub_org_abc123def456ghi6789",
"object": "sub_org",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z"
}
}
```
## List sub-organizations.
`print_mail.sub_organizations.list(SubOrganizationListParams**kwargs) -> SyncSkipLimit[SubOrganization]`
**get** `/print-mail/v1/sub_organizations`
List sub-organizations.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `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.
- `limit: int`
The limit of mailings the sub-organization can send before being charged
overages for the month.
- `name: str`
The name of the sub-organization.
- `object: Literal["sub_org"]`
Always `sub_org`.
- `"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.
- `usage: int`
The amount of mail the sub-organization has sent out this month.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.sub_organizations.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"usage": 0,
"limit": 500,
"spend": 0,
"name": "PostGrid",
"countryCode": "CA",
"id": "sub_org_abc123def456ghi6789",
"object": "sub_org",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z"
}
]
}
```
## Get a sub-organization.
`print_mail.sub_organizations.retrieve(strid) -> SubOrganization`
**get** `/print-mail/v1/sub_organizations/{id}`
Get a sub-organization.
### Parameters
- `id: str`
### Returns
- `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.
- `limit: int`
The limit of mailings the sub-organization can send before being charged
overages for the month.
- `name: str`
The name of the sub-organization.
- `object: Literal["sub_org"]`
Always `sub_org`.
- `"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.
- `usage: int`
The amount of mail the sub-organization has sent out this month.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
sub_organization = client.print_mail.sub_organizations.retrieve(
"id",
)
print(sub_organization.id)
```
#### Response
```json
{
"usage": 0,
"limit": 500,
"spend": 0,
"name": "PostGrid",
"countryCode": "CA",
"id": "sub_org_abc123def456ghi6789",
"object": "sub_org",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z"
}
```
## List users for a sub-organization.
`print_mail.sub_organizations.retrieve_users(strid, SubOrganizationRetrieveUsersParams**kwargs) -> SubOrganizationRetrieveUsersResponse`
**get** `/print-mail/v1/sub_organizations/{id}/users`
List users for a sub-organization.
### Parameters
- `id: str`
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `List[SubOrganizationRetrieveUsersResponseItem]`
- `id: str`
A unique ID prefixed with `user_`.
- `email: str`
The email of the user.
- `name: str`
The name of the user.
- `organization: str`
A unique ID prefixed with `user_`.
- `pending_invite: bool`
Indicates if the user has a pending invite.
- `roles: List[str]`
The roles given to the user. Roles can be used to restrict access for
users.
- `verified_email: bool`
Indicates if the user has a verified email or not.
- `email_preferences: Optional[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.
- `"do_not_send"`
- `"send_live_only"`
- `"send_live_and_test"`
- `last_login_time: Optional[datetime]`
The date and time at which the user last logged in.
- `phone_number: Optional[str]`
The phone number of the user.
- `previous_emails: Optional[List[str]]`
A list of emails the user has previously had. If a user has changed their
email before, this list will be populated with all of the emails they
once had.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.sub_organizations.retrieve_users(
id="id",
)
print(response)
```
#### Response
```json
[
{
"id": "user_abc123def456ghi6789",
"pendingInvite": false,
"organization": "org_abc123def456ghi6789",
"email": "user@postgrid.com",
"name": "Calvin",
"verifiedEmail": true,
"roles": [
"role_abc123def456ghi6789"
]
}
]
```
## Domain Types
### Email Preferences
- `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.
- `"do_not_send"`
- `"send_live_only"`
- `"send_live_and_test"`
### Sub Organization
- `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.
- `limit: int`
The limit of mailings the sub-organization can send before being charged
overages for the month.
- `name: str`
The name of the sub-organization.
- `object: Literal["sub_org"]`
Always `sub_org`.
- `"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.
- `usage: int`
The amount of mail the sub-organization has sent out this month.
### Sub Organization Create Response
- `class SubOrganizationCreateResponse: …`
- `sub_organization: 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.
- `limit: int`
The limit of mailings the sub-organization can send before being charged
overages for the month.
- `name: str`
The name of the sub-organization.
- `object: Literal["sub_org"]`
Always `sub_org`.
- `"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.
- `usage: int`
The amount of mail the sub-organization has sent out this month.
- `user: User`
The user object.
- `id: str`
A unique ID prefixed with `user_`.
- `api_keys: List[UserAPIKey]`
The user's API keys. Contains live and test mode API keys.
- `value: str`
The value of the API key.
- `active_until: Optional[datetime]`
An optional date which the API key is active until. After this date, the
API key will no longer be valid.
- `email: str`
The email of the user.
- `name: str`
The name of the user.
- `organization: str`
A unique ID prefixed with `user_`.
- `pending_invite: bool`
Indicates if the user has a pending invite.
- `roles: List[str]`
The roles given to the user. Roles can be used to restrict access for
users.
- `verified_email: bool`
Indicates if the user has a verified email or not.
- `email_preferences: Optional[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.
- `"do_not_send"`
- `"send_live_only"`
- `"send_live_and_test"`
- `last_login_time: Optional[datetime]`
The date and time at which the user last logged in.
- `phone_number: Optional[str]`
The phone number of the user.
- `previous_emails: Optional[List[str]]`
A list of emails the user has previously had. If a user has changed their
email before, this list will be populated with all of the emails they
once had.
### Sub Organization Retrieve Users Response
- `List[SubOrganizationRetrieveUsersResponseItem]`
- `id: str`
A unique ID prefixed with `user_`.
- `email: str`
The email of the user.
- `name: str`
The name of the user.
- `organization: str`
A unique ID prefixed with `user_`.
- `pending_invite: bool`
Indicates if the user has a pending invite.
- `roles: List[str]`
The roles given to the user. Roles can be used to restrict access for
users.
- `verified_email: bool`
Indicates if the user has a verified email or not.
- `email_preferences: Optional[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.
- `"do_not_send"`
- `"send_live_only"`
- `"send_live_and_test"`
- `last_login_time: Optional[datetime]`
The date and time at which the user last logged in.
- `phone_number: Optional[str]`
The phone number of the user.
- `previous_emails: Optional[List[str]]`
A list of emails the user has previously had. If a user has changed their
email before, this list will be populated with all of the emails they
once had.
# Boxes
## Create Box
`print_mail.boxes.create(BoxCreateParams**kwargs) -> BoxCreateResponse`
**post** `/print-mail/v1/boxes`
This endpoint allows you to create a box containing up to 100 cheques.
A Box is mailed to a single destination.
To create a box. You must specify:
- `to`: The recipient (contact or contact ID)
- `from`: The sender (contact or contact ID)
- `cheques`: An array of cheques to go in the box
For each cheque You must specify:
- `to`: The recipient (contact or contact ID)
- `from`: The sender (contact or contact ID)
- `bankAccount`: The bank account ID
- `amount`: The amount to be sent
- `number`: The cheque number
### Parameters
- `cheques: Iterable[Cheque]`
The cheques to be mailed in the box. Only 100 cheques can be included in a box at a time.
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: ChequeFrom`
- `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.
- `str`
- `number: int`
The cheque number.
- `to: ChequeTo`
- `class ContactCreateWithFirstName: …`
- `class ContactCreateWithCompanyName: …`
- `str`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `from_: From`
The 'from' (sender) of the entire box. Accepts inline ContactCreate or a contactID.
- `class ContactCreateWithFirstName: …`
- `class ContactCreateWithCompanyName: …`
- `str`
- `to: To`
The recipient of this order. You can either supply the contact information inline here or provide a contact ID. PostGrid will automatically deduplicate contacts regardless of whether you provide the information inline here or call the contact creation endpoint.
- `class ContactCreateWithFirstName: …`
- `class ContactCreateWithCompanyName: …`
- `str`
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
The mailing class of this order. If not provided, automatically set to `first_class`.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `send_date: Optional[Union[str, datetime]]`
This order will transition from `ready` to `printing` on the day after this date. You can use this parameter to schedule orders for a future date.
### Returns
- `class BoxCreateResponse: …`
- `id: str`
A unique ID prefixed with box_
- `cheques: List[Cheque]`
The cheques inside this box (in read mode).
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: 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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `number: int`
The cheque number.
- `to: Contact`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `from_: Contact`
The contact of the 'from' field in read mode should be a fully expanded Contact.
- `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.
- `"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["box"]`
Always "box".
- `"box"`
- `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.
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
box = client.print_mail.boxes.create(
cheques=[{
"from": "contact_456",
"to": "contact_123",
"bank_account": "bank_abc",
"amount": 5000,
"number": 1042,
}],
from_="contact_456",
to="contact_123",
)
print(box.id)
```
#### Response
```json
{
"id": "box_123456",
"object": "box",
"description": "A sample box of cheques",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"cheques": [
{
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 12345,
"memo": "Test Memo",
"logoURL": "https://example.com/logo.png",
"messageTemplate": "Thank you!",
"number": 1001,
"mergeVariables": {
"customKey": "customValue"
}
}
],
"mailingClass": "first_class",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2025-01-01T12:00:00Z",
"updatedAt": "2025-01-02T12:00:00Z"
}
```
## List Boxes
`print_mail.boxes.list(BoxListParams**kwargs) -> SyncSkipLimit[BoxListResponse]`
**get** `/print-mail/v1/boxes`
List all boxes.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class BoxListResponse: …`
- `id: str`
A unique ID prefixed with box_
- `cheques: List[Cheque]`
The cheques inside this box (in read mode).
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: 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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `number: int`
The cheque number.
- `to: Contact`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `from_: Contact`
The contact of the 'from' field in read mode should be a fully expanded Contact.
- `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.
- `"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["box"]`
Always "box".
- `"box"`
- `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.
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.boxes.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "box_123456",
"object": "box",
"description": "A sample box of cheques",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"cheques": [
{
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 12345,
"memo": "Test Memo",
"logoURL": "https://example.com/logo.png",
"messageTemplate": "Thank you!",
"number": 1001,
"mergeVariables": {
"customKey": "customValue"
}
}
],
"mailingClass": "first_class",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2025-01-01T12:00:00Z",
"updatedAt": "2025-01-02T12:00:00Z"
}
]
}
```
## Get Box
`print_mail.boxes.retrieve(strid) -> BoxRetrieveResponse`
**get** `/print-mail/v1/boxes/{id}`
Retrieve a box by ID.
### Parameters
- `id: str`
### Returns
- `class BoxRetrieveResponse: …`
- `id: str`
A unique ID prefixed with box_
- `cheques: List[Cheque]`
The cheques inside this box (in read mode).
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: 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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `number: int`
The cheque number.
- `to: Contact`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `from_: Contact`
The contact of the 'from' field in read mode should be a fully expanded Contact.
- `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.
- `"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["box"]`
Always "box".
- `"box"`
- `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.
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
box = client.print_mail.boxes.retrieve(
"id",
)
print(box.id)
```
#### Response
```json
{
"id": "box_123456",
"object": "box",
"description": "A sample box of cheques",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"cheques": [
{
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 12345,
"memo": "Test Memo",
"logoURL": "https://example.com/logo.png",
"messageTemplate": "Thank you!",
"number": 1001,
"mergeVariables": {
"customKey": "customValue"
}
}
],
"mailingClass": "first_class",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2025-01-01T12:00:00Z",
"updatedAt": "2025-01-02T12:00:00Z"
}
```
## Cancel Box
`print_mail.boxes.delete(strid) -> BoxDeleteResponse`
**delete** `/print-mail/v1/boxes/{id}`
Cancel a box by ID (cannot be undone).
### Parameters
- `id: str`
### Returns
- `class BoxDeleteResponse: …`
- `id: str`
A unique ID prefixed with box_
- `cheques: List[Cheque]`
The cheques inside this box (in read mode).
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: 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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `number: int`
The cheque number.
- `to: Contact`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `from_: Contact`
The contact of the 'from' field in read mode should be a fully expanded Contact.
- `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.
- `"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["box"]`
Always "box".
- `"box"`
- `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.
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
box = client.print_mail.boxes.delete(
"id",
)
print(box.id)
```
#### Response
```json
{
"id": "box_123456",
"object": "box",
"description": "A sample box of cheques",
"status": "cancelled",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"cheques": [
{
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 12345,
"memo": "Test Memo",
"logoURL": "https://example.com/logo.png",
"messageTemplate": "Thank you!",
"number": 1001,
"mergeVariables": {
"customKey": "customValue"
}
}
],
"mailingClass": "first_class",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2025-01-01T12:00:00Z",
"updatedAt": "2025-01-02T12:00:00Z"
}
```
## Progress Status
`print_mail.boxes.progressions(strid) -> BoxProgressionsResponse`
**post** `/print-mail/v1/boxes/{id}/progressions`
Progresses a box's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
### Parameters
- `id: str`
### Returns
- `class BoxProgressionsResponse: …`
- `id: str`
A unique ID prefixed with box_
- `cheques: List[Cheque]`
The cheques inside this box (in read mode).
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: 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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `number: int`
The cheque number.
- `to: Contact`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `from_: Contact`
The contact of the 'from' field in read mode should be a fully expanded Contact.
- `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.
- `"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["box"]`
Always "box".
- `"box"`
- `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.
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.boxes.progressions(
"id",
)
print(response.id)
```
#### Response
```json
{
"id": "box_123456",
"object": "box",
"description": "A sample box of cheques",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"cheques": [
{
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"bankAccount": "bank_123",
"amount": 12345,
"memo": "Test Memo",
"logoURL": "https://example.com/logo.png",
"messageTemplate": "Thank you!",
"number": 1001,
"mergeVariables": {
"customKey": "customValue"
}
}
],
"mailingClass": "first_class",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2025-01-01T12:00:00Z",
"updatedAt": "2025-01-02T12:00:00Z"
}
```
## Domain Types
### Box Create Response
- `class BoxCreateResponse: …`
- `id: str`
A unique ID prefixed with box_
- `cheques: List[Cheque]`
The cheques inside this box (in read mode).
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: 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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `number: int`
The cheque number.
- `to: Contact`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `from_: Contact`
The contact of the 'from' field in read mode should be a fully expanded Contact.
- `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.
- `"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["box"]`
Always "box".
- `"box"`
- `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.
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Box List Response
- `class BoxListResponse: …`
- `id: str`
A unique ID prefixed with box_
- `cheques: List[Cheque]`
The cheques inside this box (in read mode).
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: 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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `number: int`
The cheque number.
- `to: Contact`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `from_: Contact`
The contact of the 'from' field in read mode should be a fully expanded Contact.
- `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.
- `"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["box"]`
Always "box".
- `"box"`
- `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.
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Box Retrieve Response
- `class BoxRetrieveResponse: …`
- `id: str`
A unique ID prefixed with box_
- `cheques: List[Cheque]`
The cheques inside this box (in read mode).
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: 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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `number: int`
The cheque number.
- `to: Contact`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `from_: Contact`
The contact of the 'from' field in read mode should be a fully expanded Contact.
- `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.
- `"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["box"]`
Always "box".
- `"box"`
- `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.
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Box Delete Response
- `class BoxDeleteResponse: …`
- `id: str`
A unique ID prefixed with box_
- `cheques: List[Cheque]`
The cheques inside this box (in read mode).
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: 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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `number: int`
The cheque number.
- `to: Contact`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `from_: Contact`
The contact of the 'from' field in read mode should be a fully expanded Contact.
- `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.
- `"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["box"]`
Always "box".
- `"box"`
- `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.
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
### Box Progressions Response
- `class BoxProgressionsResponse: …`
- `id: str`
A unique ID prefixed with box_
- `cheques: List[Cheque]`
The cheques inside this box (in read mode).
- `amount: int`
The amount on the cheque.
- `bank_account: str`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from_: 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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `number: int`
The cheque number.
- `to: Contact`
- `logo_url: Optional[str]`
A URL to a logo for the cheque (optional).
- `memo: Optional[str]`
The memo text on the cheque (optional).
- `merge_variables: Optional[Dict[str, object]]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `message_template: Optional[str]`
An optional message template to be printed on or with the cheque.
- `created_at: datetime`
The UTC time at which this resource was created.
- `from_: Contact`
The contact of the 'from' field in read mode should be a fully expanded Contact.
- `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.
- `"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["box"]`
Always "box".
- `"box"`
- `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.
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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]]`
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[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]`
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.
# Snap Packs
## Create Snap Pack
`print_mail.snap_packs.create(SnapPackCreateParams**kwargs) -> SnapPackCreateResponse`
**post** `/print-mail/v1/snap_packs`
Create a snap pack. You can supply one of the following:
- HTML content for the inside and outside of the snap pack
- Template IDs for the inside and outside of the snap pack
- A URL or file upload for a two-page PDF that matches the snap pack layout
### Parameters
- `from_: SnapPackCreateWithHTMLFrom`
The contact information of the sender. You can pass contact information inline here just like you can for the `to` contact.
- `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.
- `str`
- `inside_html: str`
The HTML content for the inside of the snap pack. You can supply _either_ this or `insideTemplate` but not both.
- `outside_html: str`
The HTML content for the outside of the snap pack. You can supply _either_ this or `outsideTemplate` but not both.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `to: SnapPackCreateWithHTMLTo`
The recipient of this order. You can either supply the contact information inline here or provide a contact ID. PostGrid will automatically deduplicate contacts regardless of whether you provide the information inline here or call the contact creation endpoint.
- `class ContactCreateWithFirstName: …`
- `class ContactCreateWithCompanyName: …`
- `str`
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailing_class: Optional[Literal["first_class", "standard_class", "express", 23 more]]`
The mailing class of this order. If not provided, automatically set to `first_class`.
- `"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]]`
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[Dict[str, object]]`
See the section on Metadata.
- `send_date: Optional[Union[str, datetime]]`
This order will transition from `ready` to `printing` on the day after this date. You can use this parameter to schedule orders for a future date.
### Returns
- `class SnapPackCreateResponse: …`
- `id: str`
A unique ID prefixed with snap_pack_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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["snap_pack"]`
Always `snap_pack`.
- `"snap_pack"`
- `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.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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.
- `inside_html: Optional[str]`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `inside_template: Optional[str]`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `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.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `outside_html: Optional[str]`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outside_template: Optional[str]`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `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]`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
snap_pack = client.print_mail.snap_packs.create(
from_="contact_123",
inside_html="Inside",
outside_html="Outside",
size="8.5x11_bifold_v",
to="contact_456",
)
print(snap_pack.id)
```
#### Response
```json
{
"id": "snap_pack_123456",
"object": "snap_pack",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "8.5x11_bifold_v",
"insideHTML": "Inside",
"outsideHTML": "Outside",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "usps_first_class"
}
```
## List Snap Packs
`print_mail.snap_packs.list(SnapPackListParams**kwargs) -> SyncSkipLimit[SnapPackListResponse]`
**get** `/print-mail/v1/snap_packs`
Get a list of snap packs.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class SnapPackListResponse: …`
- `id: str`
A unique ID prefixed with snap_pack_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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["snap_pack"]`
Always `snap_pack`.
- `"snap_pack"`
- `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.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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.
- `inside_html: Optional[str]`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `inside_template: Optional[str]`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `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.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `outside_html: Optional[str]`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outside_template: Optional[str]`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `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]`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.snap_packs.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "snap_pack_123456",
"object": "snap_pack",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "8.5x11_bifold_v",
"insideHTML": "Inside",
"outsideHTML": "Outside",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "usps_first_class"
}
]
}
```
## Capabilities
`print_mail.snap_packs.retrieve_capabilities(SnapPackRetrieveCapabilitiesParams**kwargs) -> SnapPackRetrieveCapabilitiesResponse`
**get** `/print-mail/v1/snap_packs/capabilities`
Provides sizes and mailing classes available for the destination.
### Parameters
- `return_country_code: str`
The country code where mail may be returned to.
- `destination_country_code: Optional[str]`
The country code of where the snap pack will be sent to.
One of `mailingList` or `destinationCountryCode` must be supplied but
not both.
- `mailing_list: Optional[str]`
Sources destination countries from the provided mailing list.
One of `mailingList` or `destinationCountryCode` must be supplied but
not both.
### Returns
- `class SnapPackRetrieveCapabilitiesResponse: …`
- `mailing_classes: List[Literal["first_class", "standard_class", "express", 23 more]]`
- `"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"`
- `sizes: List[Literal["8.5x11_bifold_v"]]`
- `"8.5x11_bifold_v"`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.snap_packs.retrieve_capabilities(
return_country_code="returnCountryCode",
)
print(response.mailing_classes)
```
#### Response
```json
{
"sizes": [
"8.5x11_bifold_v"
],
"mailingClasses": [
"express",
"usps_express_2_day"
]
}
```
## Get Snap Pack
`print_mail.snap_packs.retrieve(strid) -> SnapPackRetrieveResponse`
**get** `/print-mail/v1/snap_packs/{id}`
Retrieve a snap pack by ID.
### Parameters
- `id: str`
### Returns
- `class SnapPackRetrieveResponse: …`
- `id: str`
A unique ID prefixed with snap_pack_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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["snap_pack"]`
Always `snap_pack`.
- `"snap_pack"`
- `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.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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.
- `inside_html: Optional[str]`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `inside_template: Optional[str]`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `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.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `outside_html: Optional[str]`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outside_template: Optional[str]`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `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]`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
snap_pack = client.print_mail.snap_packs.retrieve(
"id",
)
print(snap_pack.id)
```
#### Response
```json
{
"id": "snap_pack_123456",
"object": "snap_pack",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "8.5x11_bifold_v",
"insideHTML": "Inside",
"outsideHTML": "Outside",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "usps_first_class"
}
```
## Cancel
`print_mail.snap_packs.delete(strid) -> SnapPackDeleteResponse`
**delete** `/print-mail/v1/snap_packs/{id}`
Cancel a snap pack by ID. Note that this operation cannot be undone and
that only snap packs with a status of `ready` can be cancelled.
### Parameters
- `id: str`
### Returns
- `class SnapPackDeleteResponse: …`
- `id: str`
A unique ID prefixed with snap_pack_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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["snap_pack"]`
Always `snap_pack`.
- `"snap_pack"`
- `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.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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.
- `inside_html: Optional[str]`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `inside_template: Optional[str]`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `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.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `outside_html: Optional[str]`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outside_template: Optional[str]`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `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]`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
snap_pack = client.print_mail.snap_packs.delete(
"id",
)
print(snap_pack.id)
```
#### Response
```json
{
"id": "snap_pack_123456",
"object": "snap_pack",
"status": "cancelled",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "8.5x11_bifold_v",
"insideHTML": "Inside",
"outsideHTML": "Outside",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "usps_first_class"
}
```
## Progress Status
`print_mail.snap_packs.progressions(strid) -> SnapPackProgressionsResponse`
**post** `/print-mail/v1/snap_packs/{id}/progressions`
Progresses a snap pack's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.
Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.
### Parameters
- `id: str`
### Returns
- `class SnapPackProgressionsResponse: …`
- `id: str`
A unique ID prefixed with snap_pack_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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["snap_pack"]`
Always `snap_pack`.
- `"snap_pack"`
- `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.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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.
- `inside_html: Optional[str]`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `inside_template: Optional[str]`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `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.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `outside_html: Optional[str]`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outside_template: Optional[str]`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `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]`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.snap_packs.progressions(
"id",
)
print(response.id)
```
#### Response
```json
{
"id": "snap_pack_123456",
"object": "snap_pack",
"status": "ready",
"live": false,
"to": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"from": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"size": "8.5x11_bifold_v",
"insideHTML": "Inside",
"outsideHTML": "Outside",
"sendDate": "2020-11-12T23:23:47.974Z",
"createdAt": "2020-11-12T23:23:47.974Z",
"updatedAt": "2020-11-12T23:23:47.974Z",
"mailingClass": "usps_first_class"
}
```
## Domain Types
### Snap Pack Create Response
- `class SnapPackCreateResponse: …`
- `id: str`
A unique ID prefixed with snap_pack_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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["snap_pack"]`
Always `snap_pack`.
- `"snap_pack"`
- `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.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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.
- `inside_html: Optional[str]`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `inside_template: Optional[str]`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `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.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `outside_html: Optional[str]`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outside_template: Optional[str]`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `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]`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `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.
### Snap Pack List Response
- `class SnapPackListResponse: …`
- `id: str`
A unique ID prefixed with snap_pack_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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["snap_pack"]`
Always `snap_pack`.
- `"snap_pack"`
- `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.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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.
- `inside_html: Optional[str]`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `inside_template: Optional[str]`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `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.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `outside_html: Optional[str]`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outside_template: Optional[str]`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `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]`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `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.
### Snap Pack Retrieve Capabilities Response
- `class SnapPackRetrieveCapabilitiesResponse: …`
- `mailing_classes: List[Literal["first_class", "standard_class", "express", 23 more]]`
- `"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"`
- `sizes: List[Literal["8.5x11_bifold_v"]]`
- `"8.5x11_bifold_v"`
### Snap Pack Retrieve Response
- `class SnapPackRetrieveResponse: …`
- `id: str`
A unique ID prefixed with snap_pack_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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["snap_pack"]`
Always `snap_pack`.
- `"snap_pack"`
- `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.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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.
- `inside_html: Optional[str]`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `inside_template: Optional[str]`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `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.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `outside_html: Optional[str]`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outside_template: Optional[str]`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `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]`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `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.
### Snap Pack Delete Response
- `class SnapPackDeleteResponse: …`
- `id: str`
A unique ID prefixed with snap_pack_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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["snap_pack"]`
Always `snap_pack`.
- `"snap_pack"`
- `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.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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.
- `inside_html: Optional[str]`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `inside_template: Optional[str]`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `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.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `outside_html: Optional[str]`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outside_template: Optional[str]`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `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]`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `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.
### Snap Pack Progressions Response
- `class SnapPackProgressionsResponse: …`
- `id: str`
A unique ID prefixed with snap_pack_
- `created_at: datetime`
The UTC time at which this resource was created.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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["snap_pack"]`
Always `snap_pack`.
- `"snap_pack"`
- `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.
- `size: Literal["8.5x11_bifold_v"]`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: Literal["ready", "printing", "processed_for_delivery", 2 more]`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `"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.
- `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.
- `"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.
- `inside_html: Optional[str]`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `inside_template: Optional[str]`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `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.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `outside_html: Optional[str]`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outside_template: Optional[str]`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `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]`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `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.
# Targeted List Builds
## Create Targeted List Build
`print_mail.targeted_list_builds.create(TargetedListBuildCreateParams**kwargs) -> TargetedListBuildCreateResponse`
**post** `/print-mail/v1/targeted_list_builds`
Create a new targeted list build. A quote will be generated
asynchronously based on the provided filters.
### Parameters
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: Sequence[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[Iterable[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[Iterable[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[Sequence[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[Sequence[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[Sequence[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[Iterable[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[Sequence[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[Iterable[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[Iterable[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[Iterable[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[Sequence[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
- `idempotency_key: Optional[str]`
### Returns
- `class TargetedListBuildCreateResponse: …`
A targeted list build represents a request to build a new mailing list by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
- `id: str`
A unique ID prefixed with targeted_list_build_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `organization: str`
The ID of the organization that owns this list build.
- `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `build_progress_percent: Optional[float]`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completed_at: Optional[datetime]`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmed_at: Optional[datetime]`
The UTC time at which the build was confirmed, if any.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: Optional[List[Error]]`
Any errors encountered while generating a quote or building the list.
- `message: str`
A human-readable message describing the error.
- `type: Literal["not_enough_info_to_quote", "insufficient_credits", "internal_service_error"]`
Type of error encountered while generating a quote or building the list.
- `"not_enough_info_to_quote"`
- `"insufficient_credits"`
- `"internal_service_error"`
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailing_list: Optional[str]`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `preview_records: Optional[List[PreviewRecord]]`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formatted_address: str`
The masked, comma-joined formatted address of the contact.
- `name: str`
The masked name of the contact or business.
- `quote: Optional[Quote]`
Details of the quote generated for a targeted list build.
- `count: int`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generated_at: datetime`
The UTC time at which the quote was generated.
- `price_per_contact_cents: float`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: List[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[List[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[List[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[List[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[List[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[List[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[List[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[List[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[List[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[List[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[List[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[List[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
targeted_list_build = client.print_mail.targeted_list_builds.create(
description="Q1 prospecting list",
limit=1000,
metadata={
"campaign": "q1_prospecting"
},
us_companies={
"postal_codes": ["10001", "10002"],
"industries": ["software"],
"employee_count": [10, 500],
},
)
print(targeted_list_build.id)
```
#### Response
```json
{
"id": "targeted_list_build_123",
"live": false,
"description": "Q1 prospecting list",
"metadata": {
"campaign": "q1_prospecting"
},
"createdAt": "2026-01-05T10:00:00Z",
"updatedAt": "2026-01-05T10:01:30Z",
"organization": "organization_123",
"status": "quote_ready",
"usCompanies": {
"postalCodes": [
"10001",
"10002"
],
"industries": [
"software"
],
"employeeCount": [
10,
500
]
},
"limit": 1000,
"quote": {
"generatedAt": "2026-01-05T10:01:30Z",
"count": 1000,
"pricePerContactCents": 11.98
},
"previewRecords": [
{
"name": "Acm***",
"formattedAddress": "12** Main St, New York, NY, 100**"
}
],
"errors": []
}
```
## List Targeted List Builds
`print_mail.targeted_list_builds.list(TargetedListBuildListParams**kwargs) -> SyncSkipLimit[TargetedListBuildListResponse]`
**get** `/print-mail/v1/targeted_list_builds`
Retrieve a paginated list of targeted list builds for the authenticated
organization, ordered from most recently updated to least recently
updated.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class TargetedListBuildListResponse: …`
A targeted list build represents a request to build a new mailing list by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
- `id: str`
A unique ID prefixed with targeted_list_build_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `organization: str`
The ID of the organization that owns this list build.
- `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `build_progress_percent: Optional[float]`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completed_at: Optional[datetime]`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmed_at: Optional[datetime]`
The UTC time at which the build was confirmed, if any.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: Optional[List[Error]]`
Any errors encountered while generating a quote or building the list.
- `message: str`
A human-readable message describing the error.
- `type: Literal["not_enough_info_to_quote", "insufficient_credits", "internal_service_error"]`
Type of error encountered while generating a quote or building the list.
- `"not_enough_info_to_quote"`
- `"insufficient_credits"`
- `"internal_service_error"`
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailing_list: Optional[str]`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `preview_records: Optional[List[PreviewRecord]]`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formatted_address: str`
The masked, comma-joined formatted address of the contact.
- `name: str`
The masked name of the contact or business.
- `quote: Optional[Quote]`
Details of the quote generated for a targeted list build.
- `count: int`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generated_at: datetime`
The UTC time at which the quote was generated.
- `price_per_contact_cents: float`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: List[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[List[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[List[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[List[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[List[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[List[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[List[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[List[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[List[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[List[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[List[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[List[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.targeted_list_builds.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"totalCount": 1,
"skip": 0,
"limit": 10,
"data": [
{
"id": "targeted_list_build_123",
"live": false,
"description": "Q1 prospecting list",
"metadata": {
"campaign": "q1_prospecting"
},
"createdAt": "2026-01-05T10:00:00Z",
"updatedAt": "2026-01-05T10:01:30Z",
"organization": "organization_123",
"status": "quote_ready",
"usCompanies": {
"postalCodes": [
"10001",
"10002"
],
"industries": [
"software"
],
"employeeCount": [
10,
500
]
},
"limit": 1000,
"quote": {
"generatedAt": "2026-01-05T10:01:30Z",
"count": 1000,
"pricePerContactCents": 11.98
},
"previewRecords": [
{
"name": "Acm***",
"formattedAddress": "12** Main St, New York, NY, 100**"
}
],
"errors": []
}
]
}
```
## Get Targeted List Build
`print_mail.targeted_list_builds.retrieve(strid) -> TargetedListBuildRetrieveResponse`
**get** `/print-mail/v1/targeted_list_builds/{id}`
Retrieve a specific targeted list build by its ID.
### Parameters
- `id: str`
### Returns
- `class TargetedListBuildRetrieveResponse: …`
A targeted list build represents a request to build a new mailing list by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
- `id: str`
A unique ID prefixed with targeted_list_build_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `organization: str`
The ID of the organization that owns this list build.
- `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `build_progress_percent: Optional[float]`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completed_at: Optional[datetime]`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmed_at: Optional[datetime]`
The UTC time at which the build was confirmed, if any.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: Optional[List[Error]]`
Any errors encountered while generating a quote or building the list.
- `message: str`
A human-readable message describing the error.
- `type: Literal["not_enough_info_to_quote", "insufficient_credits", "internal_service_error"]`
Type of error encountered while generating a quote or building the list.
- `"not_enough_info_to_quote"`
- `"insufficient_credits"`
- `"internal_service_error"`
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailing_list: Optional[str]`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `preview_records: Optional[List[PreviewRecord]]`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formatted_address: str`
The masked, comma-joined formatted address of the contact.
- `name: str`
The masked name of the contact or business.
- `quote: Optional[Quote]`
Details of the quote generated for a targeted list build.
- `count: int`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generated_at: datetime`
The UTC time at which the quote was generated.
- `price_per_contact_cents: float`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: List[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[List[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[List[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[List[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[List[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[List[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[List[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[List[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[List[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[List[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[List[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[List[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
targeted_list_build = client.print_mail.targeted_list_builds.retrieve(
"id",
)
print(targeted_list_build.id)
```
#### Response
```json
{
"id": "targeted_list_build_123",
"live": false,
"description": "Q1 prospecting list",
"metadata": {
"campaign": "q1_prospecting"
},
"createdAt": "2026-01-05T10:00:00Z",
"updatedAt": "2026-01-05T10:01:30Z",
"organization": "organization_123",
"status": "quote_ready",
"usCompanies": {
"postalCodes": [
"10001",
"10002"
],
"industries": [
"software"
],
"employeeCount": [
10,
500
]
},
"limit": 1000,
"quote": {
"generatedAt": "2026-01-05T10:01:30Z",
"count": 1000,
"pricePerContactCents": 11.98
},
"previewRecords": [
{
"name": "Acm***",
"formattedAddress": "12** Main St, New York, NY, 100**"
}
],
"errors": []
}
```
## Update Targeted List Build
`print_mail.targeted_list_builds.update(strid, TargetedListBuildUpdateParams**kwargs) -> TargetedListBuildUpdateResponse`
**post** `/print-mail/v1/targeted_list_builds/{id}`
Update an existing targeted list build. Only builds that have not yet
been confirmed may be updated. Updating the filters or `limit` will
reset the build's status back to `generating_quote` and a new quote
will be generated.
### Parameters
- `id: str`
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: Sequence[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[Iterable[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[Iterable[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[Sequence[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[Sequence[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[Sequence[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[Iterable[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[Sequence[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[Iterable[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[Iterable[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[Iterable[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[Sequence[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
### Returns
- `class TargetedListBuildUpdateResponse: …`
A targeted list build represents a request to build a new mailing list by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
- `id: str`
A unique ID prefixed with targeted_list_build_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `organization: str`
The ID of the organization that owns this list build.
- `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `build_progress_percent: Optional[float]`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completed_at: Optional[datetime]`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmed_at: Optional[datetime]`
The UTC time at which the build was confirmed, if any.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: Optional[List[Error]]`
Any errors encountered while generating a quote or building the list.
- `message: str`
A human-readable message describing the error.
- `type: Literal["not_enough_info_to_quote", "insufficient_credits", "internal_service_error"]`
Type of error encountered while generating a quote or building the list.
- `"not_enough_info_to_quote"`
- `"insufficient_credits"`
- `"internal_service_error"`
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailing_list: Optional[str]`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `preview_records: Optional[List[PreviewRecord]]`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formatted_address: str`
The masked, comma-joined formatted address of the contact.
- `name: str`
The masked name of the contact or business.
- `quote: Optional[Quote]`
Details of the quote generated for a targeted list build.
- `count: int`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generated_at: datetime`
The UTC time at which the quote was generated.
- `price_per_contact_cents: float`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: List[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[List[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[List[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[List[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[List[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[List[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[List[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[List[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[List[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[List[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[List[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[List[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
targeted_list_build = client.print_mail.targeted_list_builds.update(
id="id",
limit=2000,
us_companies={
"postal_codes": ["10001", "10002", "10003"],
"industries": ["software", "fintech"],
"employee_count": [50, 1000],
},
)
print(targeted_list_build.id)
```
#### Response
```json
{
"id": "targeted_list_build_123",
"live": false,
"description": "Q1 prospecting list",
"metadata": {
"campaign": "q1_prospecting"
},
"createdAt": "2026-01-05T10:00:00Z",
"updatedAt": "2026-01-05T10:01:30Z",
"organization": "organization_123",
"status": "quote_ready",
"usCompanies": {
"postalCodes": [
"10001",
"10002"
],
"industries": [
"software"
],
"employeeCount": [
10,
500
]
},
"limit": 1000,
"quote": {
"generatedAt": "2026-01-05T10:01:30Z",
"count": 1000,
"pricePerContactCents": 11.98
},
"previewRecords": [
{
"name": "Acm***",
"formattedAddress": "12** Main St, New York, NY, 100**"
}
],
"errors": []
}
```
## Delete Targeted List Build
`print_mail.targeted_list_builds.delete(strid) -> TargetedListBuildDeleteResponse`
**delete** `/print-mail/v1/targeted_list_builds/{id}`
Delete a targeted list build. List builds can only be deleted before
they have been confirmed — once a build has transitioned to
`creating_list` or `completed` it cannot be deleted.
### Parameters
- `id: str`
### Returns
- `class TargetedListBuildDeleteResponse: …`
- `id: str`
A unique ID prefixed with targeted_list_build_
- `deleted: Literal[true]`
- `true`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
targeted_list_build = client.print_mail.targeted_list_builds.delete(
"id",
)
print(targeted_list_build.id)
```
#### Response
```json
{
"id": "targeted_list_build_123",
"deleted": true
}
```
## Confirm Targeted List Build
`print_mail.targeted_list_builds.confirm(strid) -> TargetedListBuildConfirmResponse`
**post** `/print-mail/v1/targeted_list_builds/{id}/confirm`
Confirm a targeted list build whose quote is ready. This deducts the
appropriate amount of list build credits from the organization (in
live mode) and kicks off the asynchronous creation of the underlying
mailing list.
### Parameters
- `id: str`
### Returns
- `class TargetedListBuildConfirmResponse: …`
A targeted list build represents a request to build a new mailing list by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
- `id: str`
A unique ID prefixed with targeted_list_build_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `organization: str`
The ID of the organization that owns this list build.
- `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `build_progress_percent: Optional[float]`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completed_at: Optional[datetime]`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmed_at: Optional[datetime]`
The UTC time at which the build was confirmed, if any.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: Optional[List[Error]]`
Any errors encountered while generating a quote or building the list.
- `message: str`
A human-readable message describing the error.
- `type: Literal["not_enough_info_to_quote", "insufficient_credits", "internal_service_error"]`
Type of error encountered while generating a quote or building the list.
- `"not_enough_info_to_quote"`
- `"insufficient_credits"`
- `"internal_service_error"`
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailing_list: Optional[str]`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `preview_records: Optional[List[PreviewRecord]]`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formatted_address: str`
The masked, comma-joined formatted address of the contact.
- `name: str`
The masked name of the contact or business.
- `quote: Optional[Quote]`
Details of the quote generated for a targeted list build.
- `count: int`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generated_at: datetime`
The UTC time at which the quote was generated.
- `price_per_contact_cents: float`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: List[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[List[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[List[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[List[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[List[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[List[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[List[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[List[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[List[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[List[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[List[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[List[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.targeted_list_builds.confirm(
"id",
)
print(response.id)
```
#### Response
```json
{
"id": "targeted_list_build_123",
"live": false,
"description": "Q1 prospecting list",
"metadata": {
"campaign": "q1_prospecting"
},
"createdAt": "2026-01-05T10:00:00Z",
"updatedAt": "2026-01-05T10:05:00Z",
"organization": "organization_123",
"status": "creating_list",
"usCompanies": {
"postalCodes": [
"10001",
"10002"
],
"industries": [
"software"
],
"employeeCount": [
10,
500
]
},
"limit": 1000,
"quote": {
"generatedAt": "2026-01-05T10:01:30Z",
"count": 1000,
"pricePerContactCents": 11.98
},
"confirmedAt": "2026-01-05T10:05:00Z",
"buildProgressPercent": 0,
"errors": []
}
```
## Domain Types
### Targeted List Build Create Response
- `class TargetedListBuildCreateResponse: …`
A targeted list build represents a request to build a new mailing list by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
- `id: str`
A unique ID prefixed with targeted_list_build_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `organization: str`
The ID of the organization that owns this list build.
- `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `build_progress_percent: Optional[float]`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completed_at: Optional[datetime]`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmed_at: Optional[datetime]`
The UTC time at which the build was confirmed, if any.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: Optional[List[Error]]`
Any errors encountered while generating a quote or building the list.
- `message: str`
A human-readable message describing the error.
- `type: Literal["not_enough_info_to_quote", "insufficient_credits", "internal_service_error"]`
Type of error encountered while generating a quote or building the list.
- `"not_enough_info_to_quote"`
- `"insufficient_credits"`
- `"internal_service_error"`
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailing_list: Optional[str]`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `preview_records: Optional[List[PreviewRecord]]`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formatted_address: str`
The masked, comma-joined formatted address of the contact.
- `name: str`
The masked name of the contact or business.
- `quote: Optional[Quote]`
Details of the quote generated for a targeted list build.
- `count: int`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generated_at: datetime`
The UTC time at which the quote was generated.
- `price_per_contact_cents: float`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: List[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[List[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[List[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[List[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[List[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[List[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[List[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[List[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[List[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[List[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[List[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[List[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
### Targeted List Build List Response
- `class TargetedListBuildListResponse: …`
A targeted list build represents a request to build a new mailing list by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
- `id: str`
A unique ID prefixed with targeted_list_build_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `organization: str`
The ID of the organization that owns this list build.
- `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `build_progress_percent: Optional[float]`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completed_at: Optional[datetime]`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmed_at: Optional[datetime]`
The UTC time at which the build was confirmed, if any.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: Optional[List[Error]]`
Any errors encountered while generating a quote or building the list.
- `message: str`
A human-readable message describing the error.
- `type: Literal["not_enough_info_to_quote", "insufficient_credits", "internal_service_error"]`
Type of error encountered while generating a quote or building the list.
- `"not_enough_info_to_quote"`
- `"insufficient_credits"`
- `"internal_service_error"`
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailing_list: Optional[str]`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `preview_records: Optional[List[PreviewRecord]]`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formatted_address: str`
The masked, comma-joined formatted address of the contact.
- `name: str`
The masked name of the contact or business.
- `quote: Optional[Quote]`
Details of the quote generated for a targeted list build.
- `count: int`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generated_at: datetime`
The UTC time at which the quote was generated.
- `price_per_contact_cents: float`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: List[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[List[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[List[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[List[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[List[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[List[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[List[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[List[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[List[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[List[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[List[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[List[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
### Targeted List Build Retrieve Response
- `class TargetedListBuildRetrieveResponse: …`
A targeted list build represents a request to build a new mailing list by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
- `id: str`
A unique ID prefixed with targeted_list_build_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `organization: str`
The ID of the organization that owns this list build.
- `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `build_progress_percent: Optional[float]`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completed_at: Optional[datetime]`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmed_at: Optional[datetime]`
The UTC time at which the build was confirmed, if any.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: Optional[List[Error]]`
Any errors encountered while generating a quote or building the list.
- `message: str`
A human-readable message describing the error.
- `type: Literal["not_enough_info_to_quote", "insufficient_credits", "internal_service_error"]`
Type of error encountered while generating a quote or building the list.
- `"not_enough_info_to_quote"`
- `"insufficient_credits"`
- `"internal_service_error"`
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailing_list: Optional[str]`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `preview_records: Optional[List[PreviewRecord]]`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formatted_address: str`
The masked, comma-joined formatted address of the contact.
- `name: str`
The masked name of the contact or business.
- `quote: Optional[Quote]`
Details of the quote generated for a targeted list build.
- `count: int`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generated_at: datetime`
The UTC time at which the quote was generated.
- `price_per_contact_cents: float`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: List[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[List[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[List[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[List[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[List[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[List[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[List[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[List[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[List[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[List[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[List[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[List[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
### Targeted List Build Update Response
- `class TargetedListBuildUpdateResponse: …`
A targeted list build represents a request to build a new mailing list by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
- `id: str`
A unique ID prefixed with targeted_list_build_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `organization: str`
The ID of the organization that owns this list build.
- `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `build_progress_percent: Optional[float]`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completed_at: Optional[datetime]`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmed_at: Optional[datetime]`
The UTC time at which the build was confirmed, if any.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: Optional[List[Error]]`
Any errors encountered while generating a quote or building the list.
- `message: str`
A human-readable message describing the error.
- `type: Literal["not_enough_info_to_quote", "insufficient_credits", "internal_service_error"]`
Type of error encountered while generating a quote or building the list.
- `"not_enough_info_to_quote"`
- `"insufficient_credits"`
- `"internal_service_error"`
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailing_list: Optional[str]`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `preview_records: Optional[List[PreviewRecord]]`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formatted_address: str`
The masked, comma-joined formatted address of the contact.
- `name: str`
The masked name of the contact or business.
- `quote: Optional[Quote]`
Details of the quote generated for a targeted list build.
- `count: int`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generated_at: datetime`
The UTC time at which the quote was generated.
- `price_per_contact_cents: float`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: List[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[List[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[List[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[List[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[List[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[List[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[List[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[List[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[List[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[List[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[List[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[List[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
### Targeted List Build Delete Response
- `class TargetedListBuildDeleteResponse: …`
- `id: str`
A unique ID prefixed with targeted_list_build_
- `deleted: Literal[true]`
- `true`
### Targeted List Build Confirm Response
- `class TargetedListBuildConfirmResponse: …`
A targeted list build represents a request to build a new mailing list by
targeting US consumers or companies matching the provided filters. Once
created, a quote is generated asynchronously. After reviewing the quote
and preview records, you may confirm the build, which kicks off the
creation of the underlying mailing list.
- `id: str`
A unique ID prefixed with targeted_list_build_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `organization: str`
The ID of the organization that owns this list build.
- `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `build_progress_percent: Optional[float]`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completed_at: Optional[datetime]`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmed_at: Optional[datetime]`
The UTC time at which the build was confirmed, if any.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: Optional[List[Error]]`
Any errors encountered while generating a quote or building the list.
- `message: str`
A human-readable message describing the error.
- `type: Literal["not_enough_info_to_quote", "insufficient_credits", "internal_service_error"]`
Type of error encountered while generating a quote or building the list.
- `"not_enough_info_to_quote"`
- `"insufficient_credits"`
- `"internal_service_error"`
- `limit: Optional[int]`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailing_list: Optional[str]`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
- `preview_records: Optional[List[PreviewRecord]]`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formatted_address: str`
The masked, comma-joined formatted address of the contact.
- `name: str`
The masked name of the contact or business.
- `quote: Optional[Quote]`
Details of the quote generated for a targeted list build.
- `count: int`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generated_at: datetime`
The UTC time at which the quote was generated.
- `price_per_contact_cents: float`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `us_companies: Optional[UsCompanies]`
Filters used to target US companies (B2B) when building a list.
- `postal_codes: List[str]`
Required list of five-digit US ZIP codes to target.
- `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employee_count: Optional[List[int]]`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `founded_year: Optional[List[int]]`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: Optional[List[str]]`
Filter by free-form industry names (see the autocomplete endpoint).
- `naics_codes: Optional[List[str]]`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: Optional[List[str]]`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `us_consumers: Optional[UsConsumers]`
Filters used to target US consumers (B2C) when building a list.
The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
mutually exclusive — you may supply at most one of them.
- `age_range: Optional[List[int]]`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `city_states: Optional[List[str]]`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: Optional[Literal["male", "female"]]`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `home_value_range: Optional[List[int]]`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `income_range: Optional[List[int]]`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `num_children_range: Optional[List[int]]`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 23 more]]]`
Filter by occupation classification.
- `"professional_technical"`
- `"administration_management"`
- `"sales_service"`
- `"clerical_white_collar"`
- `"craftsmen_blue_collar"`
- `"student"`
- `"homemaker"`
- `"retired"`
- `"farmer"`
- `"military"`
- `"religious"`
- `"self_employed"`
- `"self_employed_professional_technical"`
- `"self_employed_administration_management"`
- `"self_employed_sales_service"`
- `"self_employed_clerical_white_collar"`
- `"self_employed_craftsmen_blue_collar"`
- `"self_employed_student"`
- `"self_employed_homemaker"`
- `"self_employed_retired"`
- `"self_employed_other"`
- `"educator"`
- `"financial_professional"`
- `"legal_professional"`
- `"medical_professional"`
- `"other"`
- `zip_codes: Optional[List[str]]`
A list of five-digit US ZIP codes to target.
- `zip_codes_around: Optional[UsConsumersZipCodesAround]`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radius_in_miles: float`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zip_code: str`
The five-digit ZIP code at the center of the search circle.
# Filters
## Autocomplete Filter Values
`print_mail.targeted_list_builds.filters.autocomplete(FilterAutocompleteParams**kwargs) -> FilterAutocompleteResponse`
**post** `/print-mail/v1/targeted_list_builds/filters/autocomplete`
Return a list of autocomplete suggestions for a given filter field
(currently only `industry` is supported). Useful when building a UI
around the `industries` company filter.
### Parameters
- `field: Literal["industry"]`
A field that can be autocompleted when configuring list build filters.
- `"industry"`
- `size: Optional[int]`
Maximum number of suggestions to return. Between 1 and 100.
Defaults to 25 if omitted.
- `text: Optional[str]`
Optional text prefix to narrow the autocomplete suggestions.
### Returns
- `class FilterAutocompleteResponse: …`
The list of suggestions returned by an autocomplete query.
- `data: List[Data]`
- `type: Literal["industry"]`
A field that can be autocompleted when configuring list build filters.
- `"industry"`
- `value: str`
The suggested value (e.g., an industry name).
- `object: Literal["list"]`
- `"list"`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.targeted_list_builds.filters.autocomplete(
field="industry",
size=5,
text="soft",
)
print(response.data)
```
#### Response
```json
{
"object": "list",
"data": [
{
"value": "software",
"type": "industry"
},
{
"value": "software development",
"type": "industry"
}
]
}
```
## Domain Types
### Filter Autocomplete Response
- `class FilterAutocompleteResponse: …`
The list of suggestions returned by an autocomplete query.
- `data: List[Data]`
- `type: Literal["industry"]`
A field that can be autocompleted when configuring list build filters.
- `"industry"`
- `value: str`
The suggested value (e.g., an industry name).
- `object: Literal["list"]`
- `"list"`
# Template Editor Sessions
## Create Session
`print_mail.template_editor_sessions.create(TemplateEditorSessionCreateParams**kwargs) -> TemplateEditorSessionCreateResponse`
**post** `/print-mail/v1/template_editor_sessions`
Create a Template Editor Session.
Note that if no `backURL` is supplied, PostGrid removes the Back button
from the editor page. This is ideal for when you `iframe` the editor.
### Parameters
- `template: str`
ID of the underlying template that this edits.
- `back_url: Optional[str]`
The URL supplied when this editor session was created.
- `styles: Optional[Styles]`
Style overrides for the template editor session.
- `canvas: Optional[StylesCanvas]`
Style overrides for the template editor canvas.
- `background_color: Optional[str]`
The canvas background color.
- `panel_text: Optional[StylesPanelText]`
Style overrides for template editor panel text.
- `color: Optional[str]`
The panel text color.
- `save_button: Optional[StylesSaveButton]`
Style overrides for the template editor save button.
- `background_color: Optional[str]`
The save button background color.
- `text_color: Optional[str]`
The save button text color.
- `title: Optional[str]`
The title supplied when this editor session was created.
- `trackers: Optional[Union[Literal["all", "none"], Sequence[str]]]`
Controls which Trackers are displayed in the template editor session.
- `Literal["all", "none"]`
- `"all"`
- `"none"`
- `Sequence[str]`
### Returns
- `class TemplateEditorSessionCreateResponse: …`
- `id: str`
A unique ID prefixed with `template_editor_session_`.
- `created_at: datetime`
The UTC time at which this session was created.
- `live: bool`
`true` if this is a live mode session else `false`.
- `object: Literal["template_editor_session"]`
Always `template_editor_session`.
- `"template_editor_session"`
- `template: str`
ID of the underlying template that this edits.
- `url: str`
A URL that can be iframed or redirected to for editing the template.
- `back_url: Optional[str]`
The URL supplied when this editor session was created.
- `styles: Optional[Styles]`
Style overrides for the template editor session.
- `canvas: Optional[StylesCanvas]`
Style overrides for the template editor canvas.
- `background_color: Optional[str]`
The canvas background color.
- `panel_text: Optional[StylesPanelText]`
Style overrides for template editor panel text.
- `color: Optional[str]`
The panel text color.
- `save_button: Optional[StylesSaveButton]`
Style overrides for the template editor save button.
- `background_color: Optional[str]`
The save button background color.
- `text_color: Optional[str]`
The save button text color.
- `title: Optional[str]`
The title supplied when this editor session was created.
- `trackers: Optional[Union[Literal["all", "none"], List[str], null]]`
Controls which Trackers are displayed in the template editor session.
- `Literal["all", "none"]`
- `"all"`
- `"none"`
- `List[str]`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
template_editor_session = client.print_mail.template_editor_sessions.create(
template="template_eYxcbMKPZEZPk71ZJPA6Yz",
back_url="https://postgrid.com",
title="My Editor Session",
trackers=["tracker_123456789abcdefghijklmnopqrstuvwxyz"],
)
print(template_editor_session.id)
```
#### Response
```json
{
"id": "template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c",
"object": "template_editor_session",
"live": false,
"template": "template_eYxcbMKPZEZPk71ZJPA6Yz",
"backURL": "https://postgrid.com",
"title": "My Editor Session",
"trackers": [
"tracker_123456789abcdefghijklmnopqrstuvwxyz"
],
"url": "https://dashboard.postgrid.com/embed/template_editor_sessions/template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c",
"createdAt": "2023-07-05T19:36:01.369Z"
}
```
## List Sessions
`print_mail.template_editor_sessions.list(TemplateEditorSessionListParams**kwargs) -> SyncSkipLimit[TemplateEditorSessionListResponse]`
**get** `/print-mail/v1/template_editor_sessions`
Retrieve a paginated list of Template Editor Sessions.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class TemplateEditorSessionListResponse: …`
- `id: str`
A unique ID prefixed with `template_editor_session_`.
- `created_at: datetime`
The UTC time at which this session was created.
- `live: bool`
`true` if this is a live mode session else `false`.
- `object: Literal["template_editor_session"]`
Always `template_editor_session`.
- `"template_editor_session"`
- `template: str`
ID of the underlying template that this edits.
- `url: str`
A URL that can be iframed or redirected to for editing the template.
- `back_url: Optional[str]`
The URL supplied when this editor session was created.
- `styles: Optional[Styles]`
Style overrides for the template editor session.
- `canvas: Optional[StylesCanvas]`
Style overrides for the template editor canvas.
- `background_color: Optional[str]`
The canvas background color.
- `panel_text: Optional[StylesPanelText]`
Style overrides for template editor panel text.
- `color: Optional[str]`
The panel text color.
- `save_button: Optional[StylesSaveButton]`
Style overrides for the template editor save button.
- `background_color: Optional[str]`
The save button background color.
- `text_color: Optional[str]`
The save button text color.
- `title: Optional[str]`
The title supplied when this editor session was created.
- `trackers: Optional[Union[Literal["all", "none"], List[str], null]]`
Controls which Trackers are displayed in the template editor session.
- `Literal["all", "none"]`
- `"all"`
- `"none"`
- `List[str]`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.template_editor_sessions.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"limit": 10,
"skip": 0,
"totalCount": 1,
"data": [
{
"id": "template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c",
"object": "template_editor_session",
"live": false,
"template": "template_eYxcbMKPZEZPk71ZJPA6Yz",
"backURL": "https://postgrid.com",
"title": "My Editor Session",
"trackers": "none",
"url": "https://dashboard.postgrid.com/embed/template_editor_sessions/template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c",
"createdAt": "2023-07-05T19:36:01.369Z"
}
]
}
```
## Delete Session
`print_mail.template_editor_sessions.delete(strid) -> TemplateEditorSessionDeleteResponse`
**delete** `/print-mail/v1/template_editor_sessions/{id}`
Delete a Template Editor Session by ID.
### Parameters
- `id: str`
### Returns
- `class TemplateEditorSessionDeleteResponse: …`
- `id: str`
A unique ID prefixed with `template_editor_session_`.
- `deleted: Literal[true]`
- `true`
- `object: Literal["template_editor_session"]`
Always `template_editor_session`.
- `"template_editor_session"`
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
template_editor_session = client.print_mail.template_editor_sessions.delete(
"id",
)
print(template_editor_session.id)
```
#### Response
```json
{
"id": "template_editor_session_vmb3aXRJFzHb4oNRP2XMUZiTTBDtC91CSgQeqUrQfhSqq5P9wAGpmX5UkftueTubMN",
"object": "template_editor_session",
"deleted": true
}
```
## Domain Types
### Template Editor Session Create Response
- `class TemplateEditorSessionCreateResponse: …`
- `id: str`
A unique ID prefixed with `template_editor_session_`.
- `created_at: datetime`
The UTC time at which this session was created.
- `live: bool`
`true` if this is a live mode session else `false`.
- `object: Literal["template_editor_session"]`
Always `template_editor_session`.
- `"template_editor_session"`
- `template: str`
ID of the underlying template that this edits.
- `url: str`
A URL that can be iframed or redirected to for editing the template.
- `back_url: Optional[str]`
The URL supplied when this editor session was created.
- `styles: Optional[Styles]`
Style overrides for the template editor session.
- `canvas: Optional[StylesCanvas]`
Style overrides for the template editor canvas.
- `background_color: Optional[str]`
The canvas background color.
- `panel_text: Optional[StylesPanelText]`
Style overrides for template editor panel text.
- `color: Optional[str]`
The panel text color.
- `save_button: Optional[StylesSaveButton]`
Style overrides for the template editor save button.
- `background_color: Optional[str]`
The save button background color.
- `text_color: Optional[str]`
The save button text color.
- `title: Optional[str]`
The title supplied when this editor session was created.
- `trackers: Optional[Union[Literal["all", "none"], List[str], null]]`
Controls which Trackers are displayed in the template editor session.
- `Literal["all", "none"]`
- `"all"`
- `"none"`
- `List[str]`
### Template Editor Session List Response
- `class TemplateEditorSessionListResponse: …`
- `id: str`
A unique ID prefixed with `template_editor_session_`.
- `created_at: datetime`
The UTC time at which this session was created.
- `live: bool`
`true` if this is a live mode session else `false`.
- `object: Literal["template_editor_session"]`
Always `template_editor_session`.
- `"template_editor_session"`
- `template: str`
ID of the underlying template that this edits.
- `url: str`
A URL that can be iframed or redirected to for editing the template.
- `back_url: Optional[str]`
The URL supplied when this editor session was created.
- `styles: Optional[Styles]`
Style overrides for the template editor session.
- `canvas: Optional[StylesCanvas]`
Style overrides for the template editor canvas.
- `background_color: Optional[str]`
The canvas background color.
- `panel_text: Optional[StylesPanelText]`
Style overrides for template editor panel text.
- `color: Optional[str]`
The panel text color.
- `save_button: Optional[StylesSaveButton]`
Style overrides for the template editor save button.
- `background_color: Optional[str]`
The save button background color.
- `text_color: Optional[str]`
The save button text color.
- `title: Optional[str]`
The title supplied when this editor session was created.
- `trackers: Optional[Union[Literal["all", "none"], List[str], null]]`
Controls which Trackers are displayed in the template editor session.
- `Literal["all", "none"]`
- `"all"`
- `"none"`
- `List[str]`
### Template Editor Session Delete Response
- `class TemplateEditorSessionDeleteResponse: …`
- `id: str`
A unique ID prefixed with `template_editor_session_`.
- `deleted: Literal[true]`
- `true`
- `object: Literal["template_editor_session"]`
Always `template_editor_session`.
- `"template_editor_session"`
# Virtual Mailboxes
## Create Virtual Mailbox
`print_mail.virtual_mailboxes.create(VirtualMailboxCreateParams**kwargs) -> VirtualMailboxCreateResponse`
**post** `/print-mail/v1/virtual_mailboxes`
Creates a new virtual mailbox.
In live mode, the virtual mailbox will be pending assignment and cannot
be used until it has been assigned and activated by our team. You will be
notified via email once the virtual mailbox has been activated.
In test mode, the virtual mailbox will be activated immediately upon
creation.
### Parameters
- `country_code: Literal["US"]`
All of the supported countries for virtual mailboxes.
- `"US"`
- `capabilities: Optional[Capabilities]`
The capabilities the virtual mailbox should support.
- `envelope_scans: bool`
If the virtual mailbox should support envelope scans or not.
- `forward_mail_to: Optional[CapabilitiesForwardMailTo]`
A contact ID or contact object.
- `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.
- `str`
### Returns
- `class VirtualMailboxCreateResponse: …`
The virtual mailbox object.
- `id: str`
A unique ID prefixed with virtual_mailbox_
- `capabilities: Capabilities`
All of the capabilities a virtual mailbox may have.
- `envelope_scans: bool`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forward_mail_to: Optional[Contact]`
A contact to forward any returned mail to.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `country_code: Literal["US"]`
All of the supported countries for virtual mailboxes.
- `"US"`
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox"]`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: Literal["active", "pending_assignment"]`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
virtual_mailbox = client.print_mail.virtual_mailboxes.create(
country_code="US",
capabilities={
"envelope_scans": True,
"forward_mail_to": "contact_pxd7wnnD1xY6H6etKNvjb4",
},
)
print(virtual_mailbox.id)
```
#### Response
```json
{
"id": "virtual_mailbox_abcdefg123456890",
"object": "virtual_mailbox",
"live": true,
"status": "pending_assignment",
"capabilities": {
"forwardMailTo": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"envelopeScans": true
},
"countryCode": "US",
"createdAt": "2025-11-01T15:08:41.052Z",
"updatedAt": "2025-11-01T15:08:41.052Z"
}
```
## List Virtual Mailboxes
`print_mail.virtual_mailboxes.list(VirtualMailboxListParams**kwargs) -> SyncSkipLimit[VirtualMailboxListResponse]`
**get** `/print-mail/v1/virtual_mailboxes`
Lists virtual mailboxes. You can use the `skip`, `limit`, and `search`
query parameters to refine the list.
### Parameters
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class VirtualMailboxListResponse: …`
The virtual mailbox object.
- `id: str`
A unique ID prefixed with virtual_mailbox_
- `capabilities: Capabilities`
All of the capabilities a virtual mailbox may have.
- `envelope_scans: bool`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forward_mail_to: Optional[Contact]`
A contact to forward any returned mail to.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `country_code: Literal["US"]`
All of the supported countries for virtual mailboxes.
- `"US"`
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox"]`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: Literal["active", "pending_assignment"]`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.virtual_mailboxes.list()
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"totalCount": 1,
"skip": 0,
"limit": 10,
"data": [
{
"id": "virtual_mailbox_abcdefg123456890",
"object": "virtual_mailbox",
"live": true,
"status": "pending_assignment",
"capabilities": {
"forwardMailTo": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"envelopeScans": true
},
"countryCode": "US",
"createdAt": "2025-11-01T15:08:41.052Z",
"updatedAt": "2025-11-01T15:08:41.052Z"
}
]
}
```
## Retrieve Virtual Mailbox
`print_mail.virtual_mailboxes.retrieve(strid) -> VirtualMailboxRetrieveResponse`
**get** `/print-mail/v1/virtual_mailboxes/{id}`
Retrieve Virtual Mailbox
### Parameters
- `id: str`
### Returns
- `class VirtualMailboxRetrieveResponse: …`
The virtual mailbox object.
- `id: str`
A unique ID prefixed with virtual_mailbox_
- `capabilities: Capabilities`
All of the capabilities a virtual mailbox may have.
- `envelope_scans: bool`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forward_mail_to: Optional[Contact]`
A contact to forward any returned mail to.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `country_code: Literal["US"]`
All of the supported countries for virtual mailboxes.
- `"US"`
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox"]`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: Literal["active", "pending_assignment"]`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
virtual_mailbox = client.print_mail.virtual_mailboxes.retrieve(
"id",
)
print(virtual_mailbox.id)
```
#### Response
```json
{
"id": "virtual_mailbox_abcdefg123456890",
"object": "virtual_mailbox",
"live": true,
"status": "pending_assignment",
"capabilities": {
"forwardMailTo": {
"id": "contact_pxd7wnnD1xY6H6etKNvjb4",
"object": "contact",
"live": false,
"companyName": "PostGrid",
"addressLine1": "90 CANAL ST STE 600",
"city": "BOSTON",
"provinceOrState": "MA",
"postalOrZip": "90210-1234",
"countryCode": "US",
"skipVerification": false,
"forceVerifiedStatus": false,
"addressStatus": "verified",
"createdAt": "2022-02-16T15:08:41.052Z",
"updatedAt": "2022-02-16T15:08:41.052Z"
},
"envelopeScans": true
},
"countryCode": "US",
"createdAt": "2025-11-01T15:08:41.052Z",
"updatedAt": "2025-11-01T15:08:41.052Z"
}
```
## Retrieve Physical Address
`print_mail.virtual_mailboxes.retrieve_address(strid) -> VirtualMailboxRetrieveAddressResponse`
**get** `/print-mail/v1/virtual_mailboxes/{id}/address`
Retrieves the physical address of the virtual mailbox.
### Parameters
- `id: str`
### Returns
- `class VirtualMailboxRetrieveAddressResponse: …`
The address information for a mailbox.
- `address_line1: str`
The address line 1 of the mailbox.
- `country_code: Literal["US"]`
All of the supported countries for virtual mailboxes.
- `"US"`
- `address_line2: Optional[str]`
The address line 2 of the mailbox.
- `city: Optional[str]`
The city of the mailbox.
- `postal_or_zip: Optional[str]`
The postal or ZIP code of the mailbox.
- `province_or_state: Optional[str]`
The province or state of the mailbox.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
response = client.print_mail.virtual_mailboxes.retrieve_address(
"id",
)
print(response.address_line1)
```
#### Response
```json
{
"addressLine1": "145 Mulberry st",
"city": "New York",
"provinceOrState": "NY",
"postalOrZip": "10013",
"countryCode": "US"
}
```
## Domain Types
### Virtual Mailbox Create Response
- `class VirtualMailboxCreateResponse: …`
The virtual mailbox object.
- `id: str`
A unique ID prefixed with virtual_mailbox_
- `capabilities: Capabilities`
All of the capabilities a virtual mailbox may have.
- `envelope_scans: bool`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forward_mail_to: Optional[Contact]`
A contact to forward any returned mail to.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `country_code: Literal["US"]`
All of the supported countries for virtual mailboxes.
- `"US"`
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox"]`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: Literal["active", "pending_assignment"]`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Virtual Mailbox List Response
- `class VirtualMailboxListResponse: …`
The virtual mailbox object.
- `id: str`
A unique ID prefixed with virtual_mailbox_
- `capabilities: Capabilities`
All of the capabilities a virtual mailbox may have.
- `envelope_scans: bool`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forward_mail_to: Optional[Contact]`
A contact to forward any returned mail to.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `country_code: Literal["US"]`
All of the supported countries for virtual mailboxes.
- `"US"`
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox"]`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: Literal["active", "pending_assignment"]`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Virtual Mailbox Retrieve Response
- `class VirtualMailboxRetrieveResponse: …`
The virtual mailbox object.
- `id: str`
A unique ID prefixed with virtual_mailbox_
- `capabilities: Capabilities`
All of the capabilities a virtual mailbox may have.
- `envelope_scans: bool`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forward_mail_to: Optional[Contact]`
A contact to forward any returned mail to.
- `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`.
- `"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.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["contact"]`
Always `contact`.
- `"contact"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
- `country_code: Literal["US"]`
All of the supported countries for virtual mailboxes.
- `"US"`
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox"]`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: Literal["active", "pending_assignment"]`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `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.
### Virtual Mailbox Retrieve Address Response
- `class VirtualMailboxRetrieveAddressResponse: …`
The address information for a mailbox.
- `address_line1: str`
The address line 1 of the mailbox.
- `country_code: Literal["US"]`
All of the supported countries for virtual mailboxes.
- `"US"`
- `address_line2: Optional[str]`
The address line 2 of the mailbox.
- `city: Optional[str]`
The city of the mailbox.
- `postal_or_zip: Optional[str]`
The postal or ZIP code of the mailbox.
- `province_or_state: Optional[str]`
The province or state of the mailbox.
# Items
## List Virtual Mailbox Items
`print_mail.virtual_mailboxes.items.list(strid, ItemListParams**kwargs) -> SyncSkipLimit[ItemListResponse]`
**get** `/print-mail/v1/virtual_mailboxes/{id}/items`
Lists items for a virtual mailbox.
### Parameters
- `id: str`
- `limit: Optional[int]`
- `search: Optional[str]`
You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.
- `skip: Optional[int]`
### Returns
- `class ItemListResponse: …`
The virtual mailbox item object.
- `id: str`
A unique ID prefixed with virtual_mailbox_item_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox_item"]`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `virtual_mailbox: str`
The ID of the virtual mailbox associated with this item.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `file_url: Optional[str]`
A URL of the envelope scan PDF.
- `matched_letter: Optional[str]`
The ID of the letter this item was matched to.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
page = client.print_mail.virtual_mailboxes.items.list(
id="id",
)
page = page.data[0]
print(page.id)
```
#### Response
```json
{
"object": "list",
"totalCount": 1,
"skip": 0,
"limit": 10,
"data": [
{
"id": "virtual_mailbox_item_abcdefg123456890",
"object": "virtual_mailbox_item",
"live": true,
"virtualMailbox": "virtual_mailbox_abcdefg123456890",
"fileURL": "https://postgrid.com",
"matchedLetter": "letter_abcdef1234567890",
"createdAt": "2025-11-01T15:08:41.052Z",
"updatedAt": "2025-11-01T15:08:41.052Z"
}
]
}
```
## Create Test Virtual Mailbox Item
`print_mail.virtual_mailboxes.items.create(strid, ItemCreateParams**kwargs) -> ItemCreateResponse`
**post** `/print-mail/v1/virtual_mailboxes/{id}/items`
Create a test item for a virtual mailbox. This is only available in test
mode, an error will be returned if you attempt this call in live mode.
### Parameters
- `id: str`
- `description: Optional[str]`
The description of the item.
- `matched_letter: Optional[str]`
The ID of a letter to match this test item to.
- `metadata: Optional[Dict[str, object]]`
The metadata of the item.
### Returns
- `class ItemCreateResponse: …`
The virtual mailbox item object.
- `id: str`
A unique ID prefixed with virtual_mailbox_item_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox_item"]`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `virtual_mailbox: str`
The ID of the virtual mailbox associated with this item.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `file_url: Optional[str]`
A URL of the envelope scan PDF.
- `matched_letter: Optional[str]`
The ID of the letter this item was matched to.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
item = client.print_mail.virtual_mailboxes.items.create(
id="id",
matched_letter="letter_abcdef1234567890",
)
print(item.id)
```
#### Response
```json
{
"id": "virtual_mailbox_item_abcdefg123456890",
"object": "virtual_mailbox_item",
"live": false,
"virtualMailbox": "virtual_mailbox_abcdefg123456890",
"fileURL": "https://postgrid.com",
"matchedLetter": "letter_abcdef1234567890",
"createdAt": "2025-11-01T15:08:41.052Z",
"updatedAt": "2025-11-01T15:08:41.052Z"
}
```
## Retrieve Virtual Mailbox Item
`print_mail.virtual_mailboxes.items.retrieve(stritem_id, ItemRetrieveParams**kwargs) -> ItemRetrieveResponse`
**get** `/print-mail/v1/virtual_mailboxes/{id}/items/{itemID}`
Retrieves a single item for a virtual mailbox.
### Parameters
- `id: str`
- `item_id: str`
### Returns
- `class ItemRetrieveResponse: …`
The virtual mailbox item object.
- `id: str`
A unique ID prefixed with virtual_mailbox_item_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox_item"]`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `virtual_mailbox: str`
The ID of the virtual mailbox associated with this item.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `file_url: Optional[str]`
A URL of the envelope scan PDF.
- `matched_letter: Optional[str]`
The ID of the letter this item was matched to.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
### Example
```python
import os
from postgrid import PostGrid
client = PostGrid(
print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted
)
item = client.print_mail.virtual_mailboxes.items.retrieve(
item_id="itemID",
id="id",
)
print(item.id)
```
#### Response
```json
{
"id": "virtual_mailbox_item_abcdefg123456890",
"object": "virtual_mailbox_item",
"live": true,
"virtualMailbox": "virtual_mailbox_abcdefg123456890",
"fileURL": "https://postgrid.com",
"matchedLetter": "letter_abcdef1234567890",
"createdAt": "2025-11-01T15:08:41.052Z",
"updatedAt": "2025-11-01T15:08:41.052Z"
}
```
## Domain Types
### Item List Response
- `class ItemListResponse: …`
The virtual mailbox item object.
- `id: str`
A unique ID prefixed with virtual_mailbox_item_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox_item"]`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `virtual_mailbox: str`
The ID of the virtual mailbox associated with this item.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `file_url: Optional[str]`
A URL of the envelope scan PDF.
- `matched_letter: Optional[str]`
The ID of the letter this item was matched to.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
### Item Create Response
- `class ItemCreateResponse: …`
The virtual mailbox item object.
- `id: str`
A unique ID prefixed with virtual_mailbox_item_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox_item"]`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `virtual_mailbox: str`
The ID of the virtual mailbox associated with this item.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `file_url: Optional[str]`
A URL of the envelope scan PDF.
- `matched_letter: Optional[str]`
The ID of the letter this item was matched to.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.
### Item Retrieve Response
- `class ItemRetrieveResponse: …`
The virtual mailbox item object.
- `id: str`
A unique ID prefixed with virtual_mailbox_item_
- `created_at: datetime`
The UTC time at which this resource was created.
- `live: bool`
`true` if this is a live mode resource else `false`.
- `object: Literal["virtual_mailbox_item"]`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updated_at: datetime`
The UTC time at which this resource was last updated.
- `virtual_mailbox: str`
The ID of the virtual mailbox associated with this item.
- `description: Optional[str]`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `file_url: Optional[str]`
A URL of the envelope scan PDF.
- `matched_letter: Optional[str]`
The ID of the letter this item was matched to.
- `metadata: Optional[Dict[str, object]]`
See the section on Metadata.