# Print Mail
# Contacts
## Create 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._
### Body Parameters
- `contact_create: ContactCreate`
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `firstName: string`
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `companyName: string`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
### Returns
- `Contact object { id, addressLine1, addressStatus, 20 more }`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/contacts \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"addressLine1": "addressLine1",
"countryCode": "countryCode",
"firstName": "firstName"
}'
```
#### 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
**get** `/print-mail/v1/contacts`
Get a list of contacts.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/contacts \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/contacts/{id}`
Retrieve a contact.
### Path Parameters
- `id: string`
### Returns
- `Contact object { id, addressLine1, addressStatus, 20 more }`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/contacts/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**delete** `/print-mail/v1/contacts/{id}`
Delete a contact. Note that this will not affect orders that were sent to this contact.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with contact_
- `deleted: true`
- `true`
- `object: "contact"`
Always `contact`.
- `"contact"`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/contacts/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "contact_sqF12lZ1VlBb",
"deleted": true,
"object": "contact"
}
```
## Domain Types
### Contact
- `Contact object { id, addressLine1, addressStatus, 20 more }`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
### Contact Create
- `ContactCreate = ContactCreateWithFirstName or ContactCreateWithCompanyName`
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `firstName: string`
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `companyName: string`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
### Contact Create With Company Name
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `companyName: string`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
### Contact Create With First Name
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `firstName: string`
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
### Contact Delete Response
- `ContactDeleteResponse object { id, deleted, object }`
- `id: string`
A unique ID prefixed with contact_
- `deleted: true`
- `true`
- `object: "contact"`
Always `contact`.
- `"contact"`
# Templates
## Create 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.
### Body Parameters
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content of this template.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Returns
- `Template object { id, createdAt, live, 5 more }`
- `id: string`
A unique ID prefixed with template_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "template"`
Always `template`.
- `"template"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content of this template.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/templates \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
**get** `/print-mail/v1/templates`
Get a list of templates.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of Template`
- `id: string`
A unique ID prefixed with template_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "template"`
Always `template`.
- `"template"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content of this template.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/templates \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/templates/{id}`
Retrieve a template by ID.
### Path Parameters
- `id: string`
### Returns
- `Template object { id, createdAt, live, 5 more }`
- `id: string`
A unique ID prefixed with template_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "template"`
Always `template`.
- `"template"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content of this template.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/templates/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**post** `/print-mail/v1/templates/{id}`
Update a template by ID.
### Path Parameters
- `id: string`
### Body Parameters
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content of this template.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Returns
- `Template object { id, createdAt, live, 5 more }`
- `id: string`
A unique ID prefixed with template_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "template"`
Always `template`.
- `"template"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content of this template.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/templates/$ID \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
**delete** `/print-mail/v1/templates/{id}`
Delete a template by ID. Note that this operation cannot be undone.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with template_
- `deleted: true`
- `true`
- `object: "template"`
Always `template`.
- `"template"`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/templates/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "template_sqF12lZ1VlBb",
"deleted": true,
"object": "template"
}
```
## Domain Types
### Template
- `Template object { id, createdAt, live, 5 more }`
- `id: string`
A unique ID prefixed with template_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "template"`
Always `template`.
- `"template"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content of this template.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Template Delete Response
- `TemplateDeleteResponse object { id, deleted, object }`
- `id: string`
A unique ID prefixed with template_
- `deleted: true`
- `true`
- `object: "template"`
Always `template`.
- `"template"`
# Trackers
## Create Tracker
**post** `/print-mail/v1/trackers`
Create a Tracker.
### Body Parameters
- `redirectURLTemplate: string`
The base template for URLs generated by this Tracker.
- `urlExpireAfterDays: 30 or 60 or 90 or 2 more`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Returns
- `id: string`
A unique ID prefixed with tracker_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "tracker"`
Always `tracker`.
- `"tracker"`
- `redirectURLTemplate: string`
The base template for URLs generated by this Tracker.
- `uniqueVisitCount: number`
The unique number of interactions the Tracker has had.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `urlExpireAfterDays: 30 or 60 or 90 or 2 more`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visitCount: number`
The total number of interactions the Tracker has had.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/trackers \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"redirectURLTemplate": "https://postgrid.com?name={{to.firstName}}",
"urlExpireAfterDays": 30
}'
```
#### 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
**get** `/print-mail/v1/trackers`
Retrieve a paginated list of Trackers.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of object { id, createdAt, live, 8 more }`
- `id: string`
A unique ID prefixed with tracker_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "tracker"`
Always `tracker`.
- `"tracker"`
- `redirectURLTemplate: string`
The base template for URLs generated by this Tracker.
- `uniqueVisitCount: number`
The unique number of interactions the Tracker has had.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `urlExpireAfterDays: 30 or 60 or 90 or 2 more`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visitCount: number`
The total number of interactions the Tracker has had.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/trackers \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**post** `/print-mail/v1/trackers/{id}`
Update a Tracker by ID.
### Path Parameters
- `id: string`
### Body Parameters
- `redirectURLTemplate: string`
The base template for URLs generated by this Tracker.
- `urlExpireAfterDays: 30 or 60 or 90 or 2 more`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Returns
- `id: string`
A unique ID prefixed with tracker_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "tracker"`
Always `tracker`.
- `"tracker"`
- `redirectURLTemplate: string`
The base template for URLs generated by this Tracker.
- `uniqueVisitCount: number`
The unique number of interactions the Tracker has had.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `urlExpireAfterDays: 30 or 60 or 90 or 2 more`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visitCount: number`
The total number of interactions the Tracker has had.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/trackers/$ID \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"redirectURLTemplate": "https://postgrid.com?firstName={{to.firstName}}",
"urlExpireAfterDays": 90
}'
```
#### 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
**get** `/print-mail/v1/trackers/{id}`
Retrieve a Tracker by ID.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with tracker_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "tracker"`
Always `tracker`.
- `"tracker"`
- `redirectURLTemplate: string`
The base template for URLs generated by this Tracker.
- `uniqueVisitCount: number`
The unique number of interactions the Tracker has had.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `urlExpireAfterDays: 30 or 60 or 90 or 2 more`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visitCount: number`
The total number of interactions the Tracker has had.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/trackers/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**delete** `/print-mail/v1/trackers/{id}`
Delete a Tracker by ID. Note that this operation cannot be undone.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with tracker_
- `deleted: true`
- `true`
- `object: "tracker"`
Always `tracker`.
- `"tracker"`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/trackers/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
"object": "tracker",
"deleted": true
}
```
## List Tracker Visits
**get** `/print-mail/v1/trackers/{id}/visits`
Retrieve a paginated list of visits for a Tracker.
### Path Parameters
- `id: string`
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of object { id, createdAt, device, 6 more }`
- `id: string`
A unique ID prefixed with `tracker_visit_`.
- `createdAt: string`
The UTC time at which this visit was created.
- `device: string`
The type of device associated with the visit.
- `ipAddress: string`
The IP address associated with the visit.
- `live: boolean`
Indicates if the visit was used in a live order or not.
- `object: "tracker_visit"`
Always `tracker_visit`.
- `"tracker_visit"`
- `orderID: string`
The ID of the order where the interaction occurred.
- `tracker: string`
The ID of the tracker related to this visit.
- `updatedAt: string`
The UTC time at which this visit was last updated.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/trackers/$ID/visits \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
- `TrackerCreateResponse object { id, createdAt, live, 8 more }`
- `id: string`
A unique ID prefixed with tracker_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "tracker"`
Always `tracker`.
- `"tracker"`
- `redirectURLTemplate: string`
The base template for URLs generated by this Tracker.
- `uniqueVisitCount: number`
The unique number of interactions the Tracker has had.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `urlExpireAfterDays: 30 or 60 or 90 or 2 more`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visitCount: number`
The total number of interactions the Tracker has had.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Tracker List Response
- `TrackerListResponse object { id, createdAt, live, 8 more }`
- `id: string`
A unique ID prefixed with tracker_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "tracker"`
Always `tracker`.
- `"tracker"`
- `redirectURLTemplate: string`
The base template for URLs generated by this Tracker.
- `uniqueVisitCount: number`
The unique number of interactions the Tracker has had.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `urlExpireAfterDays: 30 or 60 or 90 or 2 more`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visitCount: number`
The total number of interactions the Tracker has had.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Tracker Update Response
- `TrackerUpdateResponse object { id, createdAt, live, 8 more }`
- `id: string`
A unique ID prefixed with tracker_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "tracker"`
Always `tracker`.
- `"tracker"`
- `redirectURLTemplate: string`
The base template for URLs generated by this Tracker.
- `uniqueVisitCount: number`
The unique number of interactions the Tracker has had.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `urlExpireAfterDays: 30 or 60 or 90 or 2 more`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visitCount: number`
The total number of interactions the Tracker has had.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Tracker Retrieve Response
- `TrackerRetrieveResponse object { id, createdAt, live, 8 more }`
- `id: string`
A unique ID prefixed with tracker_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "tracker"`
Always `tracker`.
- `"tracker"`
- `redirectURLTemplate: string`
The base template for URLs generated by this Tracker.
- `uniqueVisitCount: number`
The unique number of interactions the Tracker has had.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `urlExpireAfterDays: 30 or 60 or 90 or 2 more`
The number of days generated Tracker URLs remain valid.
- `30`
- `60`
- `90`
- `180`
- `365`
- `visitCount: number`
The total number of interactions the Tracker has had.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Tracker Delete Response
- `TrackerDeleteResponse object { id, deleted, object }`
- `id: string`
A unique ID prefixed with tracker_
- `deleted: true`
- `true`
- `object: "tracker"`
Always `tracker`.
- `"tracker"`
### Tracker Retrieve Visits Response
- `TrackerRetrieveVisitsResponse object { id, createdAt, device, 6 more }`
- `id: string`
A unique ID prefixed with `tracker_visit_`.
- `createdAt: string`
The UTC time at which this visit was created.
- `device: string`
The type of device associated with the visit.
- `ipAddress: string`
The IP address associated with the visit.
- `live: boolean`
Indicates if the visit was used in a live order or not.
- `object: "tracker_visit"`
Always `tracker_visit`.
- `"tracker_visit"`
- `orderID: string`
The ID of the order where the interaction occurred.
- `tracker: string`
The ID of the tracker related to this visit.
- `updatedAt: string`
The UTC time at which this visit was last updated.
# Letters
## Create 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
### Body Parameters
- `body: object { from, html, to, 15 more } or object { from, template, to, 15 more } or object { from, pdf, to, 15 more }`
- `LetterCreateWithHTML object { from, html, to, 15 more }`
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `firstName: string`
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `companyName: string`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `string`
- `html: string`
The HTML content for the letter. You can supply _either_ this or `template` but not both.
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: optional boolean`
Indicates if the letter is in color.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `doubleSided: optional boolean`
Indicates if the letter is double-sided.
- `envelope: optional string`
The envelope (ID) for the letter. You can either specify a custom envelope ID or use the default `standard` envelope.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
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`.
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforatedPage: optional 1`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plasticCard: optional PlasticCard`
Model representing a plastic card.
- `size: "standard"`
Enum representing the size of the plastic card.
- `"standard"`
- `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }`
Model representing a double-sided plastic card.
- `backHTML: optional string`
The HTML content for the back side of the double-sided plastic card.
- `backTemplate: optional string`
The template ID for the back side of the double-sided plastic card.
- `frontHTML: optional string`
The HTML content for the front side of the double-sided plastic card.
- `frontTemplate: optional string`
The template ID for the front side of the double-sided plastic card.
- `pdf: optional string`
A URL pointing to a PDF file for the double-sided plastic card or the file itself.
- `singleSided: optional object { html, pdf, template }`
Model representing a single-sided plastic card.
- `html: optional string`
The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`.
- `pdf: optional string`
A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.
- `template: optional string`
The template ID for the single-sided plastic card.
- `returnEnvelope: optional string`
The return envelope (ID) sent out with the letter, if any.
- `sendDate: optional string`
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"`
- `LetterCreateWithTemplate object { from, template, to, 15 more }`
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `template: string`
The template ID for the letter. You can supply _either_ this or `html` but not both.
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `color: optional boolean`
Indicates if the letter is in color.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `doubleSided: optional boolean`
Indicates if the letter is double-sided.
- `envelope: optional string`
The envelope (ID) for the letter. You can either specify a custom envelope ID or use the default `standard` envelope.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
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`.
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforatedPage: optional 1`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plasticCard: optional PlasticCard`
Model representing a plastic card.
- `returnEnvelope: optional string`
The return envelope (ID) sent out with the letter, if any.
- `sendDate: optional string`
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.
- `LetterCreateWithPdf object { from, pdf, to, 15 more }`
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `pdf: string`
A URL pointing to a PDF file for the letter or the PDF file itself.
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `color: optional boolean`
Indicates if the letter is in color.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `doubleSided: optional boolean`
Indicates if the letter is double-sided.
- `envelope: optional string`
The envelope (ID) for the letter. You can either specify a custom envelope ID or use the default `standard` envelope.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
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`.
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforatedPage: optional 1`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plasticCard: optional PlasticCard`
Model representing a plastic card.
- `returnEnvelope: optional string`
The return envelope (ID) sent out with the letter, if any.
- `sendDate: optional string`
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.
### Returns
- `Letter object { id, addressPlacement, color, 30 more }`
- `id: string`
A unique ID prefixed with letter_
- `addressPlacement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `color: boolean`
Indicates if the letter is in color.
- `createdAt: string`
The UTC time at which this resource was created.
- `doubleSided: boolean`
Indicates if the letter is double-sided.
- `envelope: string`
The envelope (ID) for the letter or the default `standard` envelope.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "letter"`
Always `letter`.
- `"letter"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content for the letter. You can supply _either_ this or `template` but not both.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
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`.
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdfWorkflowRun: optional string`
The ID of the PDF workflow run that created the letter, if any.
- `perforatedPage: optional 1`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plasticCard: optional PlasticCard`
Model representing a plastic card.
- `size: "standard"`
Enum representing the size of the plastic card.
- `"standard"`
- `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }`
Model representing a double-sided plastic card.
- `backHTML: optional string`
The HTML content for the back side of the double-sided plastic card.
- `backTemplate: optional string`
The template ID for the back side of the double-sided plastic card.
- `frontHTML: optional string`
The HTML content for the front side of the double-sided plastic card.
- `frontTemplate: optional string`
The template ID for the front side of the double-sided plastic card.
- `pdf: optional string`
A URL pointing to a PDF file for the double-sided plastic card or the file itself.
- `singleSided: optional object { html, pdf, template }`
Model representing a single-sided plastic card.
- `html: optional string`
The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`.
- `pdf: optional string`
A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.
- `template: optional string`
The template ID for the single-sided plastic card.
- `returnEnvelope: optional string`
The return envelope (ID) sent out with the letter, if any.
- `template: optional string`
The template ID used for the letter. You can supply _either_ this or `html` but not both.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/letters \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"from": {
"addressLine1": "addressLine1",
"countryCode": "countryCode",
"firstName": "firstName"
},
"html": "html",
"to": {
"addressLine1": "addressLine1",
"countryCode": "countryCode",
"firstName": "firstName"
}
}'
```
#### 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
**get** `/print-mail/v1/letters`
Get a list of letters.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of Letter`
- `id: string`
A unique ID prefixed with letter_
- `addressPlacement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `color: boolean`
Indicates if the letter is in color.
- `createdAt: string`
The UTC time at which this resource was created.
- `doubleSided: boolean`
Indicates if the letter is double-sided.
- `envelope: string`
The envelope (ID) for the letter or the default `standard` envelope.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "letter"`
Always `letter`.
- `"letter"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content for the letter. You can supply _either_ this or `template` but not both.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
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`.
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdfWorkflowRun: optional string`
The ID of the PDF workflow run that created the letter, if any.
- `perforatedPage: optional 1`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plasticCard: optional PlasticCard`
Model representing a plastic card.
- `size: "standard"`
Enum representing the size of the plastic card.
- `"standard"`
- `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }`
Model representing a double-sided plastic card.
- `backHTML: optional string`
The HTML content for the back side of the double-sided plastic card.
- `backTemplate: optional string`
The template ID for the back side of the double-sided plastic card.
- `frontHTML: optional string`
The HTML content for the front side of the double-sided plastic card.
- `frontTemplate: optional string`
The template ID for the front side of the double-sided plastic card.
- `pdf: optional string`
A URL pointing to a PDF file for the double-sided plastic card or the file itself.
- `singleSided: optional object { html, pdf, template }`
Model representing a single-sided plastic card.
- `html: optional string`
The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`.
- `pdf: optional string`
A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.
- `template: optional string`
The template ID for the single-sided plastic card.
- `returnEnvelope: optional string`
The return envelope (ID) sent out with the letter, if any.
- `template: optional string`
The template ID used for the letter. You can supply _either_ this or `html` but not both.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/letters \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/letters/{id}`
Retrieve a letter by ID.
### Path Parameters
- `id: string`
### Returns
- `Letter object { id, addressPlacement, color, 30 more }`
- `id: string`
A unique ID prefixed with letter_
- `addressPlacement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `color: boolean`
Indicates if the letter is in color.
- `createdAt: string`
The UTC time at which this resource was created.
- `doubleSided: boolean`
Indicates if the letter is double-sided.
- `envelope: string`
The envelope (ID) for the letter or the default `standard` envelope.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "letter"`
Always `letter`.
- `"letter"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content for the letter. You can supply _either_ this or `template` but not both.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
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`.
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdfWorkflowRun: optional string`
The ID of the PDF workflow run that created the letter, if any.
- `perforatedPage: optional 1`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plasticCard: optional PlasticCard`
Model representing a plastic card.
- `size: "standard"`
Enum representing the size of the plastic card.
- `"standard"`
- `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }`
Model representing a double-sided plastic card.
- `backHTML: optional string`
The HTML content for the back side of the double-sided plastic card.
- `backTemplate: optional string`
The template ID for the back side of the double-sided plastic card.
- `frontHTML: optional string`
The HTML content for the front side of the double-sided plastic card.
- `frontTemplate: optional string`
The template ID for the front side of the double-sided plastic card.
- `pdf: optional string`
A URL pointing to a PDF file for the double-sided plastic card or the file itself.
- `singleSided: optional object { html, pdf, template }`
Model representing a single-sided plastic card.
- `html: optional string`
The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`.
- `pdf: optional string`
A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.
- `template: optional string`
The template ID for the single-sided plastic card.
- `returnEnvelope: optional string`
The return envelope (ID) sent out with the letter, if any.
- `template: optional string`
The template ID used for the letter. You can supply _either_ this or `html` but not both.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/letters/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**delete** `/print-mail/v1/letters/{id}`
Cancel a letter by ID. Note that this operation cannot be undone.
### Path Parameters
- `id: string`
### Returns
- `Letter object { id, addressPlacement, color, 30 more }`
- `id: string`
A unique ID prefixed with letter_
- `addressPlacement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `color: boolean`
Indicates if the letter is in color.
- `createdAt: string`
The UTC time at which this resource was created.
- `doubleSided: boolean`
Indicates if the letter is double-sided.
- `envelope: string`
The envelope (ID) for the letter or the default `standard` envelope.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "letter"`
Always `letter`.
- `"letter"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content for the letter. You can supply _either_ this or `template` but not both.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
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`.
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdfWorkflowRun: optional string`
The ID of the PDF workflow run that created the letter, if any.
- `perforatedPage: optional 1`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plasticCard: optional PlasticCard`
Model representing a plastic card.
- `size: "standard"`
Enum representing the size of the plastic card.
- `"standard"`
- `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }`
Model representing a double-sided plastic card.
- `backHTML: optional string`
The HTML content for the back side of the double-sided plastic card.
- `backTemplate: optional string`
The template ID for the back side of the double-sided plastic card.
- `frontHTML: optional string`
The HTML content for the front side of the double-sided plastic card.
- `frontTemplate: optional string`
The template ID for the front side of the double-sided plastic card.
- `pdf: optional string`
A URL pointing to a PDF file for the double-sided plastic card or the file itself.
- `singleSided: optional object { html, pdf, template }`
Model representing a single-sided plastic card.
- `html: optional string`
The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`.
- `pdf: optional string`
A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.
- `template: optional string`
The template ID for the single-sided plastic card.
- `returnEnvelope: optional string`
The return envelope (ID) sent out with the letter, if any.
- `template: optional string`
The template ID used for the letter. You can supply _either_ this or `html` but not both.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/letters/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with letter_
- `object: string`
- `url: string`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/letters/$ID/url \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Body Parameters
- `note: string`
### Returns
- `Letter object { id, addressPlacement, color, 30 more }`
- `id: string`
A unique ID prefixed with letter_
- `addressPlacement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `color: boolean`
Indicates if the letter is in color.
- `createdAt: string`
The UTC time at which this resource was created.
- `doubleSided: boolean`
Indicates if the letter is double-sided.
- `envelope: string`
The envelope (ID) for the letter or the default `standard` envelope.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "letter"`
Always `letter`.
- `"letter"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content for the letter. You can supply _either_ this or `template` but not both.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
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`.
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdfWorkflowRun: optional string`
The ID of the PDF workflow run that created the letter, if any.
- `perforatedPage: optional 1`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plasticCard: optional PlasticCard`
Model representing a plastic card.
- `size: "standard"`
Enum representing the size of the plastic card.
- `"standard"`
- `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }`
Model representing a double-sided plastic card.
- `backHTML: optional string`
The HTML content for the back side of the double-sided plastic card.
- `backTemplate: optional string`
The template ID for the back side of the double-sided plastic card.
- `frontHTML: optional string`
The HTML content for the front side of the double-sided plastic card.
- `frontTemplate: optional string`
The template ID for the front side of the double-sided plastic card.
- `pdf: optional string`
A URL pointing to a PDF file for the double-sided plastic card or the file itself.
- `singleSided: optional object { html, pdf, template }`
Model representing a single-sided plastic card.
- `html: optional string`
The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`.
- `pdf: optional string`
A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.
- `template: optional string`
The template ID for the single-sided plastic card.
- `returnEnvelope: optional string`
The return envelope (ID) sent out with the letter, if any.
- `template: optional string`
The template ID used for the letter. You can supply _either_ this or `html` but not both.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/letters/$ID/cancellation \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"note": "Cancelling this letter"
}'
```
#### 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
**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`.
### Path Parameters
- `id: string`
### Returns
- `Letter object { id, addressPlacement, color, 30 more }`
- `id: string`
A unique ID prefixed with letter_
- `addressPlacement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `color: boolean`
Indicates if the letter is in color.
- `createdAt: string`
The UTC time at which this resource was created.
- `doubleSided: boolean`
Indicates if the letter is double-sided.
- `envelope: string`
The envelope (ID) for the letter or the default `standard` envelope.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "letter"`
Always `letter`.
- `"letter"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content for the letter. You can supply _either_ this or `template` but not both.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
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`.
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdfWorkflowRun: optional string`
The ID of the PDF workflow run that created the letter, if any.
- `perforatedPage: optional 1`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plasticCard: optional PlasticCard`
Model representing a plastic card.
- `size: "standard"`
Enum representing the size of the plastic card.
- `"standard"`
- `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }`
Model representing a double-sided plastic card.
- `backHTML: optional string`
The HTML content for the back side of the double-sided plastic card.
- `backTemplate: optional string`
The template ID for the back side of the double-sided plastic card.
- `frontHTML: optional string`
The HTML content for the front side of the double-sided plastic card.
- `frontTemplate: optional string`
The template ID for the front side of the double-sided plastic card.
- `pdf: optional string`
A URL pointing to a PDF file for the double-sided plastic card or the file itself.
- `singleSided: optional object { html, pdf, template }`
Model representing a single-sided plastic card.
- `html: optional string`
The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`.
- `pdf: optional string`
A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.
- `template: optional string`
The template ID for the single-sided plastic card.
- `returnEnvelope: optional string`
The return envelope (ID) sent out with the letter, if any.
- `template: optional string`
The template ID used for the letter. You can supply _either_ this or `html` but not both.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/letters/$ID/progressions \
-X POST \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
- `AddressPlacement = "top_first_page" or "insert_blank_page"`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
### Attached Pdf
- `AttachedPdf object { file, placement }`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
### Letter
- `Letter object { id, addressPlacement, color, 30 more }`
- `id: string`
A unique ID prefixed with letter_
- `addressPlacement: AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `color: boolean`
Indicates if the letter is in color.
- `createdAt: string`
The UTC time at which this resource was created.
- `doubleSided: boolean`
Indicates if the letter is double-sided.
- `envelope: string`
The envelope (ID) for the letter or the default `standard` envelope.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "letter"`
Always `letter`.
- `"letter"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `html: optional string`
The HTML content for the letter. You can supply _either_ this or `template` but not both.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
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`.
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `pdfWorkflowRun: optional string`
The ID of the PDF workflow run that created the letter, if any.
- `perforatedPage: optional 1`
If specified, indicates which letter page is perforated. Currently, only the first page can be perforated.
- `1`
- `plasticCard: optional PlasticCard`
Model representing a plastic card.
- `size: "standard"`
Enum representing the size of the plastic card.
- `"standard"`
- `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }`
Model representing a double-sided plastic card.
- `backHTML: optional string`
The HTML content for the back side of the double-sided plastic card.
- `backTemplate: optional string`
The template ID for the back side of the double-sided plastic card.
- `frontHTML: optional string`
The HTML content for the front side of the double-sided plastic card.
- `frontTemplate: optional string`
The template ID for the front side of the double-sided plastic card.
- `pdf: optional string`
A URL pointing to a PDF file for the double-sided plastic card or the file itself.
- `singleSided: optional object { html, pdf, template }`
Model representing a single-sided plastic card.
- `html: optional string`
The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`.
- `pdf: optional string`
A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.
- `template: optional string`
The template ID for the single-sided plastic card.
- `returnEnvelope: optional string`
The return envelope (ID) sent out with the letter, if any.
- `template: optional string`
The template ID used for the letter. You can supply _either_ this or `html` but not both.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
If a PDF was uploaded for the letter, this will contain the signed link to the uploaded PDF.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Letter Size
- `LetterSize = "us_letter" or "a4"`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
### Plastic Card
- `PlasticCard object { size, doubleSided, singleSided }`
Model representing a plastic card.
- `size: "standard"`
Enum representing the size of the plastic card.
- `"standard"`
- `doubleSided: optional object { backHTML, backTemplate, frontHTML, 2 more }`
Model representing a double-sided plastic card.
- `backHTML: optional string`
The HTML content for the back side of the double-sided plastic card.
- `backTemplate: optional string`
The template ID for the back side of the double-sided plastic card.
- `frontHTML: optional string`
The HTML content for the front side of the double-sided plastic card.
- `frontTemplate: optional string`
The template ID for the front side of the double-sided plastic card.
- `pdf: optional string`
A URL pointing to a PDF file for the double-sided plastic card or the file itself.
- `singleSided: optional object { html, pdf, template }`
Model representing a single-sided plastic card.
- `html: optional string`
The HTML content for the single-sided plastic card. Can specify one of this, `template`, or `pdf`.
- `pdf: optional string`
A URL pointing to a PDF file for the single-sided plastic card or the PDF file itself.
- `template: optional string`
The template ID for the single-sided plastic card.
### Letter Retrieve URL Response
- `LetterRetrieveURLResponse object { id, object, url }`
- `id: string`
A unique ID prefixed with letter_
- `object: string`
- `url: string`
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
**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
### Body Parameters
- `body: object { backHTML, frontHTML, size, 8 more } or object { backTemplate, frontTemplate, size, 8 more } or object { pdf, size, to, 7 more } or object { pdf, size, to, 7 more }`
- `PostcardCreateWithHTML object { backHTML, frontHTML, size, 8 more }`
- `backHTML: string`
The HTML content for the back of the postcard. You can supply _either_ this or `backTemplate` but not both.
- `frontHTML: string`
The HTML content for the front of the postcard. You can supply _either_ this or `frontTemplate` but not both.
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `firstName: string`
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `companyName: string`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `sendDate: optional string`
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.
- `PostcardCreateWithTemplate object { backTemplate, frontTemplate, size, 8 more }`
- `backTemplate: string`
The template ID for the back of the postcard. You can supply _either_ this or `backHTML` but not both.
- `frontTemplate: string`
The template ID for the front of the postcard. You can supply _either_ this or `frontHTML` but not both.
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `sendDate: optional string`
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.
- `PostcardCreateWithPdfurl object { pdf, size, to, 7 more }`
- `pdf: string`
A URL pointing to a 2 page PDF file. The first page is the front of the postcard and the second page is the back (where the address will be stamped on).
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `sendDate: optional string`
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.
- `PostcardCreateWithPdfFile object { pdf, size, to, 7 more }`
- `pdf: string`
A 2 page PDF file. The first page is the front of the postcard and the second page is the back (where the address will be stamped on).
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `sendDate: optional string`
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
- `Postcard object { id, createdAt, live, 18 more }`
- `id: string`
A unique ID prefixed with postcard_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "postcard"`
Always `postcard`.
- `"postcard"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional Contact`
The contact information of the sender.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/postcards \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"backHTML": "backHTML",
"frontHTML": "frontHTML",
"size": "6x4",
"to": {
"addressLine1": "addressLine1",
"countryCode": "countryCode",
"firstName": "firstName"
}
}'
```
#### 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
**get** `/print-mail/v1/postcards`
Get a list of postcards.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of Postcard`
- `id: string`
A unique ID prefixed with postcard_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "postcard"`
Always `postcard`.
- `"postcard"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional Contact`
The contact information of the sender.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/postcards \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/postcards/{id}`
Retrieve a postcard by ID.
### Path Parameters
- `id: string`
### Returns
- `Postcard object { id, createdAt, live, 18 more }`
- `id: string`
A unique ID prefixed with postcard_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "postcard"`
Always `postcard`.
- `"postcard"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional Contact`
The contact information of the sender.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/postcards/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**delete** `/print-mail/v1/postcards/{id}`
Cancel a postcard by ID. Note that this operation cannot be undone.
### Path Parameters
- `id: string`
### Returns
- `Postcard object { id, createdAt, live, 18 more }`
- `id: string`
A unique ID prefixed with postcard_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "postcard"`
Always `postcard`.
- `"postcard"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional Contact`
The contact information of the sender.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/postcards/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with postcard_
- `object: string`
- `url: string`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/postcards/$ID/url \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Body Parameters
- `note: string`
### Returns
- `Postcard object { id, createdAt, live, 18 more }`
- `id: string`
A unique ID prefixed with postcard_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "postcard"`
Always `postcard`.
- `"postcard"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional Contact`
The contact information of the sender.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/postcards/$ID/cancellation \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"note": "Cancelling this postcard"
}'
```
#### 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
**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`.
### Path Parameters
- `id: string`
### Returns
- `Postcard object { id, createdAt, live, 18 more }`
- `id: string`
A unique ID prefixed with postcard_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "postcard"`
Always `postcard`.
- `"postcard"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional Contact`
The contact information of the sender.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/postcards/$ID/progressions \
-X POST \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
- `Postcard object { id, createdAt, live, 18 more }`
- `id: string`
A unique ID prefixed with postcard_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "postcard"`
Always `postcard`.
- `"postcard"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `from: optional Contact`
The contact information of the sender.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
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`.
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Postcard Retrieve URL Response
- `PostcardRetrieveURLResponse object { id, object, url }`
- `id: string`
A unique ID prefixed with postcard_
- `object: string`
- `url: string`
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
**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.
### Body Parameters
- `body: object { accountNumber, bankCountryCode, bankName, 9 more } or object { accountNumber, bankCountryCode, bankName, 9 more } or object { accountNumber, bankCountryCode, bankName, 9 more }`
- `BankAccountCreateSignatureText object { accountNumber, bankCountryCode, bankName, 9 more }`
- `accountNumber: string`
The account number of the bank account.
- `bankCountryCode: BankAccountCountryCode`
Countries typically have different bank account formats and standards. These are the countries
which PostGrid's bank accounts API supports.
- `"CA"`
- `"US"`
- `bankName: string`
The name of the bank.
- `signatureText: string`
The signature text of the bank account.
- `bankPrimaryLine: optional string`
The primary address line of the bank.
- `bankSecondaryLine: optional string`
The secondary address line of the bank.
- `caDesignationNumber: optional string`
The designation number of the bank account (for CA).
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `routeNumber: optional string`
The route number of the bank account (for CA).
- `routingNumber: optional string`
The routing number of the bank account (for US).
- `transitNumber: optional string`
The transit number of the bank account (for CA).
- `BankAccountCreateSignatureImageURL object { accountNumber, bankCountryCode, bankName, 9 more }`
- `accountNumber: string`
The account number of the bank account.
- `bankCountryCode: BankAccountCountryCode`
Countries typically have different bank account formats and standards. These are the countries
which PostGrid's bank accounts API supports.
- `bankName: string`
The name of the bank.
- `signatureImage: string`
Link to signature image which PostGrid will download and apply to cheques created with this bank account.
- `bankPrimaryLine: optional string`
The primary address line of the bank.
- `bankSecondaryLine: optional string`
The secondary address line of the bank.
- `caDesignationNumber: optional string`
The designation number of the bank account (for CA).
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `routeNumber: optional string`
The route number of the bank account (for CA).
- `routingNumber: optional string`
The routing number of the bank account (for US).
- `transitNumber: optional string`
The transit number of the bank account (for CA).
- `BankAccountCreateSignatureImageFile object { accountNumber, bankCountryCode, bankName, 9 more }`
- `accountNumber: string`
The account number of the bank account.
- `bankCountryCode: BankAccountCountryCode`
Countries typically have different bank account formats and standards. These are the countries
which PostGrid's bank accounts API supports.
- `bankName: string`
The name of the bank.
- `signatureImage: string`
A PNG or JPEG file which PostGrid will apply to checks created with this bank account.
- `bankPrimaryLine: optional string`
The primary address line of the bank.
- `bankSecondaryLine: optional string`
The secondary address line of the bank.
- `caDesignationNumber: optional string`
The designation number of the bank account (for CA).
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `routeNumber: optional string`
The route number of the bank account (for CA).
- `routingNumber: optional string`
The routing number of the bank account (for US).
- `transitNumber: optional string`
The transit number of the bank account (for CA).
### Returns
- `BankAccount object { id, accountNumber, bankCountryCode, 15 more }`
- `id: string`
A unique ID prefixed with bank_account_
- `accountNumber: string`
The account number of the bank account.
- `bankCountryCode: BankAccountCountryCode`
Countries typically have different bank account formats and standards. These are the countries
which PostGrid's bank accounts API supports.
- `"CA"`
- `"US"`
- `bankName: string`
The name of the bank.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "bank_account"`
Always `bank_account`.
- `"bank_account"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `bankPrimaryLine: optional string`
The primary address line of the bank.
- `bankSecondaryLine: optional string`
The secondary address line of the bank.
- `caDesignationNumber: optional string`
The designation number of the bank account (for CA).
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `routeNumber: optional string`
The route number of the bank account (for CA).
- `routingNumber: optional string`
The routing number of the bank account (for US).
- `signatureImage: optional string`
A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present.
- `signatureText: optional string`
The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present.
- `transitNumber: optional string`
The transit number of the bank account (for CA).
### Example
```http
curl https://api.postgrid.com/print-mail/v1/bank_accounts \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"accountNumber": "accountNumber",
"bankCountryCode": "CA",
"bankName": "bankName",
"signatureText": "signatureText"
}'
```
#### 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
**get** `/print-mail/v1/bank_accounts`
Get a list of bank accounts.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of BankAccount`
- `id: string`
A unique ID prefixed with bank_account_
- `accountNumber: string`
The account number of the bank account.
- `bankCountryCode: BankAccountCountryCode`
Countries typically have different bank account formats and standards. These are the countries
which PostGrid's bank accounts API supports.
- `"CA"`
- `"US"`
- `bankName: string`
The name of the bank.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "bank_account"`
Always `bank_account`.
- `"bank_account"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `bankPrimaryLine: optional string`
The primary address line of the bank.
- `bankSecondaryLine: optional string`
The secondary address line of the bank.
- `caDesignationNumber: optional string`
The designation number of the bank account (for CA).
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `routeNumber: optional string`
The route number of the bank account (for CA).
- `routingNumber: optional string`
The routing number of the bank account (for US).
- `signatureImage: optional string`
A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present.
- `signatureText: optional string`
The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present.
- `transitNumber: optional string`
The transit number of the bank account (for CA).
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/bank_accounts \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/bank_accounts/{id}`
Retrieve a bank account by ID.
### Path Parameters
- `id: string`
### Returns
- `BankAccount object { id, accountNumber, bankCountryCode, 15 more }`
- `id: string`
A unique ID prefixed with bank_account_
- `accountNumber: string`
The account number of the bank account.
- `bankCountryCode: BankAccountCountryCode`
Countries typically have different bank account formats and standards. These are the countries
which PostGrid's bank accounts API supports.
- `"CA"`
- `"US"`
- `bankName: string`
The name of the bank.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "bank_account"`
Always `bank_account`.
- `"bank_account"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `bankPrimaryLine: optional string`
The primary address line of the bank.
- `bankSecondaryLine: optional string`
The secondary address line of the bank.
- `caDesignationNumber: optional string`
The designation number of the bank account (for CA).
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `routeNumber: optional string`
The route number of the bank account (for CA).
- `routingNumber: optional string`
The routing number of the bank account (for US).
- `signatureImage: optional string`
A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present.
- `signatureText: optional string`
The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present.
- `transitNumber: optional string`
The transit number of the bank account (for CA).
### Example
```http
curl https://api.postgrid.com/print-mail/v1/bank_accounts/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**delete** `/print-mail/v1/bank_accounts/{id}`
Delete a bank account by ID. Note that this operation cannot be undone.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with bank_account_
- `deleted: true`
- `true`
- `object: "bank_account"`
Always `bank_account`.
- `"bank_account"`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/bank_accounts/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "bank_account_sqF12lZ1VlBb",
"deleted": true,
"object": "bank_account"
}
```
## Domain Types
### Bank Account
- `BankAccount object { id, accountNumber, bankCountryCode, 15 more }`
- `id: string`
A unique ID prefixed with bank_account_
- `accountNumber: string`
The account number of the bank account.
- `bankCountryCode: BankAccountCountryCode`
Countries typically have different bank account formats and standards. These are the countries
which PostGrid's bank accounts API supports.
- `"CA"`
- `"US"`
- `bankName: string`
The name of the bank.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "bank_account"`
Always `bank_account`.
- `"bank_account"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `bankPrimaryLine: optional string`
The primary address line of the bank.
- `bankSecondaryLine: optional string`
The secondary address line of the bank.
- `caDesignationNumber: optional string`
The designation number of the bank account (for CA).
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `routeNumber: optional string`
The route number of the bank account (for CA).
- `routingNumber: optional string`
The routing number of the bank account (for US).
- `signatureImage: optional string`
A signed link to the signature image uploaded when this bank account was created. This is omitted if `signatureText` is present.
- `signatureText: optional string`
The signature text PostGrid uses to generate a signature for cheques created using this bank account. This is omitted if `signatureImage` is present.
- `transitNumber: optional string`
The transit number of the bank account (for CA).
### Bank Account Country Code
- `BankAccountCountryCode = "CA" or "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
- `BankAccountDeleteResponse object { id, deleted, object }`
- `id: string`
A unique ID prefixed with bank_account_
- `deleted: true`
- `true`
- `object: "bank_account"`
Always `bank_account`.
- `"bank_account"`
# Cheques
## Create 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"
}
}
```
### Body Parameters
- `amount: number`
The amount of the cheque in cents.
- `bankAccount: string`
The bank account (ID) associated with the cheque.
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `firstName: string`
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `companyName: string`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `string`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `currencyCode: optional "USD" or "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 string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `digitalOnly: optional DigitalOnly`
The digitalOnly object contains data for digital-only cheques. A watermark must be provided.
- `watermark: string`
Text to be displayed as a watermark on the digital cheque.
- `envelope: optional "standard" or string`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `string`
- `logoURL: optional string`
An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file).
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string`
The memo of the cheque.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `message: optional string`
The message of the cheque.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `number: optional number`
The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number.
- `redirectTo: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `sendDate: optional string`
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
- `Cheque object { id, amount, bankAccount, 27 more }`
- `id: string`
A unique ID prefixed with cheque_
- `amount: number`
The amount of the cheque in cents.
- `bankAccount: string`
The bank account (ID) associated with the cheque.
- `createdAt: string`
The UTC time at which this resource was created.
- `currencyCode: "USD" or "CAD"`
The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified.
- `"USD"`
- `"CAD"`
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "cheque"`
Always `cheque`.
- `"cheque"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `depositReadyPDFURL: optional string`
A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `digitalOnly: optional DigitalOnly`
The digitalOnly object contains data for digital-only cheques. A watermark must be provided.
- `watermark: string`
Text to be displayed as a watermark on the digital cheque.
- `envelope: optional "standard" or string`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `string`
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `logoURL: optional string`
An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file).
- `memo: optional string`
The memo of the cheque.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `message: optional string`
The message of the cheque.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `number: optional number`
The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/cheques \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"amount": 1000,
"bankAccount": "bank_123",
"from": "contact_123",
"to": "contact_123"
}'
```
#### 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
**get** `/print-mail/v1/cheques`
Get a list of cheques.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of Cheque`
- `id: string`
A unique ID prefixed with cheque_
- `amount: number`
The amount of the cheque in cents.
- `bankAccount: string`
The bank account (ID) associated with the cheque.
- `createdAt: string`
The UTC time at which this resource was created.
- `currencyCode: "USD" or "CAD"`
The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified.
- `"USD"`
- `"CAD"`
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "cheque"`
Always `cheque`.
- `"cheque"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `depositReadyPDFURL: optional string`
A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `digitalOnly: optional DigitalOnly`
The digitalOnly object contains data for digital-only cheques. A watermark must be provided.
- `watermark: string`
Text to be displayed as a watermark on the digital cheque.
- `envelope: optional "standard" or string`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `string`
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `logoURL: optional string`
An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file).
- `memo: optional string`
The memo of the cheque.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `message: optional string`
The message of the cheque.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `number: optional number`
The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/cheques \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/cheques/{id}`
Retrieve a cheque by ID.
### Path Parameters
- `id: string`
### Returns
- `Cheque object { id, amount, bankAccount, 27 more }`
- `id: string`
A unique ID prefixed with cheque_
- `amount: number`
The amount of the cheque in cents.
- `bankAccount: string`
The bank account (ID) associated with the cheque.
- `createdAt: string`
The UTC time at which this resource was created.
- `currencyCode: "USD" or "CAD"`
The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified.
- `"USD"`
- `"CAD"`
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "cheque"`
Always `cheque`.
- `"cheque"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `depositReadyPDFURL: optional string`
A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `digitalOnly: optional DigitalOnly`
The digitalOnly object contains data for digital-only cheques. A watermark must be provided.
- `watermark: string`
Text to be displayed as a watermark on the digital cheque.
- `envelope: optional "standard" or string`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `string`
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `logoURL: optional string`
An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file).
- `memo: optional string`
The memo of the cheque.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `message: optional string`
The message of the cheque.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `number: optional number`
The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/cheques/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**delete** `/print-mail/v1/cheques/{id}`
Cancel a cheque by ID. Note that this operation cannot be undone.
### Path Parameters
- `id: string`
### Returns
- `Cheque object { id, amount, bankAccount, 27 more }`
- `id: string`
A unique ID prefixed with cheque_
- `amount: number`
The amount of the cheque in cents.
- `bankAccount: string`
The bank account (ID) associated with the cheque.
- `createdAt: string`
The UTC time at which this resource was created.
- `currencyCode: "USD" or "CAD"`
The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified.
- `"USD"`
- `"CAD"`
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "cheque"`
Always `cheque`.
- `"cheque"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `depositReadyPDFURL: optional string`
A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `digitalOnly: optional DigitalOnly`
The digitalOnly object contains data for digital-only cheques. A watermark must be provided.
- `watermark: string`
Text to be displayed as a watermark on the digital cheque.
- `envelope: optional "standard" or string`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `string`
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `logoURL: optional string`
An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file).
- `memo: optional string`
The memo of the cheque.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `message: optional string`
The message of the cheque.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `number: optional number`
The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/cheques/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with cheque_
- `object: string`
- `url: string`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/cheques/$ID/url \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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)
**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.
### Path Parameters
- `id: string`
### Returns
- `Cheque object { id, amount, bankAccount, 27 more }`
- `id: string`
A unique ID prefixed with cheque_
- `amount: number`
The amount of the cheque in cents.
- `bankAccount: string`
The bank account (ID) associated with the cheque.
- `createdAt: string`
The UTC time at which this resource was created.
- `currencyCode: "USD" or "CAD"`
The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified.
- `"USD"`
- `"CAD"`
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "cheque"`
Always `cheque`.
- `"cheque"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `depositReadyPDFURL: optional string`
A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `digitalOnly: optional DigitalOnly`
The digitalOnly object contains data for digital-only cheques. A watermark must be provided.
- `watermark: string`
Text to be displayed as a watermark on the digital cheque.
- `envelope: optional "standard" or string`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `string`
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `logoURL: optional string`
An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file).
- `memo: optional string`
The memo of the cheque.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `message: optional string`
The message of the cheque.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `number: optional number`
The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/cheques/$ID/with_deposit_ready_pdf \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Body Parameters
- `note: string`
### Returns
- `Cheque object { id, amount, bankAccount, 27 more }`
- `id: string`
A unique ID prefixed with cheque_
- `amount: number`
The amount of the cheque in cents.
- `bankAccount: string`
The bank account (ID) associated with the cheque.
- `createdAt: string`
The UTC time at which this resource was created.
- `currencyCode: "USD" or "CAD"`
The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified.
- `"USD"`
- `"CAD"`
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "cheque"`
Always `cheque`.
- `"cheque"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `depositReadyPDFURL: optional string`
A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `digitalOnly: optional DigitalOnly`
The digitalOnly object contains data for digital-only cheques. A watermark must be provided.
- `watermark: string`
Text to be displayed as a watermark on the digital cheque.
- `envelope: optional "standard" or string`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `string`
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `logoURL: optional string`
An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file).
- `memo: optional string`
The memo of the cheque.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `message: optional string`
The message of the cheque.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `number: optional number`
The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/cheques/$ID/cancellation \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"note": "Cancelling this cheque"
}'
```
#### 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
**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`.
### Path Parameters
- `id: string`
### Returns
- `Cheque object { id, amount, bankAccount, 27 more }`
- `id: string`
A unique ID prefixed with cheque_
- `amount: number`
The amount of the cheque in cents.
- `bankAccount: string`
The bank account (ID) associated with the cheque.
- `createdAt: string`
The UTC time at which this resource was created.
- `currencyCode: "USD" or "CAD"`
The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified.
- `"USD"`
- `"CAD"`
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "cheque"`
Always `cheque`.
- `"cheque"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `depositReadyPDFURL: optional string`
A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `digitalOnly: optional DigitalOnly`
The digitalOnly object contains data for digital-only cheques. A watermark must be provided.
- `watermark: string`
Text to be displayed as a watermark on the digital cheque.
- `envelope: optional "standard" or string`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `string`
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `logoURL: optional string`
An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file).
- `memo: optional string`
The memo of the cheque.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `message: optional string`
The message of the cheque.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `number: optional number`
The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/cheques/$ID/progressions \
-X POST \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
- `Cheque object { id, amount, bankAccount, 27 more }`
- `id: string`
A unique ID prefixed with cheque_
- `amount: number`
The amount of the cheque in cents.
- `bankAccount: string`
The bank account (ID) associated with the cheque.
- `createdAt: string`
The UTC time at which this resource was created.
- `currencyCode: "USD" or "CAD"`
The currency code of the cheque. This can be `USD` even if drawing from a Canadian bank account and vice versa. Defaults to the currency of the bank account country if not otherwise specified.
- `"USD"`
- `"CAD"`
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "cheque"`
Always `cheque`.
- `"cheque"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `depositReadyPDFURL: optional string`
A link to the deposit-ready PDF for a digital-only cheque, returned if requested and available.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `digitalOnly: optional DigitalOnly`
The digitalOnly object contains data for digital-only cheques. A watermark must be provided.
- `watermark: string`
Text to be displayed as a watermark on the digital cheque.
- `envelope: optional "standard" or string`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
The envelope of the cheque. If a custom envelope ID is not specified, defaults to `standard`.
- `"standard"`
- `string`
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `logoURL: optional string`
An optional logo URL for the cheque. This will be placed next to the recipient address at the top left corner of the cheque. This needs to be a public link to an image file (e.g. a PNG or JPEG file).
- `memo: optional string`
The memo of the cheque.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `message: optional string`
The message of the cheque.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `number: optional number`
The number of the cheque. If you don't provide this, it will automatically be set to an incrementing number starting from 1 across your entire account, ensuring that every cheque has a unique number.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Cheque Size
- `ChequeSize = "us_letter" or "us_legal"`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
### Digital Only
- `DigitalOnly object { watermark }`
- `watermark: string`
Text to be displayed as a watermark on the digital cheque.
### Cheque Retrieve URL Response
- `ChequeRetrieveURLResponse object { id, object, url }`
- `id: string`
A unique ID prefixed with cheque_
- `object: string`
- `url: string`
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
**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
### Body Parameters
- `body: object { from, insideHTML, outsideHTML, 7 more } or object { from, insideTemplate, outsideTemplate, 7 more } or object { from, pdf, size, 6 more } or object { from, pdf, size, 6 more }`
- `SelfMailerCreateWithHTML object { from, insideHTML, outsideHTML, 7 more }`
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `firstName: string`
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `companyName: string`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `string`
- `insideHTML: string`
The HTML content for the inside of the self-mailer. You can supply _either_ this or `insideTemplate` but not both.
- `outsideHTML: string`
The HTML content for the outside of the self-mailer. You can supply _either_ this or `outsideTemplate` but not both.
- `size: "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `sendDate: optional string`
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.
- `SelfMailerCreateWithTemplate object { from, insideTemplate, outsideTemplate, 7 more }`
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `insideTemplate: string`
The template ID for the inside of the self-mailer. You can supply _either_ this or `insideHTML` but not both.
- `outsideTemplate: string`
The template ID for the outside of the self-mailer. You can supply _either_ this or `outsideHTML` but not both.
- `size: "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `sendDate: optional string`
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.
- `SelfMailerCreateWithPdfurl object { from, pdf, size, 6 more }`
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `pdf: string`
A URL pointing to a 2 page PDF file. The first page is the inside of the self-mailer and the second page is the outside (where the address will be stamped on).
- `size: "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `sendDate: optional string`
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.
- `SelfMailerCreateWithPdfFile object { from, pdf, size, 6 more }`
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to`.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `pdf: string`
A 2 page PDF file. The first page is the inside of the self-mailer and the second page is the outside (where the address will be stamped on).
- `size: "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `sendDate: optional string`
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
- `SelfMailer object { id, createdAt, from, 17 more }`
- `id: string`
A unique ID prefixed with self_mailer_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "self_mailer"`
Always `self_mailer`.
- `"self_mailer"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/self_mailers \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"from": {
"addressLine1": "addressLine1",
"countryCode": "countryCode",
"firstName": "firstName"
},
"insideHTML": "insideHTML",
"outsideHTML": "outsideHTML",
"size": "8.5x11_bifold",
"to": {
"addressLine1": "addressLine1",
"countryCode": "countryCode",
"firstName": "firstName"
}
}'
```
#### 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
**get** `/print-mail/v1/self_mailers`
Get a list of self-mailers.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of SelfMailer`
- `id: string`
A unique ID prefixed with self_mailer_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "self_mailer"`
Always `self_mailer`.
- `"self_mailer"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/self_mailers \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/self_mailers/{id}`
Retrieve a self-mailer by ID.
### Path Parameters
- `id: string`
### Returns
- `SelfMailer object { id, createdAt, from, 17 more }`
- `id: string`
A unique ID prefixed with self_mailer_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "self_mailer"`
Always `self_mailer`.
- `"self_mailer"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/self_mailers/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**delete** `/print-mail/v1/self_mailers/{id}`
Cancel a self-mailer by ID. Note that this operation cannot be undone.
### Path Parameters
- `id: string`
### Returns
- `SelfMailer object { id, createdAt, from, 17 more }`
- `id: string`
A unique ID prefixed with self_mailer_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "self_mailer"`
Always `self_mailer`.
- `"self_mailer"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/self_mailers/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with self_mailer_
- `object: string`
- `url: string`
A signed URL linking to the order preview PDF. The link remains valid for 15 minutes from the time of the API call.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/self_mailers/$ID/url \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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`.
### Path Parameters
- `id: string`
### Returns
- `SelfMailer object { id, createdAt, from, 17 more }`
- `id: string`
A unique ID prefixed with self_mailer_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "self_mailer"`
Always `self_mailer`.
- `"self_mailer"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/self_mailers/$ID/progressions \
-X POST \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
- `SelfMailer object { id, createdAt, from, 17 more }`
- `id: string`
A unique ID prefixed with self_mailer_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"first_class"`
- `"standard_class"`
- `"express"`
- `"certified"`
- `"certified_return_receipt"`
- `"registered"`
- `"usps_first_class"`
- `"usps_standard_class"`
- `"usps_eddm"`
- `"usps_express_2_day"`
- `"usps_express_3_day"`
- `"usps_first_class_certified"`
- `"usps_first_class_certified_return_receipt"`
- `"usps_first_class_registered"`
- `"usps_express_3_day_signature_confirmation"`
- `"usps_express_3_day_certified"`
- `"usps_express_3_day_certified_return_receipt"`
- `"ca_post_lettermail"`
- `"ca_post_personalized"`
- `"ca_post_neighbourhood_mail"`
- `"ups_express_overnight"`
- `"ups_express_2_day"`
- `"ups_express_3_day"`
- `"royal_mail_first_class"`
- `"royal_mail_second_class"`
- `"au_post_second_class"`
- `object: "self_mailer"`
Always `self_mailer`.
- `"self_mailer"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `status: "ready" or "printing" or "processed_for_delivery" or 2 more`
See `OrderStatus` for more details on the status of this order.
- `"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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Self Mailer Retrieve URL Response
- `SelfMailerRetrieveURLResponse object { id, object, url }`
- `id: string`
A unique ID prefixed with self_mailer_
- `object: string`
- `url: string`
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
**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.
### Header Parameters
- `"idempotency-key": optional string`
### Body Parameters
- `mailingList: string`
The ID of the mailing list associated with this campaign.
- `cheque: optional object { bankAccount, currencyCode, description, 12 more }`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bankAccount: optional string`
ID of the bank account to use for the cheque.
- `currencyCode: optional "CAD" or "USD"`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: optional string`
An optional description.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `letterPDF: optional string`
PDF file for an optional attached letter. Cannot be used with `letterTemplate`.
- `letterSettings: optional object { color }`
Settings for the attached letter (e.g., color printing).
- `color: optional boolean`
Whether to print the attached letter in color.
- `letterTemplate: optional string`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `logo: optional string`
A publicly accessible URL for the logo to print on the cheque.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string`
Memo line text for the cheque.
- `mergeVariables: optional map[unknown]`
Default merge variables for the cheque.
- `message: optional string`
Message included on the cheque stub.
- `metadata: optional map[string]`
Optional key-value metadata.
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `defaultSenderContact: optional string`
The ID of the default sender contact to use for orders if not specified per recipient.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `letter: optional object { addressPlacement, attachedPDF, color, 13 more }`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: optional boolean`
Whether to print in color.
- `description: optional string`
An optional description.
- `doubleSided: optional boolean`
Whether to print on both sides of the paper.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `envelopeType: optional "standard_double_window" or "flat"`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the letter.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
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 string`
A PDF file or URL for the letter content. Cannot be used with `template`.
- `perforatedPage: optional 1`
Which page number should be perforated (if any).
- `1`
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: optional string`
ID of a template for the letter content. Cannot be used with `pdf`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `postcard: optional object { backTemplate, description, frontTemplate, 6 more }`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `backTemplate: optional string`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: optional string`
An optional description.
- `frontTemplate: optional string`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the postcard.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
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 string`
A 2-page PDF file for the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`.
- `size: optional "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `selfMailer: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the self-mailer.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `pdf: optional string`
A 2-page PDF file for the self-mailer content. Cannot be used with `insideTemplate`/`outsideTemplate`.
- `size: optional "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `sendDate: optional string`
The scheduled date and time for the campaign to be sent.
- `snapPack: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the snap pack.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `pdf: optional string`
A 2-page PDF file for the snap pack content. Cannot be used with `insideTemplate`/`outsideTemplate`.
- `size: optional "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
### Returns
- `Campaign object { id, createdAt, createdCount, 16 more }`
Represents a bulk mail campaign.
- `id: string`
A unique ID prefixed with campaign_
- `createdAt: string`
The UTC time at which this resource was created.
- `createdCount: number`
The number of orders successfully created for this campaign.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingList: string`
The ID of the mailing list associated with this campaign.
- `status: "drafting" or "changes_required" or "creating_orders" or 4 more`
Status of the campaign lifecycle.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cheque: optional object { bankAccount, currencyCode, description, 12 more }`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bankAccount: optional string`
ID of the bank account to use for the cheque.
- `currencyCode: optional "CAD" or "USD"`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: optional string`
An optional description.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `letterSettings: optional object { color }`
Settings for the attached letter (e.g., color printing).
- `color: optional boolean`
Whether to print the attached letter in color.
- `letterTemplate: optional string`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letterUploadedPDF: optional string`
A signed URL to the attached letter PDF, if any.
- `logo: optional string`
A publicly accessible URL for the logo to print on the cheque.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string`
Memo line text for the cheque.
- `mergeVariables: optional map[unknown]`
Default merge variables for the cheque.
- `message: optional string`
Message included on the cheque stub.
- `metadata: optional map[string]`
Optional key-value metadata.
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `defaultSenderContact: optional string`
The ID of the default sender contact to use for orders if not specified per recipient.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "processing_error" or "internal_error"`
Type of error encountered during campaign processing.
- `"processing_error"`
- `"internal_error"`
- `letter: optional object { addressPlacement, attachedPDF, color, 13 more }`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: optional boolean`
Whether to print in color.
- `description: optional string`
An optional description.
- `doubleSided: optional boolean`
Whether to print on both sides of the paper.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `envelopeType: optional "standard_double_window" or "flat"`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the letter.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforatedPage: optional 1`
Which page number should be perforated (if any).
- `1`
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: optional string`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `orderPreviewURL: optional string`
A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.
- `postcard: optional object { backTemplate, description, frontTemplate, 6 more }`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `backTemplate: optional string`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: optional string`
An optional description.
- `frontTemplate: optional string`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the postcard.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
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 "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `selfMailer: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the self-mailer.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `sendDate: optional string`
The scheduled date and time for the campaign to be sent.
- `snapPack: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the snap pack.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/campaigns \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"mailingList": "mailingList"
}'
```
#### 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
**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.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of Campaign`
- `id: string`
A unique ID prefixed with campaign_
- `createdAt: string`
The UTC time at which this resource was created.
- `createdCount: number`
The number of orders successfully created for this campaign.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingList: string`
The ID of the mailing list associated with this campaign.
- `status: "drafting" or "changes_required" or "creating_orders" or 4 more`
Status of the campaign lifecycle.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cheque: optional object { bankAccount, currencyCode, description, 12 more }`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bankAccount: optional string`
ID of the bank account to use for the cheque.
- `currencyCode: optional "CAD" or "USD"`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: optional string`
An optional description.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `letterSettings: optional object { color }`
Settings for the attached letter (e.g., color printing).
- `color: optional boolean`
Whether to print the attached letter in color.
- `letterTemplate: optional string`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letterUploadedPDF: optional string`
A signed URL to the attached letter PDF, if any.
- `logo: optional string`
A publicly accessible URL for the logo to print on the cheque.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string`
Memo line text for the cheque.
- `mergeVariables: optional map[unknown]`
Default merge variables for the cheque.
- `message: optional string`
Message included on the cheque stub.
- `metadata: optional map[string]`
Optional key-value metadata.
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `defaultSenderContact: optional string`
The ID of the default sender contact to use for orders if not specified per recipient.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "processing_error" or "internal_error"`
Type of error encountered during campaign processing.
- `"processing_error"`
- `"internal_error"`
- `letter: optional object { addressPlacement, attachedPDF, color, 13 more }`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: optional boolean`
Whether to print in color.
- `description: optional string`
An optional description.
- `doubleSided: optional boolean`
Whether to print on both sides of the paper.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `envelopeType: optional "standard_double_window" or "flat"`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the letter.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforatedPage: optional 1`
Which page number should be perforated (if any).
- `1`
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: optional string`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `orderPreviewURL: optional string`
A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.
- `postcard: optional object { backTemplate, description, frontTemplate, 6 more }`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `backTemplate: optional string`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: optional string`
An optional description.
- `frontTemplate: optional string`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the postcard.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
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 "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `selfMailer: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the self-mailer.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `sendDate: optional string`
The scheduled date and time for the campaign to be sent.
- `snapPack: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the snap pack.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/campaigns \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/campaigns/{id}`
Retrieve a specific campaign by its ID.
### Path Parameters
- `id: string`
### Returns
- `Campaign object { id, createdAt, createdCount, 16 more }`
Represents a bulk mail campaign.
- `id: string`
A unique ID prefixed with campaign_
- `createdAt: string`
The UTC time at which this resource was created.
- `createdCount: number`
The number of orders successfully created for this campaign.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingList: string`
The ID of the mailing list associated with this campaign.
- `status: "drafting" or "changes_required" or "creating_orders" or 4 more`
Status of the campaign lifecycle.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cheque: optional object { bankAccount, currencyCode, description, 12 more }`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bankAccount: optional string`
ID of the bank account to use for the cheque.
- `currencyCode: optional "CAD" or "USD"`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: optional string`
An optional description.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `letterSettings: optional object { color }`
Settings for the attached letter (e.g., color printing).
- `color: optional boolean`
Whether to print the attached letter in color.
- `letterTemplate: optional string`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letterUploadedPDF: optional string`
A signed URL to the attached letter PDF, if any.
- `logo: optional string`
A publicly accessible URL for the logo to print on the cheque.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string`
Memo line text for the cheque.
- `mergeVariables: optional map[unknown]`
Default merge variables for the cheque.
- `message: optional string`
Message included on the cheque stub.
- `metadata: optional map[string]`
Optional key-value metadata.
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `defaultSenderContact: optional string`
The ID of the default sender contact to use for orders if not specified per recipient.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "processing_error" or "internal_error"`
Type of error encountered during campaign processing.
- `"processing_error"`
- `"internal_error"`
- `letter: optional object { addressPlacement, attachedPDF, color, 13 more }`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: optional boolean`
Whether to print in color.
- `description: optional string`
An optional description.
- `doubleSided: optional boolean`
Whether to print on both sides of the paper.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `envelopeType: optional "standard_double_window" or "flat"`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the letter.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforatedPage: optional 1`
Which page number should be perforated (if any).
- `1`
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: optional string`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `orderPreviewURL: optional string`
A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.
- `postcard: optional object { backTemplate, description, frontTemplate, 6 more }`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `backTemplate: optional string`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: optional string`
An optional description.
- `frontTemplate: optional string`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the postcard.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
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 "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `selfMailer: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the self-mailer.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `sendDate: optional string`
The scheduled date and time for the campaign to be sent.
- `snapPack: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the snap pack.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/campaigns/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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`.
### Path Parameters
- `id: string`
### Body Parameters
- `cheque: optional object { bankAccount, currencyCode, description, 12 more }`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bankAccount: optional string`
ID of the bank account to use for the cheque.
- `currencyCode: optional "CAD" or "USD"`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: optional string`
An optional description.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `letterPDF: optional string`
PDF file for an optional attached letter. Cannot be used with `letterTemplate`.
- `letterSettings: optional object { color }`
Settings for the attached letter (e.g., color printing).
- `color: optional boolean`
Whether to print the attached letter in color.
- `letterTemplate: optional string`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `logo: optional string`
A publicly accessible URL for the logo to print on the cheque.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string`
Memo line text for the cheque.
- `mergeVariables: optional map[unknown]`
Default merge variables for the cheque.
- `message: optional string`
Message included on the cheque stub.
- `metadata: optional map[string]`
Optional key-value metadata.
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `defaultSenderContact: optional string`
The ID of the default sender contact. Set to `null` to remove.
- `description: optional string`
An optional description for the campaign. Set to `null` to remove the existing description.
- `letter: optional object { addressPlacement, attachedPDF, color, 13 more }`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: optional boolean`
Whether to print in color.
- `description: optional string`
An optional description.
- `doubleSided: optional boolean`
Whether to print on both sides of the paper.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `envelopeType: optional "standard_double_window" or "flat"`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the letter.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
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 string`
A PDF file or URL for the letter content. Cannot be used with `template`.
- `perforatedPage: optional 1`
Which page number should be perforated (if any).
- `1`
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: optional string`
ID of a template for the letter content. Cannot be used with `pdf`.
- `mailingList: optional string`
The ID of the mailing list to associate with this campaign.
- `metadata: optional map[string]`
Optional key-value data associated with the campaign. Set to `null` to remove existing metadata.
- `postcard: optional object { backTemplate, description, frontTemplate, 6 more }`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `backTemplate: optional string`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: optional string`
An optional description.
- `frontTemplate: optional string`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the postcard.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
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 string`
A 2-page PDF file for the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`.
- `size: optional "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `selfMailer: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the self-mailer.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `pdf: optional string`
A 2-page PDF file for the self-mailer content. Cannot be used with `insideTemplate`/`outsideTemplate`.
- `size: optional "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `snapPack: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the snap pack.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `pdf: optional string`
A 2-page PDF file for the snap pack content. Cannot be used with `insideTemplate`/`outsideTemplate`.
- `size: optional "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
### Returns
- `Campaign object { id, createdAt, createdCount, 16 more }`
Represents a bulk mail campaign.
- `id: string`
A unique ID prefixed with campaign_
- `createdAt: string`
The UTC time at which this resource was created.
- `createdCount: number`
The number of orders successfully created for this campaign.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingList: string`
The ID of the mailing list associated with this campaign.
- `status: "drafting" or "changes_required" or "creating_orders" or 4 more`
Status of the campaign lifecycle.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cheque: optional object { bankAccount, currencyCode, description, 12 more }`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bankAccount: optional string`
ID of the bank account to use for the cheque.
- `currencyCode: optional "CAD" or "USD"`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: optional string`
An optional description.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `letterSettings: optional object { color }`
Settings for the attached letter (e.g., color printing).
- `color: optional boolean`
Whether to print the attached letter in color.
- `letterTemplate: optional string`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letterUploadedPDF: optional string`
A signed URL to the attached letter PDF, if any.
- `logo: optional string`
A publicly accessible URL for the logo to print on the cheque.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string`
Memo line text for the cheque.
- `mergeVariables: optional map[unknown]`
Default merge variables for the cheque.
- `message: optional string`
Message included on the cheque stub.
- `metadata: optional map[string]`
Optional key-value metadata.
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `defaultSenderContact: optional string`
The ID of the default sender contact to use for orders if not specified per recipient.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "processing_error" or "internal_error"`
Type of error encountered during campaign processing.
- `"processing_error"`
- `"internal_error"`
- `letter: optional object { addressPlacement, attachedPDF, color, 13 more }`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: optional boolean`
Whether to print in color.
- `description: optional string`
An optional description.
- `doubleSided: optional boolean`
Whether to print on both sides of the paper.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `envelopeType: optional "standard_double_window" or "flat"`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the letter.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforatedPage: optional 1`
Which page number should be perforated (if any).
- `1`
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: optional string`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `orderPreviewURL: optional string`
A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.
- `postcard: optional object { backTemplate, description, frontTemplate, 6 more }`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `backTemplate: optional string`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: optional string`
An optional description.
- `frontTemplate: optional string`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the postcard.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
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 "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `selfMailer: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the self-mailer.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `sendDate: optional string`
The scheduled date and time for the campaign to be sent.
- `snapPack: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the snap pack.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/campaigns/$ID \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
**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.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with campaign_
- `deleted: true`
- `true`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/campaigns/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "campaign_sqF12lZ1VlBb",
"deleted": true
}
```
## Send 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.
### Path Parameters
- `id: string`
### Body Parameters
- `sendDate: optional string or string`
The date and time the campaign should be sent. Must be in the future. If omitted, defaults to the earliest possible processing date.
- `string`
- `string`
### Returns
- `Campaign object { id, createdAt, createdCount, 16 more }`
Represents a bulk mail campaign.
- `id: string`
A unique ID prefixed with campaign_
- `createdAt: string`
The UTC time at which this resource was created.
- `createdCount: number`
The number of orders successfully created for this campaign.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingList: string`
The ID of the mailing list associated with this campaign.
- `status: "drafting" or "changes_required" or "creating_orders" or 4 more`
Status of the campaign lifecycle.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cheque: optional object { bankAccount, currencyCode, description, 12 more }`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bankAccount: optional string`
ID of the bank account to use for the cheque.
- `currencyCode: optional "CAD" or "USD"`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: optional string`
An optional description.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `letterSettings: optional object { color }`
Settings for the attached letter (e.g., color printing).
- `color: optional boolean`
Whether to print the attached letter in color.
- `letterTemplate: optional string`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letterUploadedPDF: optional string`
A signed URL to the attached letter PDF, if any.
- `logo: optional string`
A publicly accessible URL for the logo to print on the cheque.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string`
Memo line text for the cheque.
- `mergeVariables: optional map[unknown]`
Default merge variables for the cheque.
- `message: optional string`
Message included on the cheque stub.
- `metadata: optional map[string]`
Optional key-value metadata.
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `defaultSenderContact: optional string`
The ID of the default sender contact to use for orders if not specified per recipient.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "processing_error" or "internal_error"`
Type of error encountered during campaign processing.
- `"processing_error"`
- `"internal_error"`
- `letter: optional object { addressPlacement, attachedPDF, color, 13 more }`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: optional boolean`
Whether to print in color.
- `description: optional string`
An optional description.
- `doubleSided: optional boolean`
Whether to print on both sides of the paper.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `envelopeType: optional "standard_double_window" or "flat"`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the letter.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforatedPage: optional 1`
Which page number should be perforated (if any).
- `1`
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: optional string`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `orderPreviewURL: optional string`
A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.
- `postcard: optional object { backTemplate, description, frontTemplate, 6 more }`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `backTemplate: optional string`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: optional string`
An optional description.
- `frontTemplate: optional string`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the postcard.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
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 "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `selfMailer: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the self-mailer.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `sendDate: optional string`
The scheduled date and time for the campaign to be sent.
- `snapPack: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the snap pack.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/campaigns/$ID/send \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
- `Campaign object { id, createdAt, createdCount, 16 more }`
Represents a bulk mail campaign.
- `id: string`
A unique ID prefixed with campaign_
- `createdAt: string`
The UTC time at which this resource was created.
- `createdCount: number`
The number of orders successfully created for this campaign.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingList: string`
The ID of the mailing list associated with this campaign.
- `status: "drafting" or "changes_required" or "creating_orders" or 4 more`
Status of the campaign lifecycle.
- `"drafting"`
- `"changes_required"`
- `"creating_orders"`
- `"draft"`
- `"ready"`
- `"printing"`
- `"processed_for_delivery"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cheque: optional object { bankAccount, currencyCode, description, 12 more }`
Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `bankAccount: optional string`
ID of the bank account to use for the cheque.
- `currencyCode: optional "CAD" or "USD"`
Enum representing the supported currency codes.
- `"CAD"`
- `"USD"`
- `description: optional string`
An optional description.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `letterSettings: optional object { color }`
Settings for the attached letter (e.g., color printing).
- `color: optional boolean`
Whether to print the attached letter in color.
- `letterTemplate: optional string`
ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
- `letterUploadedPDF: optional string`
A signed URL to the attached letter PDF, if any.
- `logo: optional string`
A publicly accessible URL for the logo to print on the cheque.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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 string`
Memo line text for the cheque.
- `mergeVariables: optional map[unknown]`
Default merge variables for the cheque.
- `message: optional string`
Message included on the cheque stub.
- `metadata: optional map[string]`
Optional key-value metadata.
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional ChequeSize`
Enum representing the supported cheque sizes.
- `"us_letter"`
- `"us_legal"`
- `defaultSenderContact: optional string`
The ID of the default sender contact to use for orders if not specified per recipient.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "processing_error" or "internal_error"`
Type of error encountered during campaign processing.
- `"processing_error"`
- `"internal_error"`
- `letter: optional object { addressPlacement, attachedPDF, color, 13 more }`
Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `addressPlacement: optional AddressPlacement`
Enum representing the placement of the address on the letter.
- `"top_first_page"`
- `"insert_blank_page"`
- `attachedPDF: optional AttachedPdf`
Model representing an attached PDF.
- `file: string`
The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
- `placement: "before_template" or "after_template"`
Enum representing the placement of the attached PDF.
- `"before_template"`
- `"after_template"`
- `color: optional boolean`
Whether to print in color.
- `description: optional string`
An optional description.
- `doubleSided: optional boolean`
Whether to print on both sides of the paper.
- `envelope: optional string`
The custom envelope ID or `"standard"`.
- `envelopeType: optional "standard_double_window" or "flat"`
The type of envelope used for the letter.
- `"standard_double_window"`
- `"flat"`
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the letter.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "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"`
- `PremiumPaperID = string`
Premium paper identifier.
`standard` is always accepted. Organizations may also have additional
custom `premium_paper_*` IDs beyond the built-in values documented here.
- `perforatedPage: optional 1`
Which page number should be perforated (if any).
- `1`
- `returnEnvelope: optional string`
ID of a return envelope to include.
- `size: optional LetterSize`
Enum representing the supported letter sizes.
- `"us_letter"`
- `"a4"`
- `template: optional string`
ID of a template for the letter content. Cannot be used with `pdf`.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `orderPreviewURL: optional string`
A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.
- `postcard: optional object { backTemplate, description, frontTemplate, 6 more }`
Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `backTemplate: optional string`
ID of the template for the back side. Cannot be used with `pdf`.
- `description: optional string`
An optional description.
- `frontTemplate: optional string`
ID of the template for the front side. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the postcard.
- `metadata: optional map[string]`
Optional key-value metadata.
- `paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string`
Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".
- `PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 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"`
- `PremiumPaperID = string`
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 "6x4" or "9x6" or "11x6"`
Enum representing the supported postcard sizes.
- `"6x4"`
- `"9x6"`
- `"11x6"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the campaign is in the `ready` status.
- `selfMailer: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the self-mailer.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"`
Enum representing the supported self-mailer sizes.
- `"8.5x11_bifold"`
- `"8.5x11_trifold"`
- `"9.5x16_trifold"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
- `sendDate: optional string`
The scheduled date and time for the campaign to be sent.
- `snapPack: optional object { description, insideTemplate, mailingClass, 5 more }`
Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
- `description: optional string`
An optional description.
- `insideTemplate: optional string`
ID of the template for the inside. Cannot be used with `pdf`.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
Default merge variables for the snap pack.
- `metadata: optional map[string]`
Optional key-value metadata.
- `outsideTemplate: optional string`
ID of the template for the outside. Cannot be used with `pdf`.
- `size: optional "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF, if any.
### Campaign Delete Response
- `CampaignDeleteResponse object { id, deleted }`
- `id: string`
A unique ID prefixed with campaign_
- `deleted: true`
- `true`
# Mailing List Imports
## Create Mailing List Import
**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.
### Header Parameters
- `"idempotency-key": optional string`
### Body Parameters
- `file: string`
The CSV file for this import.
- `fileType: FileType`
Type of file supported for mailing list imports.
- `"csv"`
- `receiverAddressMapping: map[string]`
Mapping of columns for receiver addresses.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `receiverMergeVariableMapping: optional map[string]`
Optional mapping of columns for receiver merge variables.
- `senderAddressMapping: optional map[string]`
Optional mapping of columns for sender addresses.
If this is present, then all receivers should have a corresponding sender.
- `senderMergeVariableMapping: optional map[string]`
Optional mapping of columns for sender merge variables.
### Returns
- `MailingListImportResponse object { id, createdAt, errors, 13 more }`
Read-only view of a MailingListImport
- `id: string`
A unique ID prefixed with mailing_list_import_
- `createdAt: string`
The UTC time at which this resource was created.
- `errors: array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "internal_service_error"`
Type of error encountered during import processing.
- `"no_valid_contacts_error"`
- `"multiple_countries_error"`
- `"invalid_contact_count_error"`
- `"internal_service_error"`
- `file: object { fileType, receiverAddressMapping, url, 3 more }`
The file object your controller returns: all the mappings plus a signed URL.
- `fileType: FileType`
Type of file supported for mailing list imports.
- `"csv"`
- `receiverAddressMapping: map[string]`
Mapping of columns for receiver addresses.
Contact fields to file columns.
Possible Contact fields:
- description
- firstName
- lastName
- email
- phoneNumber
- companyName
- addressLine1
- addressLine2
- jobTitle
- city
- postalOrZip
- provinceOrState
- countryCode
- `url: string`
The signed URL your controller generates.
- `receiverMergeVariableMapping: optional map[string]`
Optional mapping of columns for receiver merge variables.
- `senderAddressMapping: optional map[string]`
Optional mapping of columns for sender addresses.
- `senderMergeVariableMapping: optional map[string]`
Optional mapping of columns for sender merge variables.
- `invalidRowCount: number`
Number of invalid rows found in the file.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `notes: array of object { message, type }`
Additional notes about the import process.
- `message: string`
A human-readable message describing the note.
- `type: "truncated_test_file" or "skipped_invalid_contacts"`
Type of note attached to the import process.
- `"truncated_test_file"`
- `"skipped_invalid_contacts"`
- `organization: string`
The organization that owns this import.
- `receiverStatusCount: VerificationStatusCount`
Count of contact verification statuses.
- `correctedCount: number`
Number of contacts that were corrected during verification.
- `failedCount: number`
Number of contacts that failed verification.
- `verifiedCount: number`
Number of contacts that were verified without changes.
- `status: "validating" or "completed" or "changes_required"`
Status of the mailing list import process.
- `"validating"`
- `"completed"`
- `"changes_required"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `validRowCount: number`
Number of valid rows processed from the file.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the import is completed.
- `senderStatusCount: optional VerificationStatusCount`
Count of contact verification statuses.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_list_imports \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"file": "https://signed-upload-url.csv",
"fileType": "csv",
"receiverAddressMapping": {
"description": "Description",
"firstName": "First Name",
"lastName": "Last Name",
"email": "Email",
"addressLine1": "Address",
"city": "City",
"postalOrZip": "Postal Code",
"provinceOrState": "State",
"countryCode": "Country"
}
}'
```
#### 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
**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.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of MailingListImportResponse`
- `id: string`
A unique ID prefixed with mailing_list_import_
- `createdAt: string`
The UTC time at which this resource was created.
- `errors: array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "internal_service_error"`
Type of error encountered during import processing.
- `"no_valid_contacts_error"`
- `"multiple_countries_error"`
- `"invalid_contact_count_error"`
- `"internal_service_error"`
- `file: object { fileType, receiverAddressMapping, url, 3 more }`
The file object your controller returns: all the mappings plus a signed URL.
- `fileType: FileType`
Type of file supported for mailing list imports.
- `"csv"`
- `receiverAddressMapping: map[string]`
Mapping of columns for receiver addresses.
Contact fields to file columns.
Possible Contact fields:
- description
- firstName
- lastName
- email
- phoneNumber
- companyName
- addressLine1
- addressLine2
- jobTitle
- city
- postalOrZip
- provinceOrState
- countryCode
- `url: string`
The signed URL your controller generates.
- `receiverMergeVariableMapping: optional map[string]`
Optional mapping of columns for receiver merge variables.
- `senderAddressMapping: optional map[string]`
Optional mapping of columns for sender addresses.
- `senderMergeVariableMapping: optional map[string]`
Optional mapping of columns for sender merge variables.
- `invalidRowCount: number`
Number of invalid rows found in the file.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `notes: array of object { message, type }`
Additional notes about the import process.
- `message: string`
A human-readable message describing the note.
- `type: "truncated_test_file" or "skipped_invalid_contacts"`
Type of note attached to the import process.
- `"truncated_test_file"`
- `"skipped_invalid_contacts"`
- `organization: string`
The organization that owns this import.
- `receiverStatusCount: VerificationStatusCount`
Count of contact verification statuses.
- `correctedCount: number`
Number of contacts that were corrected during verification.
- `failedCount: number`
Number of contacts that failed verification.
- `verifiedCount: number`
Number of contacts that were verified without changes.
- `status: "validating" or "completed" or "changes_required"`
Status of the mailing list import process.
- `"validating"`
- `"completed"`
- `"changes_required"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `validRowCount: number`
Number of valid rows processed from the file.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the import is completed.
- `senderStatusCount: optional VerificationStatusCount`
Count of contact verification statuses.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_list_imports \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**post** `/print-mail/v1/mailing_list_imports/{id}`
Update an existing mailing list import.
### Path Parameters
- `id: string`
### Body Parameters
- `description: optional string`
An optional description for the import. Set to `null` to remove the existing description.
- `metadata: optional map[string]`
Optional key-value data associated with the import. Set to `null` to remove existing metadata.
### Returns
- `MailingListImportResponse object { id, createdAt, errors, 13 more }`
Read-only view of a MailingListImport
- `id: string`
A unique ID prefixed with mailing_list_import_
- `createdAt: string`
The UTC time at which this resource was created.
- `errors: array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "internal_service_error"`
Type of error encountered during import processing.
- `"no_valid_contacts_error"`
- `"multiple_countries_error"`
- `"invalid_contact_count_error"`
- `"internal_service_error"`
- `file: object { fileType, receiverAddressMapping, url, 3 more }`
The file object your controller returns: all the mappings plus a signed URL.
- `fileType: FileType`
Type of file supported for mailing list imports.
- `"csv"`
- `receiverAddressMapping: map[string]`
Mapping of columns for receiver addresses.
Contact fields to file columns.
Possible Contact fields:
- description
- firstName
- lastName
- email
- phoneNumber
- companyName
- addressLine1
- addressLine2
- jobTitle
- city
- postalOrZip
- provinceOrState
- countryCode
- `url: string`
The signed URL your controller generates.
- `receiverMergeVariableMapping: optional map[string]`
Optional mapping of columns for receiver merge variables.
- `senderAddressMapping: optional map[string]`
Optional mapping of columns for sender addresses.
- `senderMergeVariableMapping: optional map[string]`
Optional mapping of columns for sender merge variables.
- `invalidRowCount: number`
Number of invalid rows found in the file.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `notes: array of object { message, type }`
Additional notes about the import process.
- `message: string`
A human-readable message describing the note.
- `type: "truncated_test_file" or "skipped_invalid_contacts"`
Type of note attached to the import process.
- `"truncated_test_file"`
- `"skipped_invalid_contacts"`
- `organization: string`
The organization that owns this import.
- `receiverStatusCount: VerificationStatusCount`
Count of contact verification statuses.
- `correctedCount: number`
Number of contacts that were corrected during verification.
- `failedCount: number`
Number of contacts that failed verification.
- `verifiedCount: number`
Number of contacts that were verified without changes.
- `status: "validating" or "completed" or "changes_required"`
Status of the mailing list import process.
- `"validating"`
- `"completed"`
- `"changes_required"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `validRowCount: number`
Number of valid rows processed from the file.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the import is completed.
- `senderStatusCount: optional VerificationStatusCount`
Count of contact verification statuses.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_list_imports/$ID \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
**get** `/print-mail/v1/mailing_list_imports/{id}`
Retrieve a specific mailing list import by its ID.
### Path Parameters
- `id: string`
### Returns
- `MailingListImportResponse object { id, createdAt, errors, 13 more }`
Read-only view of a MailingListImport
- `id: string`
A unique ID prefixed with mailing_list_import_
- `createdAt: string`
The UTC time at which this resource was created.
- `errors: array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "internal_service_error"`
Type of error encountered during import processing.
- `"no_valid_contacts_error"`
- `"multiple_countries_error"`
- `"invalid_contact_count_error"`
- `"internal_service_error"`
- `file: object { fileType, receiverAddressMapping, url, 3 more }`
The file object your controller returns: all the mappings plus a signed URL.
- `fileType: FileType`
Type of file supported for mailing list imports.
- `"csv"`
- `receiverAddressMapping: map[string]`
Mapping of columns for receiver addresses.
Contact fields to file columns.
Possible Contact fields:
- description
- firstName
- lastName
- email
- phoneNumber
- companyName
- addressLine1
- addressLine2
- jobTitle
- city
- postalOrZip
- provinceOrState
- countryCode
- `url: string`
The signed URL your controller generates.
- `receiverMergeVariableMapping: optional map[string]`
Optional mapping of columns for receiver merge variables.
- `senderAddressMapping: optional map[string]`
Optional mapping of columns for sender addresses.
- `senderMergeVariableMapping: optional map[string]`
Optional mapping of columns for sender merge variables.
- `invalidRowCount: number`
Number of invalid rows found in the file.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `notes: array of object { message, type }`
Additional notes about the import process.
- `message: string`
A human-readable message describing the note.
- `type: "truncated_test_file" or "skipped_invalid_contacts"`
Type of note attached to the import process.
- `"truncated_test_file"`
- `"skipped_invalid_contacts"`
- `organization: string`
The organization that owns this import.
- `receiverStatusCount: VerificationStatusCount`
Count of contact verification statuses.
- `correctedCount: number`
Number of contacts that were corrected during verification.
- `failedCount: number`
Number of contacts that failed verification.
- `verifiedCount: number`
Number of contacts that were verified without changes.
- `status: "validating" or "completed" or "changes_required"`
Status of the mailing list import process.
- `"validating"`
- `"completed"`
- `"changes_required"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `validRowCount: number`
Number of valid rows processed from the file.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the import is completed.
- `senderStatusCount: optional VerificationStatusCount`
Count of contact verification statuses.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_list_imports/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with mailing_list_import_
- `deleted: true`
- `true`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_list_imports/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "mailing_list_import_123",
"deleted": true
}
```
## Domain Types
### File Type
- `FileType = "csv"`
Type of file supported for mailing list imports.
- `"csv"`
### Mailing List Import Response
- `MailingListImportResponse object { id, createdAt, errors, 13 more }`
Read-only view of a MailingListImport
- `id: string`
A unique ID prefixed with mailing_list_import_
- `createdAt: string`
The UTC time at which this resource was created.
- `errors: array of object { message, type }`
A list of processing errors encountered, if any. Present when status is 'changes_required'.
- `message: string`
A human-readable message describing the error.
- `type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "internal_service_error"`
Type of error encountered during import processing.
- `"no_valid_contacts_error"`
- `"multiple_countries_error"`
- `"invalid_contact_count_error"`
- `"internal_service_error"`
- `file: object { fileType, receiverAddressMapping, url, 3 more }`
The file object your controller returns: all the mappings plus a signed URL.
- `fileType: FileType`
Type of file supported for mailing list imports.
- `"csv"`
- `receiverAddressMapping: map[string]`
Mapping of columns for receiver addresses.
Contact fields to file columns.
Possible Contact fields:
- description
- firstName
- lastName
- email
- phoneNumber
- companyName
- addressLine1
- addressLine2
- jobTitle
- city
- postalOrZip
- provinceOrState
- countryCode
- `url: string`
The signed URL your controller generates.
- `receiverMergeVariableMapping: optional map[string]`
Optional mapping of columns for receiver merge variables.
- `senderAddressMapping: optional map[string]`
Optional mapping of columns for sender addresses.
- `senderMergeVariableMapping: optional map[string]`
Optional mapping of columns for sender merge variables.
- `invalidRowCount: number`
Number of invalid rows found in the file.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `notes: array of object { message, type }`
Additional notes about the import process.
- `message: string`
A human-readable message describing the note.
- `type: "truncated_test_file" or "skipped_invalid_contacts"`
Type of note attached to the import process.
- `"truncated_test_file"`
- `"skipped_invalid_contacts"`
- `organization: string`
The organization that owns this import.
- `receiverStatusCount: VerificationStatusCount`
Count of contact verification statuses.
- `correctedCount: number`
Number of contacts that were corrected during verification.
- `failedCount: number`
Number of contacts that failed verification.
- `verifiedCount: number`
Number of contacts that were verified without changes.
- `status: "validating" or "completed" or "changes_required"`
Status of the mailing list import process.
- `"validating"`
- `"completed"`
- `"changes_required"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `validRowCount: number`
Number of valid rows processed from the file.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `reportURL: optional string`
A temporary URL to download the processing report, available once the import is completed.
- `senderStatusCount: optional VerificationStatusCount`
Count of contact verification statuses.
### Verification Status Count
- `VerificationStatusCount object { correctedCount, failedCount, verifiedCount }`
Count of contact verification statuses.
- `correctedCount: number`
Number of contacts that were corrected during verification.
- `failedCount: number`
Number of contacts that failed verification.
- `verifiedCount: number`
Number of contacts that were verified without changes.
### Mailing List Import Delete Response
- `MailingListImportDeleteResponse object { id, deleted }`
- `id: string`
A unique ID prefixed with mailing_list_import_
- `deleted: true`
- `true`
# Mailing Lists
## Create Mailing List
**post** `/print-mail/v1/mailing_lists`
Create a new mailing list.
### Header Parameters
- `"idempotency-key": optional string`
### Body Parameters
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Returns
- `MailingList object { id, createdAt, live, 5 more }`
Represents a mailing list.
- `id: string`
A unique ID prefixed with mailing_list_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"`
Status of the mailing list processing.
- `"creating_contacts"`
- `"removing_contacts"`
- `"counting_recipient_country_codes"`
- `"completed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any.
- `message: string`
A human-readable message describing the error.
- `type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "internal_service_error"`
Type of error encountered during mailing list processing.
- `"mailing_list_imports_not_found_error"`
- `"download_file_error"`
- `"operational_error"`
- `"internal_service_error"`
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_lists \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
**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.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of MailingList`
- `id: string`
A unique ID prefixed with mailing_list_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"`
Status of the mailing list processing.
- `"creating_contacts"`
- `"removing_contacts"`
- `"counting_recipient_country_codes"`
- `"completed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any.
- `message: string`
A human-readable message describing the error.
- `type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "internal_service_error"`
Type of error encountered during mailing list processing.
- `"mailing_list_imports_not_found_error"`
- `"download_file_error"`
- `"operational_error"`
- `"internal_service_error"`
- `metadata: optional map[unknown]`
See the section on Metadata.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_lists \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/mailing_lists/{id}`
Retrieve a specific mailing list by its ID.
### Path Parameters
- `id: string`
### Returns
- `MailingList object { id, createdAt, live, 5 more }`
Represents a mailing list.
- `id: string`
A unique ID prefixed with mailing_list_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"`
Status of the mailing list processing.
- `"creating_contacts"`
- `"removing_contacts"`
- `"counting_recipient_country_codes"`
- `"completed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any.
- `message: string`
A human-readable message describing the error.
- `type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "internal_service_error"`
Type of error encountered during mailing list processing.
- `"mailing_list_imports_not_found_error"`
- `"download_file_error"`
- `"operational_error"`
- `"internal_service_error"`
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**post** `/print-mail/v1/mailing_lists/{id}`
Update an existing mailing list.
### Path Parameters
- `id: string`
### Body Parameters
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Returns
- `MailingListUpdate object { description, metadata }`
Parameters for updating an existing mailing list.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### Response
```json
{
"description": "Test Mailing List",
"metadata": {
"campaign": "launch"
}
}
```
## Delete Mailing List
**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.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with mailing_list_
- `deleted: true`
- `true`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "mailing_list_sqF12lZ1VlBb",
"deleted": true
}
```
## Submit a Mailing List Job
**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.
### Path Parameters
- `id: string`
### Body Parameters
- `addContacts: optional array of string`
List of contact IDs to add to the mailing list. Cannot be used with other operations.
- `addMailingListImports: optional array of string`
List of mailing list import IDs to add to the mailing list. Cannot be used with other operations.
- `removeContacts: optional array of string`
List of contact IDs to remove from the mailing list. Cannot be used with other operations.
- `removeMailingListImports: optional array of string`
List of mailing list import IDs to remove from the mailing list. Cannot be used with other operations.
### Returns
- `MailingList object { id, createdAt, live, 5 more }`
Represents a mailing list.
- `id: string`
A unique ID prefixed with mailing_list_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"`
Status of the mailing list processing.
- `"creating_contacts"`
- `"removing_contacts"`
- `"counting_recipient_country_codes"`
- `"completed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any.
- `message: string`
A human-readable message describing the error.
- `type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "internal_service_error"`
Type of error encountered during mailing list processing.
- `"mailing_list_imports_not_found_error"`
- `"download_file_error"`
- `"operational_error"`
- `"internal_service_error"`
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID/jobs \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
- `MailingList object { id, createdAt, live, 5 more }`
Represents a mailing list.
- `id: string`
A unique ID prefixed with mailing_list_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"`
Status of the mailing list processing.
- `"creating_contacts"`
- `"removing_contacts"`
- `"counting_recipient_country_codes"`
- `"completed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
A list of processing errors encountered, if any.
- `message: string`
A human-readable message describing the error.
- `type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "internal_service_error"`
Type of error encountered during mailing list processing.
- `"mailing_list_imports_not_found_error"`
- `"download_file_error"`
- `"operational_error"`
- `"internal_service_error"`
- `metadata: optional map[unknown]`
See the section on Metadata.
### Mailing List Update
- `MailingListUpdate object { description, metadata }`
Parameters for updating an existing mailing list.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Mailing List Delete Response
- `MailingListDeleteResponse object { id, deleted }`
- `id: string`
A unique ID prefixed with mailing_list_
- `deleted: true`
- `true`
# Reports
## Create Saved 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.
### Body Parameters
- `sqlQuery: string`
The SQL query defining the report.
- `description: optional string`
An optional user-friendly description for the report.
- `metadata: optional map[string]`
Optional key-value metadata associated with the report.
### Returns
- `Report object { id, createdAt, live, 5 more }`
Represents a saved Report definition.
- `id: string`
Unique identifier for the report.
- `createdAt: string`
Timestamp when the report was created.
- `live: boolean`
Indicates if the report is associated with the live or test environment.
- `object: "report"`
Always `report`.
- `"report"`
- `sqlQuery: string`
The SQL query defining the report.
- `updatedAt: string`
Timestamp when the report was last updated.
- `description: optional string`
An optional user-friendly description for the report.
- `metadata: optional map[string]`
Optional key-value metadata associated with the report.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/reports \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?"
}'
```
#### 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
**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.
### Body Parameters
- `sqlQuery: string`
The SQL query to execute for the sample.
- `limit: optional number`
Maximum number of rows to return in the sample.
- `params: optional array of string`
Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).
### Returns
- `ReportSample object { id, records, report }`
Represents the result of a report sample query.
- `id: string`
Unique identifier for the sample query result.
- `records: array of map[unknown]`
The actual data records returned by the sample query.
- `report: string`
The ID of the report this sample was generated from, or null for ad-hoc samples.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/reports/samples \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"sqlQuery": "sqlQuery"
}'
```
#### Response
```json
{
"id": "sample_abc",
"report": "report_123",
"records": [
{
"id": "order_1"
},
{
"id": "order_2"
}
]
}
```
## Update Report
**post** `/print-mail/v1/reports/{id}`
Update an existing saved report definition. You can change the query, description, or metadata.
### Path Parameters
- `id: string`
### Body Parameters
- `description: optional string`
An optional user-friendly description for the report. Set to null to remove.
- `metadata: optional map[string]`
Optional key-value metadata associated with the report. Set to null to remove.
- `sqlQuery: optional string`
The SQL query defining the report.
### Returns
- `Report object { id, createdAt, live, 5 more }`
Represents a saved Report definition.
- `id: string`
Unique identifier for the report.
- `createdAt: string`
Timestamp when the report was created.
- `live: boolean`
Indicates if the report is associated with the live or test environment.
- `object: "report"`
Always `report`.
- `"report"`
- `sqlQuery: string`
The SQL query defining the report.
- `updatedAt: string`
Timestamp when the report was last updated.
- `description: optional string`
An optional user-friendly description for the report.
- `metadata: optional map[string]`
Optional key-value metadata associated with the report.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/reports/$ID \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
**get** `/print-mail/v1/reports`
Retrieve a list of saved reports for your organization.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of Report`
- `id: string`
Unique identifier for the report.
- `createdAt: string`
Timestamp when the report was created.
- `live: boolean`
Indicates if the report is associated with the live or test environment.
- `object: "report"`
Always `report`.
- `"report"`
- `sqlQuery: string`
The SQL query defining the report.
- `updatedAt: string`
Timestamp when the report was last updated.
- `description: optional string`
An optional user-friendly description for the report.
- `metadata: optional map[string]`
Optional key-value metadata associated with the report.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/reports \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/reports/{id}`
Retrieve the details of a specific saved report by its ID.
### Path Parameters
- `id: string`
### Returns
- `Report object { id, createdAt, live, 5 more }`
Represents a saved Report definition.
- `id: string`
Unique identifier for the report.
- `createdAt: string`
Timestamp when the report was created.
- `live: boolean`
Indicates if the report is associated with the live or test environment.
- `object: "report"`
Always `report`.
- `"report"`
- `sqlQuery: string`
The SQL query defining the report.
- `updatedAt: string`
Timestamp when the report was last updated.
- `description: optional string`
An optional user-friendly description for the report.
- `metadata: optional map[string]`
Optional key-value metadata associated with the report.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/reports/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**delete** `/print-mail/v1/reports/{id}`
Delete a saved report definition. This action cannot be undone.
Associated exports are not automatically deleted.
### Path Parameters
- `id: string`
### Returns
- `DeletedResponse object { id, deleted }`
Generic response for delete operations.
- `id: string`
The ID of the deleted resource.
- `deleted: true`
Indicates the resource was successfully deleted.
- `true`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/reports/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "report_123",
"deleted": true
}
```
## Domain Types
### Deleted Response
- `DeletedResponse object { id, deleted }`
Generic response for delete operations.
- `id: string`
The ID of the deleted resource.
- `deleted: true`
Indicates the resource was successfully deleted.
- `true`
### Report
- `Report object { id, createdAt, live, 5 more }`
Represents a saved Report definition.
- `id: string`
Unique identifier for the report.
- `createdAt: string`
Timestamp when the report was created.
- `live: boolean`
Indicates if the report is associated with the live or test environment.
- `object: "report"`
Always `report`.
- `"report"`
- `sqlQuery: string`
The SQL query defining the report.
- `updatedAt: string`
Timestamp when the report was last updated.
- `description: optional string`
An optional user-friendly description for the report.
- `metadata: optional map[string]`
Optional key-value metadata associated with the report.
# Samples
## Sample a Saved Report
**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.
### Path Parameters
- `id: string`
### Body Parameters
- `limit: optional number`
Maximum number of rows to return in the sample.
- `params: optional array of string`
Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).
### Returns
- `ReportSample object { id, records, report }`
Represents the result of a report sample query.
- `id: string`
Unique identifier for the sample query result.
- `records: array of map[unknown]`
The actual data records returned by the sample query.
- `report: string`
The ID of the report this sample was generated from, or null for ad-hoc samples.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/reports/$ID/samples \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### Response
```json
{
"id": "sample_abc",
"report": "report_123",
"records": [
{
"id": "order_1"
},
{
"id": "order_2"
}
]
}
```
## Domain Types
### Report Sample
- `ReportSample object { id, records, report }`
Represents the result of a report sample query.
- `id: string`
Unique identifier for the sample query result.
- `records: array of map[unknown]`
The actual data records returned by the sample query.
- `report: string`
The ID of the report this sample was generated from, or null for ad-hoc samples.
### Report Sample Create Base
- `ReportSampleCreateBase object { limit, params }`
Base properties for creating a report sample.
- `limit: optional number`
Maximum number of rows to return in the sample.
- `params: optional array of string`
Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).
# Exports
## Create a Report Export
**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.
### Path Parameters
- `reportID: string`
### Body Parameters
- `description: optional string`
An optional user-friendly description for the export.
- `metadata: optional map[string]`
Optional key-value metadata associated with the export.
- `params: optional array of string`
Optional parameters to bind to the SQL query of the associated report.
### Returns
- `ReportExport object { id, createdAt, live, 11 more }`
Represents a report export job and its results.
- `id: string`
Unique identifier for the report export.
- `createdAt: string`
Timestamp when the export was created.
- `live: boolean`
Indicates if the export is associated with the live or test environment.
- `object: "report_export"`
Always `report_export`.
- `"report_export"`
- `report: object { id, sqlQuery }`
Details of the report this export was generated from.
- `id: string`
The ID of the report.
- `sqlQuery: string`
The SQL query used for this export (snapshotted at creation time).
- `updatedAt: string`
Timestamp when the export was last updated (e.g., finished generation).
- `description: optional string`
An optional user-friendly description for the export.
- `failureMessage: optional string`
If export generation failed, this contains the error message.
- `metadata: optional map[string]`
Optional key-value metadata associated with the export.
- `outputURL: optional string`
A signed URL to download the exported data (CSV format). Available when generation is complete and successful.
- `params: optional array of string`
Optional parameters to bind to the SQL query of the associated report.
- `rowCount: optional number`
The number of rows in the exported data.
- `sizeInBytes: optional number`
The size of the generated export file in bytes.
- `truncatedToBytes: optional number`
If the output was truncated, indicates the byte limit reached.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/reports/$REPORT_ID/exports \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
**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.
### Path Parameters
- `reportID: string`
- `exportID: string`
### Returns
- `ReportExport object { id, createdAt, live, 11 more }`
Represents a report export job and its results.
- `id: string`
Unique identifier for the report export.
- `createdAt: string`
Timestamp when the export was created.
- `live: boolean`
Indicates if the export is associated with the live or test environment.
- `object: "report_export"`
Always `report_export`.
- `"report_export"`
- `report: object { id, sqlQuery }`
Details of the report this export was generated from.
- `id: string`
The ID of the report.
- `sqlQuery: string`
The SQL query used for this export (snapshotted at creation time).
- `updatedAt: string`
Timestamp when the export was last updated (e.g., finished generation).
- `description: optional string`
An optional user-friendly description for the export.
- `failureMessage: optional string`
If export generation failed, this contains the error message.
- `metadata: optional map[string]`
Optional key-value metadata associated with the export.
- `outputURL: optional string`
A signed URL to download the exported data (CSV format). Available when generation is complete and successful.
- `params: optional array of string`
Optional parameters to bind to the SQL query of the associated report.
- `rowCount: optional number`
The number of rows in the exported data.
- `sizeInBytes: optional number`
The size of the generated export file in bytes.
- `truncatedToBytes: optional number`
If the output was truncated, indicates the byte limit reached.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/reports/$REPORT_ID/exports/$EXPORT_ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `reportID: string`
- `exportID: string`
### Returns
- `DeletedResponse object { id, deleted }`
Generic response for delete operations.
- `id: string`
The ID of the deleted resource.
- `deleted: true`
Indicates the resource was successfully deleted.
- `true`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/reports/$REPORT_ID/exports/$EXPORT_ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "report_export_123",
"deleted": true
}
```
## Domain Types
### Report Export
- `ReportExport object { id, createdAt, live, 11 more }`
Represents a report export job and its results.
- `id: string`
Unique identifier for the report export.
- `createdAt: string`
Timestamp when the export was created.
- `live: boolean`
Indicates if the export is associated with the live or test environment.
- `object: "report_export"`
Always `report_export`.
- `"report_export"`
- `report: object { id, sqlQuery }`
Details of the report this export was generated from.
- `id: string`
The ID of the report.
- `sqlQuery: string`
The SQL query used for this export (snapshotted at creation time).
- `updatedAt: string`
Timestamp when the export was last updated (e.g., finished generation).
- `description: optional string`
An optional user-friendly description for the export.
- `failureMessage: optional string`
If export generation failed, this contains the error message.
- `metadata: optional map[string]`
Optional key-value metadata associated with the export.
- `outputURL: optional string`
A signed URL to download the exported data (CSV format). Available when generation is complete and successful.
- `params: optional array of string`
Optional parameters to bind to the SQL query of the associated report.
- `rowCount: optional number`
The number of rows in the exported data.
- `sizeInBytes: optional number`
The size of the generated export file in bytes.
- `truncatedToBytes: optional number`
If the output was truncated, indicates the byte limit reached.
# Sub Organizations
## Create a sub-organization.
**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.
### Body Parameters
- `countryCode: string`
The country code of the sub-organization.
- `email: string`
The email of the user to be created alongside the sub-organization.
- `name: string`
The name of the user to be created alongside the sub-organization.
- `organizationName: string`
The name of the sub-organization.
- `password: string`
The password of the user to be created alongside the sub-organization.
- `phoneNumber: optional string`
The phone number of the user to be created alongside the
sub-organization.
### Returns
- `subOrganization: SubOrganization`
The Sub-Organization object.
- `id: string`
A unique ID prefixed with `sub_org_`.
- `countryCode: string`
The country code of the sub-organization.
- `createdAt: string`
The UTC time at which this resource was created.
- `limit: number`
The limit of mailings the sub-organization can send before being charged
overages for the month.
- `name: string`
The name of the sub-organization.
- `object: "sub_org"`
Always `sub_org`.
- `"sub_org"`
- `spend: number`
The current rolling charge for the sub-organization for the month, in
cents.
- `updatedAt: string`
The UTC time at which this resource was last update.
- `usage: number`
The amount of mail the sub-organization has sent out this month.
- `user: object { id, apiKeys, email, 9 more }`
The user object.
- `id: string`
A unique ID prefixed with `user_`.
- `apiKeys: array of object { value, activeUntil }`
The user's API keys. Contains live and test mode API keys.
- `value: string`
The value of the API key.
- `activeUntil: optional string`
An optional date which the API key is active until. After this date, the
API key will no longer be valid.
- `email: string`
The email of the user.
- `name: string`
The name of the user.
- `organization: string`
A unique ID prefixed with `user_`.
- `pendingInvite: boolean`
Indicates if the user has a pending invite.
- `roles: array of string`
The roles given to the user. Roles can be used to restrict access for
users.
- `verifiedEmail: boolean`
Indicates if the user has a verified email or not.
- `emailPreferences: optional EmailPreferences`
A set of preferences for how a user should receive emails.
- `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"`
The list of preferences for receiving order preview emails.
- `"do_not_send"`
- `"send_live_only"`
- `"send_live_and_test"`
- `lastLoginTime: optional string`
The date and time at which the user last logged in.
- `phoneNumber: optional string`
The phone number of the user.
- `previousEmails: optional array of string`
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
```http
curl https://api.postgrid.com/print-mail/v1/sub_organizations \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"countryCode": "CA",
"email": "suborg@postgrid.com",
"name": "Calvin",
"organizationName": "PostGrid",
"password": "very-strong-password"
}'
```
#### 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.
**get** `/print-mail/v1/sub_organizations`
List sub-organizations.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of SubOrganization`
- `id: string`
A unique ID prefixed with `sub_org_`.
- `countryCode: string`
The country code of the sub-organization.
- `createdAt: string`
The UTC time at which this resource was created.
- `limit: number`
The limit of mailings the sub-organization can send before being charged
overages for the month.
- `name: string`
The name of the sub-organization.
- `object: "sub_org"`
Always `sub_org`.
- `"sub_org"`
- `spend: number`
The current rolling charge for the sub-organization for the month, in
cents.
- `updatedAt: string`
The UTC time at which this resource was last update.
- `usage: number`
The amount of mail the sub-organization has sent out this month.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/sub_organizations \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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.
**get** `/print-mail/v1/sub_organizations/{id}`
Get a sub-organization.
### Path Parameters
- `id: string`
### Returns
- `SubOrganization object { id, countryCode, createdAt, 6 more }`
The Sub-Organization object.
- `id: string`
A unique ID prefixed with `sub_org_`.
- `countryCode: string`
The country code of the sub-organization.
- `createdAt: string`
The UTC time at which this resource was created.
- `limit: number`
The limit of mailings the sub-organization can send before being charged
overages for the month.
- `name: string`
The name of the sub-organization.
- `object: "sub_org"`
Always `sub_org`.
- `"sub_org"`
- `spend: number`
The current rolling charge for the sub-organization for the month, in
cents.
- `updatedAt: string`
The UTC time at which this resource was last update.
- `usage: number`
The amount of mail the sub-organization has sent out this month.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/sub_organizations/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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.
**get** `/print-mail/v1/sub_organizations/{id}/users`
List users for a sub-organization.
### Path Parameters
- `id: string`
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `id: string`
A unique ID prefixed with `user_`.
- `email: string`
The email of the user.
- `name: string`
The name of the user.
- `organization: string`
A unique ID prefixed with `user_`.
- `pendingInvite: boolean`
Indicates if the user has a pending invite.
- `roles: array of string`
The roles given to the user. Roles can be used to restrict access for
users.
- `verifiedEmail: boolean`
Indicates if the user has a verified email or not.
- `emailPreferences: optional EmailPreferences`
A set of preferences for how a user should receive emails.
- `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"`
The list of preferences for receiving order preview emails.
- `"do_not_send"`
- `"send_live_only"`
- `"send_live_and_test"`
- `lastLoginTime: optional string`
The date and time at which the user last logged in.
- `phoneNumber: optional string`
The phone number of the user.
- `previousEmails: optional array of string`
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
```http
curl https://api.postgrid.com/print-mail/v1/sub_organizations/$ID/users \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
- `EmailPreferences object { orderPreviewSendPreference }`
A set of preferences for how a user should receive emails.
- `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"`
The list of preferences for receiving order preview emails.
- `"do_not_send"`
- `"send_live_only"`
- `"send_live_and_test"`
### Sub Organization
- `SubOrganization object { id, countryCode, createdAt, 6 more }`
The Sub-Organization object.
- `id: string`
A unique ID prefixed with `sub_org_`.
- `countryCode: string`
The country code of the sub-organization.
- `createdAt: string`
The UTC time at which this resource was created.
- `limit: number`
The limit of mailings the sub-organization can send before being charged
overages for the month.
- `name: string`
The name of the sub-organization.
- `object: "sub_org"`
Always `sub_org`.
- `"sub_org"`
- `spend: number`
The current rolling charge for the sub-organization for the month, in
cents.
- `updatedAt: string`
The UTC time at which this resource was last update.
- `usage: number`
The amount of mail the sub-organization has sent out this month.
### Sub Organization Create Response
- `SubOrganizationCreateResponse object { subOrganization, user }`
- `subOrganization: SubOrganization`
The Sub-Organization object.
- `id: string`
A unique ID prefixed with `sub_org_`.
- `countryCode: string`
The country code of the sub-organization.
- `createdAt: string`
The UTC time at which this resource was created.
- `limit: number`
The limit of mailings the sub-organization can send before being charged
overages for the month.
- `name: string`
The name of the sub-organization.
- `object: "sub_org"`
Always `sub_org`.
- `"sub_org"`
- `spend: number`
The current rolling charge for the sub-organization for the month, in
cents.
- `updatedAt: string`
The UTC time at which this resource was last update.
- `usage: number`
The amount of mail the sub-organization has sent out this month.
- `user: object { id, apiKeys, email, 9 more }`
The user object.
- `id: string`
A unique ID prefixed with `user_`.
- `apiKeys: array of object { value, activeUntil }`
The user's API keys. Contains live and test mode API keys.
- `value: string`
The value of the API key.
- `activeUntil: optional string`
An optional date which the API key is active until. After this date, the
API key will no longer be valid.
- `email: string`
The email of the user.
- `name: string`
The name of the user.
- `organization: string`
A unique ID prefixed with `user_`.
- `pendingInvite: boolean`
Indicates if the user has a pending invite.
- `roles: array of string`
The roles given to the user. Roles can be used to restrict access for
users.
- `verifiedEmail: boolean`
Indicates if the user has a verified email or not.
- `emailPreferences: optional EmailPreferences`
A set of preferences for how a user should receive emails.
- `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"`
The list of preferences for receiving order preview emails.
- `"do_not_send"`
- `"send_live_only"`
- `"send_live_and_test"`
- `lastLoginTime: optional string`
The date and time at which the user last logged in.
- `phoneNumber: optional string`
The phone number of the user.
- `previousEmails: optional array of string`
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
- `SubOrganizationRetrieveUsersResponse = array of object { id, email, name, 8 more }`
- `id: string`
A unique ID prefixed with `user_`.
- `email: string`
The email of the user.
- `name: string`
The name of the user.
- `organization: string`
A unique ID prefixed with `user_`.
- `pendingInvite: boolean`
Indicates if the user has a pending invite.
- `roles: array of string`
The roles given to the user. Roles can be used to restrict access for
users.
- `verifiedEmail: boolean`
Indicates if the user has a verified email or not.
- `emailPreferences: optional EmailPreferences`
A set of preferences for how a user should receive emails.
- `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"`
The list of preferences for receiving order preview emails.
- `"do_not_send"`
- `"send_live_only"`
- `"send_live_and_test"`
- `lastLoginTime: optional string`
The date and time at which the user last logged in.
- `phoneNumber: optional string`
The phone number of the user.
- `previousEmails: optional array of string`
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
**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
### Body Parameters
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques to be mailed in the box. Only 100 cheques can be included in a box at a time.
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `firstName: string`
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `companyName: string`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `string`
- `number: number`
The cheque number.
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The 'from' (sender) of the entire box. Accepts inline ContactCreate or a contactID.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `sendDate: optional string`
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
- `id: string`
A unique ID prefixed with box_
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques inside this box (in read mode).
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `number: number`
The cheque number.
- `to: Contact`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `createdAt: string`
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: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "box"`
Always "box".
- `"box"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/boxes \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"cheques": [
{
"amount": 5000,
"bankAccount": "bank_abc",
"from": "contact_456",
"number": 1042,
"to": "contact_123"
}
],
"from": "contact_456",
"to": "contact_123"
}'
```
#### 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
**get** `/print-mail/v1/boxes`
List all boxes.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of object { id, cheques, createdAt, 17 more }`
- `id: string`
A unique ID prefixed with box_
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques inside this box (in read mode).
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `number: number`
The cheque number.
- `to: Contact`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `createdAt: string`
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: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "box"`
Always "box".
- `"box"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/boxes \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/boxes/{id}`
Retrieve a box by ID.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with box_
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques inside this box (in read mode).
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `number: number`
The cheque number.
- `to: Contact`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `createdAt: string`
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: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "box"`
Always "box".
- `"box"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/boxes/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**delete** `/print-mail/v1/boxes/{id}`
Cancel a box by ID (cannot be undone).
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with box_
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques inside this box (in read mode).
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `number: number`
The cheque number.
- `to: Contact`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `createdAt: string`
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: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "box"`
Always "box".
- `"box"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/boxes/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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`.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with box_
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques inside this box (in read mode).
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `number: number`
The cheque number.
- `to: Contact`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `createdAt: string`
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: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "box"`
Always "box".
- `"box"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/boxes/$ID/progressions \
-X POST \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
- `BoxCreateResponse object { id, cheques, createdAt, 17 more }`
- `id: string`
A unique ID prefixed with box_
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques inside this box (in read mode).
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `number: number`
The cheque number.
- `to: Contact`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `createdAt: string`
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: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "box"`
Always "box".
- `"box"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Box List Response
- `BoxListResponse object { id, cheques, createdAt, 17 more }`
- `id: string`
A unique ID prefixed with box_
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques inside this box (in read mode).
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `number: number`
The cheque number.
- `to: Contact`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `createdAt: string`
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: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "box"`
Always "box".
- `"box"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Box Retrieve Response
- `BoxRetrieveResponse object { id, cheques, createdAt, 17 more }`
- `id: string`
A unique ID prefixed with box_
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques inside this box (in read mode).
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `number: number`
The cheque number.
- `to: Contact`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `createdAt: string`
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: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "box"`
Always "box".
- `"box"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Box Delete Response
- `BoxDeleteResponse object { id, cheques, createdAt, 17 more }`
- `id: string`
A unique ID prefixed with box_
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques inside this box (in read mode).
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `number: number`
The cheque number.
- `to: Contact`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `createdAt: string`
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: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "box"`
Always "box".
- `"box"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Box Progressions Response
- `BoxProgressionsResponse object { id, cheques, createdAt, 17 more }`
- `id: string`
A unique ID prefixed with box_
- `cheques: array of object { amount, bankAccount, from, 6 more }`
The cheques inside this box (in read mode).
- `amount: number`
The amount on the cheque.
- `bankAccount: string`
The bank account (ID or reference) from which the cheque amount is drawn.
- `from: Contact`
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `number: number`
The cheque number.
- `to: Contact`
- `logoURL: optional string`
A URL to a logo for the cheque (optional).
- `memo: optional string`
The memo text on the cheque (optional).
- `mergeVariables: optional map[unknown]`
A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).
- `messageTemplate: optional string`
An optional message template to be printed on or with the cheque.
- `createdAt: string`
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: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "box"`
Always "box".
- `"box"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
# Snap Packs
## Create Snap Pack
**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
### Body Parameters
- `body: object { from, insideHTML, outsideHTML, 7 more } or object { from, insideTemplate, outsideTemplate, 7 more } or object { from, pdf, size, 6 more }`
- `SnapPackCreateWithHTML object { from, insideHTML, outsideHTML, 7 more }`
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to` contact.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `firstName: string`
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `companyName: string`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `string`
- `insideHTML: string`
The HTML content for the inside of the snap pack. You can supply _either_ this or `insideTemplate` but not both.
- `outsideHTML: string`
The HTML content for the outside of the snap pack. You can supply _either_ this or `outsideTemplate` but not both.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `sendDate: optional string`
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.
- `SnapPackCreateWithTemplate object { from, insideTemplate, outsideTemplate, 7 more }`
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to` contact.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `insideTemplate: string`
The template ID for the inside of the snap pack. You can supply _either_ this or `insideHTML` but not both.
- `outsideTemplate: string`
The template ID for the outside of the snap pack. You can supply _either_ this or `outsideHTML` but not both.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `sendDate: optional string`
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.
- `SnapPackCreateWithPdf object { from, pdf, size, 6 more }`
- `from: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
The contact information of the sender. You can pass contact information inline here just like you can for the `to` contact.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `pdf: string`
A URL or a multipart-uploaded two-page PDF (first page is the outside, second page is the inside) that matches the selected snap pack size.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
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.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `string`
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `mailingClass: optional "first_class" or "standard_class" or "express" or 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"`
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `sendDate: optional string`
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
- `id: string`
A unique ID prefixed with snap_pack_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "snap_pack"`
Always `snap_pack`.
- `"snap_pack"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `insideHTML: optional string`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `insideTemplate: optional string`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `outsideHTML: optional string`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outsideTemplate: optional string`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/snap_packs \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"from": {
"addressLine1": "addressLine1",
"countryCode": "countryCode",
"firstName": "firstName"
},
"insideHTML": "insideHTML",
"outsideHTML": "outsideHTML",
"size": "8.5x11_bifold_v",
"to": {
"addressLine1": "addressLine1",
"countryCode": "countryCode",
"firstName": "firstName"
}
}'
```
#### 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
**get** `/print-mail/v1/snap_packs`
Get a list of snap packs.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of object { id, createdAt, from, 22 more }`
- `id: string`
A unique ID prefixed with snap_pack_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "snap_pack"`
Always `snap_pack`.
- `"snap_pack"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `insideHTML: optional string`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `insideTemplate: optional string`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `outsideHTML: optional string`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outsideTemplate: optional string`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/snap_packs \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/snap_packs/capabilities`
Provides sizes and mailing classes available for the destination.
### Query Parameters
- `returnCountryCode: string`
The country code where mail may be returned to.
- `destinationCountryCode: optional string`
The country code of where the snap pack will be sent to.
One of `mailingList` or `destinationCountryCode` must be supplied but
not both.
- `mailingList: optional string`
Sources destination countries from the provided mailing list.
One of `mailingList` or `destinationCountryCode` must be supplied but
not both.
### Returns
- `mailingClasses: array of "first_class" or "standard_class" or "express" or 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: array of "8.5x11_bifold_v"`
- `"8.5x11_bifold_v"`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/snap_packs/capabilities \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"sizes": [
"8.5x11_bifold_v"
],
"mailingClasses": [
"express",
"usps_express_2_day"
]
}
```
## Get Snap Pack
**get** `/print-mail/v1/snap_packs/{id}`
Retrieve a snap pack by ID.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with snap_pack_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "snap_pack"`
Always `snap_pack`.
- `"snap_pack"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `insideHTML: optional string`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `insideTemplate: optional string`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `outsideHTML: optional string`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outsideTemplate: optional string`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/snap_packs/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with snap_pack_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "snap_pack"`
Always `snap_pack`.
- `"snap_pack"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `insideHTML: optional string`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `insideTemplate: optional string`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `outsideHTML: optional string`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outsideTemplate: optional string`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/snap_packs/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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`.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with snap_pack_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "snap_pack"`
Always `snap_pack`.
- `"snap_pack"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `insideHTML: optional string`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `insideTemplate: optional string`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `outsideHTML: optional string`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outsideTemplate: optional string`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/snap_packs/$ID/progressions \
-X POST \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
- `SnapPackCreateResponse object { id, createdAt, from, 22 more }`
- `id: string`
A unique ID prefixed with snap_pack_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "snap_pack"`
Always `snap_pack`.
- `"snap_pack"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `insideHTML: optional string`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `insideTemplate: optional string`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `outsideHTML: optional string`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outsideTemplate: optional string`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Snap Pack List Response
- `SnapPackListResponse object { id, createdAt, from, 22 more }`
- `id: string`
A unique ID prefixed with snap_pack_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "snap_pack"`
Always `snap_pack`.
- `"snap_pack"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `insideHTML: optional string`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `insideTemplate: optional string`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `outsideHTML: optional string`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outsideTemplate: optional string`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Snap Pack Retrieve Capabilities Response
- `SnapPackRetrieveCapabilitiesResponse object { mailingClasses, sizes }`
- `mailingClasses: array of "first_class" or "standard_class" or "express" or 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: array of "8.5x11_bifold_v"`
- `"8.5x11_bifold_v"`
### Snap Pack Retrieve Response
- `SnapPackRetrieveResponse object { id, createdAt, from, 22 more }`
- `id: string`
A unique ID prefixed with snap_pack_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "snap_pack"`
Always `snap_pack`.
- `"snap_pack"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `insideHTML: optional string`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `insideTemplate: optional string`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `outsideHTML: optional string`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outsideTemplate: optional string`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Snap Pack Delete Response
- `SnapPackDeleteResponse object { id, createdAt, from, 22 more }`
- `id: string`
A unique ID prefixed with snap_pack_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "snap_pack"`
Always `snap_pack`.
- `"snap_pack"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `insideHTML: optional string`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `insideTemplate: optional string`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `outsideHTML: optional string`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outsideTemplate: optional string`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
### Snap Pack Progressions Response
- `SnapPackProgressionsResponse object { id, createdAt, from, 22 more }`
- `id: string`
A unique ID prefixed with snap_pack_
- `createdAt: string`
The UTC time at which this resource was created.
- `from: Contact`
The contact information of the sender.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `mailingClass: "first_class" or "standard_class" or "express" or 23 more`
The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.
- `"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: "snap_pack"`
Always `snap_pack`.
- `"snap_pack"`
- `sendDate: string`
This order will transition from `ready` to `printing` on the day after this date. For example, if this is a date on Tuesday, the order will transition to `printing` on Wednesday at midnight eastern time.
- `size: "8.5x11_bifold_v"`
Enum representing the supported snap pack sizes.
- `"8.5x11_bifold_v"`
- `status: "ready" or "printing" or "processed_for_delivery" or 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.
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `cancellation: optional object { reason, cancelledByUser, note }`
The cancellation details of this order. Populated if the order has been cancelled.
- `reason: "user_initiated" or "invalid_content" or "invalid_order_mailing_class"`
The reason for the cancellation.
- `"user_initiated"`
- `"invalid_content"`
- `"invalid_order_mailing_class"`
- `cancelledByUser: optional string`
The user ID who cancelled the order.
- `note: optional string`
An optional note provided by the user who cancelled the order.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `imbDate: optional string`
The last date that the IMB status was updated. See `imbStatus` for more details.
- `imbStatus: optional "entered_mail_stream" or "out_for_delivery" or "returned_to_sender"`
The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.
- `"entered_mail_stream"`
- `"out_for_delivery"`
- `"returned_to_sender"`
- `imbZIPCode: optional string`
The most recent ZIP code of the USPS facility that the order has been processed through. Only populated when an `imbStatus` is present.
- `insideHTML: optional string`
The HTML content for the inside of the snap pack, when provided instead of a template or PDF.
- `insideTemplate: optional string`
The template ID for the inside of the snap pack, when provided instead of HTML or PDF.
- `mergeVariables: optional map[unknown]`
These will be merged with the variables in the template or HTML you create this order with. The keys in this object should match the variable names in the template _exactly_ as they are case-sensitive. Note that these _do not_ apply to PDFs uploaded with the order.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `outsideHTML: optional string`
The HTML content for the outside of the snap pack, when provided instead of a template or PDF.
- `outsideTemplate: optional string`
The template ID for the outside of the snap pack, when provided instead of HTML or PDF.
- `trackingNumber: optional string`
The tracking number of this order. Populated after an express/certified order has been processed for delivery.
- `uploadedPDF: optional string`
A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.
- `url: optional string`
PostGrid renders a PDF preview for all orders. This should be inspected to ensure that the order is correct before it is sent out because it shows what will be printed and mailed to the recipient. Once the PDF preview is generated, this field will be returned by all `GET` endpoints which produce this order.
This URL is a signed link to the PDF preview. It will expire after a short period of time. If you need to access this URL after it has expired, you can regenerate it by calling the `GET` endpoint again.
# Targeted List Builds
## Create Targeted List Build
**post** `/print-mail/v1/targeted_list_builds`
Create a new targeted list build. A quote will be generated
asynchronously based on the provided filters.
### Header Parameters
- `"idempotency-key": optional string`
### Body Parameters
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `limit: optional number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
### Returns
- `id: string`
A unique ID prefixed with targeted_list_build_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `organization: string`
The ID of the organization that owns this list build.
- `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `buildProgressPercent: optional number`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completedAt: optional string`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmedAt: optional string`
The UTC time at which the build was confirmed, if any.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
Any errors encountered while generating a quote or building the list.
- `message: string`
A human-readable message describing the error.
- `type: "not_enough_info_to_quote" or "insufficient_credits" or "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 number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailingList: optional string`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `previewRecords: optional array of object { formattedAddress, name }`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formattedAddress: string`
The masked, comma-joined formatted address of the contact.
- `name: string`
The masked name of the contact or business.
- `quote: optional object { count, generatedAt, pricePerContactCents }`
Details of the quote generated for a targeted list build.
- `count: number`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generatedAt: string`
The UTC time at which the quote was generated.
- `pricePerContactCents: number`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/targeted_list_builds \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
**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.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of object { id, createdAt, live, 15 more }`
- `id: string`
A unique ID prefixed with targeted_list_build_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `organization: string`
The ID of the organization that owns this list build.
- `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `buildProgressPercent: optional number`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completedAt: optional string`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmedAt: optional string`
The UTC time at which the build was confirmed, if any.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
Any errors encountered while generating a quote or building the list.
- `message: string`
A human-readable message describing the error.
- `type: "not_enough_info_to_quote" or "insufficient_credits" or "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 number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailingList: optional string`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `previewRecords: optional array of object { formattedAddress, name }`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formattedAddress: string`
The masked, comma-joined formatted address of the contact.
- `name: string`
The masked name of the contact or business.
- `quote: optional object { count, generatedAt, pricePerContactCents }`
Details of the quote generated for a targeted list build.
- `count: number`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generatedAt: string`
The UTC time at which the quote was generated.
- `pricePerContactCents: number`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/targeted_list_builds \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/targeted_list_builds/{id}`
Retrieve a specific targeted list build by its ID.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with targeted_list_build_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `organization: string`
The ID of the organization that owns this list build.
- `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `buildProgressPercent: optional number`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completedAt: optional string`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmedAt: optional string`
The UTC time at which the build was confirmed, if any.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
Any errors encountered while generating a quote or building the list.
- `message: string`
A human-readable message describing the error.
- `type: "not_enough_info_to_quote" or "insufficient_credits" or "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 number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailingList: optional string`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `previewRecords: optional array of object { formattedAddress, name }`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formattedAddress: string`
The masked, comma-joined formatted address of the contact.
- `name: string`
The masked name of the contact or business.
- `quote: optional object { count, generatedAt, pricePerContactCents }`
Details of the quote generated for a targeted list build.
- `count: number`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generatedAt: string`
The UTC time at which the quote was generated.
- `pricePerContactCents: number`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/targeted_list_builds/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Body Parameters
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `limit: optional number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
### Returns
- `id: string`
A unique ID prefixed with targeted_list_build_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `organization: string`
The ID of the organization that owns this list build.
- `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `buildProgressPercent: optional number`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completedAt: optional string`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmedAt: optional string`
The UTC time at which the build was confirmed, if any.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
Any errors encountered while generating a quote or building the list.
- `message: string`
A human-readable message describing the error.
- `type: "not_enough_info_to_quote" or "insufficient_credits" or "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 number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailingList: optional string`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `previewRecords: optional array of object { formattedAddress, name }`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formattedAddress: string`
The masked, comma-joined formatted address of the contact.
- `name: string`
The masked name of the contact or business.
- `quote: optional object { count, generatedAt, pricePerContactCents }`
Details of the quote generated for a targeted list build.
- `count: number`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generatedAt: string`
The UTC time at which the quote was generated.
- `pricePerContactCents: number`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/targeted_list_builds/$ID \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
**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.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with targeted_list_build_
- `deleted: true`
- `true`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/targeted_list_builds/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "targeted_list_build_123",
"deleted": true
}
```
## Confirm Targeted List Build
**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.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with targeted_list_build_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `organization: string`
The ID of the organization that owns this list build.
- `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `buildProgressPercent: optional number`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completedAt: optional string`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmedAt: optional string`
The UTC time at which the build was confirmed, if any.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
Any errors encountered while generating a quote or building the list.
- `message: string`
A human-readable message describing the error.
- `type: "not_enough_info_to_quote" or "insufficient_credits" or "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 number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailingList: optional string`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `previewRecords: optional array of object { formattedAddress, name }`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formattedAddress: string`
The masked, comma-joined formatted address of the contact.
- `name: string`
The masked name of the contact or business.
- `quote: optional object { count, generatedAt, pricePerContactCents }`
Details of the quote generated for a targeted list build.
- `count: number`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generatedAt: string`
The UTC time at which the quote was generated.
- `pricePerContactCents: number`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/targeted_list_builds/$ID/confirm \
-X POST \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
- `TargetedListBuildCreateResponse object { id, createdAt, live, 15 more }`
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: string`
A unique ID prefixed with targeted_list_build_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `organization: string`
The ID of the organization that owns this list build.
- `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `buildProgressPercent: optional number`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completedAt: optional string`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmedAt: optional string`
The UTC time at which the build was confirmed, if any.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
Any errors encountered while generating a quote or building the list.
- `message: string`
A human-readable message describing the error.
- `type: "not_enough_info_to_quote" or "insufficient_credits" or "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 number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailingList: optional string`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `previewRecords: optional array of object { formattedAddress, name }`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formattedAddress: string`
The masked, comma-joined formatted address of the contact.
- `name: string`
The masked name of the contact or business.
- `quote: optional object { count, generatedAt, pricePerContactCents }`
Details of the quote generated for a targeted list build.
- `count: number`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generatedAt: string`
The UTC time at which the quote was generated.
- `pricePerContactCents: number`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
### Targeted List Build List Response
- `TargetedListBuildListResponse object { id, createdAt, live, 15 more }`
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: string`
A unique ID prefixed with targeted_list_build_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `organization: string`
The ID of the organization that owns this list build.
- `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `buildProgressPercent: optional number`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completedAt: optional string`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmedAt: optional string`
The UTC time at which the build was confirmed, if any.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
Any errors encountered while generating a quote or building the list.
- `message: string`
A human-readable message describing the error.
- `type: "not_enough_info_to_quote" or "insufficient_credits" or "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 number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailingList: optional string`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `previewRecords: optional array of object { formattedAddress, name }`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formattedAddress: string`
The masked, comma-joined formatted address of the contact.
- `name: string`
The masked name of the contact or business.
- `quote: optional object { count, generatedAt, pricePerContactCents }`
Details of the quote generated for a targeted list build.
- `count: number`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generatedAt: string`
The UTC time at which the quote was generated.
- `pricePerContactCents: number`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
### Targeted List Build Retrieve Response
- `TargetedListBuildRetrieveResponse object { id, createdAt, live, 15 more }`
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: string`
A unique ID prefixed with targeted_list_build_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `organization: string`
The ID of the organization that owns this list build.
- `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `buildProgressPercent: optional number`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completedAt: optional string`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmedAt: optional string`
The UTC time at which the build was confirmed, if any.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
Any errors encountered while generating a quote or building the list.
- `message: string`
A human-readable message describing the error.
- `type: "not_enough_info_to_quote" or "insufficient_credits" or "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 number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailingList: optional string`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `previewRecords: optional array of object { formattedAddress, name }`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formattedAddress: string`
The masked, comma-joined formatted address of the contact.
- `name: string`
The masked name of the contact or business.
- `quote: optional object { count, generatedAt, pricePerContactCents }`
Details of the quote generated for a targeted list build.
- `count: number`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generatedAt: string`
The UTC time at which the quote was generated.
- `pricePerContactCents: number`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
### Targeted List Build Update Response
- `TargetedListBuildUpdateResponse object { id, createdAt, live, 15 more }`
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: string`
A unique ID prefixed with targeted_list_build_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `organization: string`
The ID of the organization that owns this list build.
- `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `buildProgressPercent: optional number`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completedAt: optional string`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmedAt: optional string`
The UTC time at which the build was confirmed, if any.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
Any errors encountered while generating a quote or building the list.
- `message: string`
A human-readable message describing the error.
- `type: "not_enough_info_to_quote" or "insufficient_credits" or "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 number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailingList: optional string`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `previewRecords: optional array of object { formattedAddress, name }`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formattedAddress: string`
The masked, comma-joined formatted address of the contact.
- `name: string`
The masked name of the contact or business.
- `quote: optional object { count, generatedAt, pricePerContactCents }`
Details of the quote generated for a targeted list build.
- `count: number`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generatedAt: string`
The UTC time at which the quote was generated.
- `pricePerContactCents: number`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
### Targeted List Build Delete Response
- `TargetedListBuildDeleteResponse object { id, deleted }`
- `id: string`
A unique ID prefixed with targeted_list_build_
- `deleted: true`
- `true`
### Targeted List Build Confirm Response
- `TargetedListBuildConfirmResponse object { id, createdAt, live, 15 more }`
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: string`
A unique ID prefixed with targeted_list_build_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `organization: string`
The ID of the organization that owns this list build.
- `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`
Status of a targeted list build.
- `"generating_quote"`
- `"quote_ready"`
- `"creating_list"`
- `"completed"`
- `"failed"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `buildProgressPercent: optional number`
A percentage from 0 to 100 representing how much of the build has
completed. Only populated while `status` is `creating_list`.
- `completedAt: optional string`
The UTC time at which the build finished successfully. Only present
once `status` is `completed`.
- `confirmedAt: optional string`
The UTC time at which the build was confirmed, if any.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `errors: optional array of object { message, type }`
Any errors encountered while generating a quote or building the list.
- `message: string`
A human-readable message describing the error.
- `type: "not_enough_info_to_quote" or "insufficient_credits" or "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 number`
Maximum number of contacts to include in the built mailing list. If
omitted, all matching contacts are included.
- `mailingList: optional string`
The ID of the mailing list that was built. Present once `status` is
`completed`.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `previewRecords: optional array of object { formattedAddress, name }`
A small number of masked sample records for the configured filters,
populated alongside `quote`.
- `formattedAddress: string`
The masked, comma-joined formatted address of the contact.
- `name: string`
The masked name of the contact or business.
- `quote: optional object { count, generatedAt, pricePerContactCents }`
Details of the quote generated for a targeted list build.
- `count: number`
The number of contacts that will be included in the built mailing
list. This accounts for any `limit` that was provided.
- `generatedAt: string`
The UTC time at which the quote was generated.
- `pricePerContactCents: number`
The price per contact, in cents. Multiply by `count` to get the total
cost of building the list.
- `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`
Filters used to target US companies (B2B) when building a list.
- `postalCodes: array of string`
Required list of five-digit US ZIP codes to target.
- `companyTypes: optional array of "public" or "private" or "educational" or 3 more`
Filter by ownership structure of the company.
- `"public"`
- `"private"`
- `"educational"`
- `"government"`
- `"nonprofit"`
- `"public_subsidiary"`
- `employeeCount: optional array of number`
Inclusive `[min, max]` range for the number of employees at the
company. Values must be between 1 and 1,000,000.
- `foundedYear: optional array of number`
Inclusive `[min, max]` range for the year the company was founded.
Values must be between 1600 and 2100.
- `industries: optional array of string`
Filter by free-form industry names (see the autocomplete endpoint).
- `naicsCodes: optional array of string`
Filter by six-digit
[NAICS](https://www.census.gov/naics/) industry codes.
- `tags: optional array of string`
Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).
- `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`
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.
- `ageRange: optional array of number`
Inclusive `[min, max]` age range. Values must be between 18 and 80.
- `cityStates: optional array of string`
A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.
- `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`
Filter by highest level of education completed.
- `"high_school"`
- `"college"`
- `"grad_school"`
- `"vocational_training"`
- `gender: optional "male" or "female"`
Gender filter for US consumer list builds.
- `"male"`
- `"female"`
- `homeValueRange: optional array of number`
Inclusive `[min, max]` home value range, in US dollars. Values must be
between 0 and 1,000,000.
- `incomeRange: optional array of number`
Inclusive `[min, max]` annual household income range, in US dollars.
Values must be between 0 and 200,000.
- `numChildrenRange: optional array of number`
Inclusive `[min, max]` number of children in the household. Values must
be between 0 and 8.
- `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 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"`
- `zipCodes: optional array of string`
A list of five-digit US ZIP codes to target.
- `zipCodesAround: optional object { radiusInMiles, zipCode }`
A geographic filter that selects all ZIP codes within a given radius of a
center ZIP code.
- `radiusInMiles: number`
The radius in miles around `zipCode` to include. Between 0.1 and 100.
- `zipCode: string`
The five-digit ZIP code at the center of the search circle.
# Filters
## Autocomplete Filter Values
**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.
### Body Parameters
- `field: "industry"`
A field that can be autocompleted when configuring list build filters.
- `"industry"`
- `size: optional number`
Maximum number of suggestions to return. Between 1 and 100.
Defaults to 25 if omitted.
- `text: optional string`
Optional text prefix to narrow the autocomplete suggestions.
### Returns
- `data: array of object { type, value }`
- `type: "industry"`
A field that can be autocompleted when configuring list build filters.
- `"industry"`
- `value: string`
The suggested value (e.g., an industry name).
- `object: "list"`
- `"list"`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/targeted_list_builds/filters/autocomplete \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"field": "industry"
}'
```
#### Response
```json
{
"object": "list",
"data": [
{
"value": "software",
"type": "industry"
},
{
"value": "software development",
"type": "industry"
}
]
}
```
## Domain Types
### Filter Autocomplete Response
- `FilterAutocompleteResponse object { data, object }`
The list of suggestions returned by an autocomplete query.
- `data: array of object { type, value }`
- `type: "industry"`
A field that can be autocompleted when configuring list build filters.
- `"industry"`
- `value: string`
The suggested value (e.g., an industry name).
- `object: "list"`
- `"list"`
# Template Editor Sessions
## Create Session
**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.
### Body Parameters
- `template: string`
ID of the underlying template that this edits.
- `backURL: optional string`
The URL supplied when this editor session was created.
- `styles: optional object { canvas, panelText, saveButton }`
Style overrides for the template editor session.
- `canvas: optional object { backgroundColor }`
Style overrides for the template editor canvas.
- `backgroundColor: optional string`
The canvas background color.
- `panelText: optional object { color }`
Style overrides for template editor panel text.
- `color: optional string`
The panel text color.
- `saveButton: optional object { backgroundColor, textColor }`
Style overrides for the template editor save button.
- `backgroundColor: optional string`
The save button background color.
- `textColor: optional string`
The save button text color.
- `title: optional string`
The title supplied when this editor session was created.
- `trackers: optional "all" or "none" or array of string`
Controls which Trackers are displayed in the template editor session.
- `"all" or "none"`
- `"all"`
- `"none"`
- `array of string`
### Returns
- `id: string`
A unique ID prefixed with `template_editor_session_`.
- `createdAt: string`
The UTC time at which this session was created.
- `live: boolean`
`true` if this is a live mode session else `false`.
- `object: "template_editor_session"`
Always `template_editor_session`.
- `"template_editor_session"`
- `template: string`
ID of the underlying template that this edits.
- `url: string`
A URL that can be iframed or redirected to for editing the template.
- `backURL: optional string`
The URL supplied when this editor session was created.
- `styles: optional object { canvas, panelText, saveButton }`
Style overrides for the template editor session.
- `canvas: optional object { backgroundColor }`
Style overrides for the template editor canvas.
- `backgroundColor: optional string`
The canvas background color.
- `panelText: optional object { color }`
Style overrides for template editor panel text.
- `color: optional string`
The panel text color.
- `saveButton: optional object { backgroundColor, textColor }`
Style overrides for the template editor save button.
- `backgroundColor: optional string`
The save button background color.
- `textColor: optional string`
The save button text color.
- `title: optional string`
The title supplied when this editor session was created.
- `trackers: optional "all" or "none" or array of string`
Controls which Trackers are displayed in the template editor session.
- `"all" or "none"`
- `"all"`
- `"none"`
- `array of string`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/template_editor_sessions \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"template": "template_eYxcbMKPZEZPk71ZJPA6Yz"
}'
```
#### 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
**get** `/print-mail/v1/template_editor_sessions`
Retrieve a paginated list of Template Editor Sessions.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of object { id, createdAt, live, 7 more }`
- `id: string`
A unique ID prefixed with `template_editor_session_`.
- `createdAt: string`
The UTC time at which this session was created.
- `live: boolean`
`true` if this is a live mode session else `false`.
- `object: "template_editor_session"`
Always `template_editor_session`.
- `"template_editor_session"`
- `template: string`
ID of the underlying template that this edits.
- `url: string`
A URL that can be iframed or redirected to for editing the template.
- `backURL: optional string`
The URL supplied when this editor session was created.
- `styles: optional object { canvas, panelText, saveButton }`
Style overrides for the template editor session.
- `canvas: optional object { backgroundColor }`
Style overrides for the template editor canvas.
- `backgroundColor: optional string`
The canvas background color.
- `panelText: optional object { color }`
Style overrides for template editor panel text.
- `color: optional string`
The panel text color.
- `saveButton: optional object { backgroundColor, textColor }`
Style overrides for the template editor save button.
- `backgroundColor: optional string`
The save button background color.
- `textColor: optional string`
The save button text color.
- `title: optional string`
The title supplied when this editor session was created.
- `trackers: optional "all" or "none" or array of string`
Controls which Trackers are displayed in the template editor session.
- `"all" or "none"`
- `"all"`
- `"none"`
- `array of string`
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/template_editor_sessions \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**delete** `/print-mail/v1/template_editor_sessions/{id}`
Delete a Template Editor Session by ID.
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with `template_editor_session_`.
- `deleted: true`
- `true`
- `object: "template_editor_session"`
Always `template_editor_session`.
- `"template_editor_session"`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/template_editor_sessions/$ID \
-X DELETE \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"id": "template_editor_session_vmb3aXRJFzHb4oNRP2XMUZiTTBDtC91CSgQeqUrQfhSqq5P9wAGpmX5UkftueTubMN",
"object": "template_editor_session",
"deleted": true
}
```
## Domain Types
### Template Editor Session Create Response
- `TemplateEditorSessionCreateResponse object { id, createdAt, live, 7 more }`
- `id: string`
A unique ID prefixed with `template_editor_session_`.
- `createdAt: string`
The UTC time at which this session was created.
- `live: boolean`
`true` if this is a live mode session else `false`.
- `object: "template_editor_session"`
Always `template_editor_session`.
- `"template_editor_session"`
- `template: string`
ID of the underlying template that this edits.
- `url: string`
A URL that can be iframed or redirected to for editing the template.
- `backURL: optional string`
The URL supplied when this editor session was created.
- `styles: optional object { canvas, panelText, saveButton }`
Style overrides for the template editor session.
- `canvas: optional object { backgroundColor }`
Style overrides for the template editor canvas.
- `backgroundColor: optional string`
The canvas background color.
- `panelText: optional object { color }`
Style overrides for template editor panel text.
- `color: optional string`
The panel text color.
- `saveButton: optional object { backgroundColor, textColor }`
Style overrides for the template editor save button.
- `backgroundColor: optional string`
The save button background color.
- `textColor: optional string`
The save button text color.
- `title: optional string`
The title supplied when this editor session was created.
- `trackers: optional "all" or "none" or array of string`
Controls which Trackers are displayed in the template editor session.
- `"all" or "none"`
- `"all"`
- `"none"`
- `array of string`
### Template Editor Session List Response
- `TemplateEditorSessionListResponse object { id, createdAt, live, 7 more }`
- `id: string`
A unique ID prefixed with `template_editor_session_`.
- `createdAt: string`
The UTC time at which this session was created.
- `live: boolean`
`true` if this is a live mode session else `false`.
- `object: "template_editor_session"`
Always `template_editor_session`.
- `"template_editor_session"`
- `template: string`
ID of the underlying template that this edits.
- `url: string`
A URL that can be iframed or redirected to for editing the template.
- `backURL: optional string`
The URL supplied when this editor session was created.
- `styles: optional object { canvas, panelText, saveButton }`
Style overrides for the template editor session.
- `canvas: optional object { backgroundColor }`
Style overrides for the template editor canvas.
- `backgroundColor: optional string`
The canvas background color.
- `panelText: optional object { color }`
Style overrides for template editor panel text.
- `color: optional string`
The panel text color.
- `saveButton: optional object { backgroundColor, textColor }`
Style overrides for the template editor save button.
- `backgroundColor: optional string`
The save button background color.
- `textColor: optional string`
The save button text color.
- `title: optional string`
The title supplied when this editor session was created.
- `trackers: optional "all" or "none" or array of string`
Controls which Trackers are displayed in the template editor session.
- `"all" or "none"`
- `"all"`
- `"none"`
- `array of string`
### Template Editor Session Delete Response
- `TemplateEditorSessionDeleteResponse object { id, deleted, object }`
- `id: string`
A unique ID prefixed with `template_editor_session_`.
- `deleted: true`
- `true`
- `object: "template_editor_session"`
Always `template_editor_session`.
- `"template_editor_session"`
# Virtual Mailboxes
## Create Virtual Mailbox
**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.
### Body Parameters
- `countryCode: "US"`
All of the supported countries for virtual mailboxes.
- `"US"`
- `capabilities: optional object { envelopeScans, forwardMailTo }`
The capabilities the virtual mailbox should support.
- `envelopeScans: boolean`
If the virtual mailbox should support envelope scans or not.
- `forwardMailTo: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string`
A contact ID or contact object.
- `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `firstName: string`
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`
- `addressLine1: string`
The first line of the contact's address.
- `companyName: string`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `string`
### Returns
- `id: string`
A unique ID prefixed with virtual_mailbox_
- `capabilities: object { envelopeScans, forwardMailTo }`
All of the capabilities a virtual mailbox may have.
- `envelopeScans: boolean`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forwardMailTo: optional Contact`
A contact to forward any returned mail to.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `countryCode: "US"`
All of the supported countries for virtual mailboxes.
- `"US"`
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox"`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: "active" or "pending_assignment"`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{
"countryCode": "US"
}'
```
#### 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
**get** `/print-mail/v1/virtual_mailboxes`
Lists virtual mailboxes. You can use the `skip`, `limit`, and `search`
query parameters to refine the list.
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of object { id, capabilities, countryCode, 7 more }`
- `id: string`
A unique ID prefixed with virtual_mailbox_
- `capabilities: object { envelopeScans, forwardMailTo }`
All of the capabilities a virtual mailbox may have.
- `envelopeScans: boolean`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forwardMailTo: optional Contact`
A contact to forward any returned mail to.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `countryCode: "US"`
All of the supported countries for virtual mailboxes.
- `"US"`
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox"`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: "active" or "pending_assignment"`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/virtual_mailboxes/{id}`
Retrieve Virtual Mailbox
### Path Parameters
- `id: string`
### Returns
- `id: string`
A unique ID prefixed with virtual_mailbox_
- `capabilities: object { envelopeScans, forwardMailTo }`
All of the capabilities a virtual mailbox may have.
- `envelopeScans: boolean`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forwardMailTo: optional Contact`
A contact to forward any returned mail to.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `countryCode: "US"`
All of the supported countries for virtual mailboxes.
- `"US"`
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox"`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: "active" or "pending_assignment"`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes/$ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**get** `/print-mail/v1/virtual_mailboxes/{id}/address`
Retrieves the physical address of the virtual mailbox.
### Path Parameters
- `id: string`
### Returns
- `addressLine1: string`
The address line 1 of the mailbox.
- `countryCode: "US"`
All of the supported countries for virtual mailboxes.
- `"US"`
- `addressLine2: optional string`
The address line 2 of the mailbox.
- `city: optional string`
The city of the mailbox.
- `postalOrZip: optional string`
The postal or ZIP code of the mailbox.
- `provinceOrState: optional string`
The province or state of the mailbox.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes/$ID/address \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### Response
```json
{
"addressLine1": "145 Mulberry st",
"city": "New York",
"provinceOrState": "NY",
"postalOrZip": "10013",
"countryCode": "US"
}
```
## Domain Types
### Virtual Mailbox Create Response
- `VirtualMailboxCreateResponse object { id, capabilities, countryCode, 7 more }`
The virtual mailbox object.
- `id: string`
A unique ID prefixed with virtual_mailbox_
- `capabilities: object { envelopeScans, forwardMailTo }`
All of the capabilities a virtual mailbox may have.
- `envelopeScans: boolean`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forwardMailTo: optional Contact`
A contact to forward any returned mail to.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `countryCode: "US"`
All of the supported countries for virtual mailboxes.
- `"US"`
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox"`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: "active" or "pending_assignment"`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Virtual Mailbox List Response
- `VirtualMailboxListResponse object { id, capabilities, countryCode, 7 more }`
The virtual mailbox object.
- `id: string`
A unique ID prefixed with virtual_mailbox_
- `capabilities: object { envelopeScans, forwardMailTo }`
All of the capabilities a virtual mailbox may have.
- `envelopeScans: boolean`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forwardMailTo: optional Contact`
A contact to forward any returned mail to.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `countryCode: "US"`
All of the supported countries for virtual mailboxes.
- `"US"`
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox"`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: "active" or "pending_assignment"`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Virtual Mailbox Retrieve Response
- `VirtualMailboxRetrieveResponse object { id, capabilities, countryCode, 7 more }`
The virtual mailbox object.
- `id: string`
A unique ID prefixed with virtual_mailbox_
- `capabilities: object { envelopeScans, forwardMailTo }`
All of the capabilities a virtual mailbox may have.
- `envelopeScans: boolean`
Indicates if the virtual mailbox can produce scans of envelopes.
- `forwardMailTo: optional Contact`
A contact to forward any returned mail to.
- `id: string`
A unique ID prefixed with contact_
- `addressLine1: string`
The first line of the contact's address.
- `addressStatus: "verified" or "corrected" or "failed"`
One of `verified`, `corrected`, or `failed`.
- `"verified"`
- `"corrected"`
- `"failed"`
- `countryCode: string`
The ISO 3611-1 country code of the contact's address.
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "contact"`
Always `contact`.
- `"contact"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `addressErrors: optional string`
A series of human-readable errors/warnings that were raised when running the provided address through our address verification.
- `addressLine2: optional string`
Second line of the contact's address, if applicable.
- `city: optional string`
The city of the contact's address.
- `companyName: optional string`
Company name of the contact.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `email: optional string`
Email of the contact.
- `firstName: optional string`
First name of the contact.
- `forceVerifiedStatus: optional boolean`
If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
- `jobTitle: optional string`
Job title of the contact.
- `lastName: optional string`
Last name of the contact.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `phoneNumber: optional string`
Phone number of the contact.
- `postalOrZip: optional string`
The postal or ZIP code of the contact's address.
- `provinceOrState: optional string`
Province or state of the contact's address.
- `skipVerification: optional boolean`
If `true`, PostGrid will skip running this contact's address through our address verification system.
- `countryCode: "US"`
All of the supported countries for virtual mailboxes.
- `"US"`
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox"`
Always "virtual_mailbox".
- `"virtual_mailbox"`
- `status: "active" or "pending_assignment"`
The possible statuses of virtual mailboxes.
- `"active"`
- `"pending_assignment"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Virtual Mailbox Retrieve Address Response
- `VirtualMailboxRetrieveAddressResponse object { addressLine1, countryCode, addressLine2, 3 more }`
The address information for a mailbox.
- `addressLine1: string`
The address line 1 of the mailbox.
- `countryCode: "US"`
All of the supported countries for virtual mailboxes.
- `"US"`
- `addressLine2: optional string`
The address line 2 of the mailbox.
- `city: optional string`
The city of the mailbox.
- `postalOrZip: optional string`
The postal or ZIP code of the mailbox.
- `provinceOrState: optional string`
The province or state of the mailbox.
# Items
## List Virtual Mailbox Items
**get** `/print-mail/v1/virtual_mailboxes/{id}/items`
Lists items for a virtual mailbox.
### Path Parameters
- `id: string`
### Query Parameters
- `limit: optional number`
- `search: optional string`
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 number`
### Returns
- `data: array of object { id, createdAt, live, 7 more }`
- `id: string`
A unique ID prefixed with virtual_mailbox_item_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox_item"`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `virtualMailbox: string`
The ID of the virtual mailbox associated with this item.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `fileURL: optional string`
A URL of the envelope scan PDF.
- `matchedLetter: optional string`
The ID of the letter this item was matched to.
- `metadata: optional map[unknown]`
See the section on Metadata.
- `limit: number`
- `object: "list"`
- `"list"`
- `skip: number`
- `totalCount: number`
### Example
```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes/$ID/items \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
**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.
### Path Parameters
- `id: string`
### Body Parameters
- `description: optional string`
The description of the item.
- `matchedLetter: optional string`
The ID of a letter to match this test item to.
- `metadata: optional map[unknown]`
The metadata of the item.
### Returns
- `id: string`
A unique ID prefixed with virtual_mailbox_item_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox_item"`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `virtualMailbox: string`
The ID of the virtual mailbox associated with this item.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `fileURL: optional string`
A URL of the envelope scan PDF.
- `matchedLetter: optional string`
The ID of the letter this item was matched to.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes/$ID/items \
-H 'Content-Type: application/json' \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
-d '{}'
```
#### 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
**get** `/print-mail/v1/virtual_mailboxes/{id}/items/{itemID}`
Retrieves a single item for a virtual mailbox.
### Path Parameters
- `id: string`
- `itemID: string`
### Returns
- `id: string`
A unique ID prefixed with virtual_mailbox_item_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox_item"`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `virtualMailbox: string`
The ID of the virtual mailbox associated with this item.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `fileURL: optional string`
A URL of the envelope scan PDF.
- `matchedLetter: optional string`
The ID of the letter this item was matched to.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Example
```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes/$ID/items/$ITEM_ID \
-H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```
#### 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
- `ItemListResponse object { id, createdAt, live, 7 more }`
The virtual mailbox item object.
- `id: string`
A unique ID prefixed with virtual_mailbox_item_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox_item"`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `virtualMailbox: string`
The ID of the virtual mailbox associated with this item.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `fileURL: optional string`
A URL of the envelope scan PDF.
- `matchedLetter: optional string`
The ID of the letter this item was matched to.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Item Create Response
- `ItemCreateResponse object { id, createdAt, live, 7 more }`
The virtual mailbox item object.
- `id: string`
A unique ID prefixed with virtual_mailbox_item_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox_item"`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `virtualMailbox: string`
The ID of the virtual mailbox associated with this item.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `fileURL: optional string`
A URL of the envelope scan PDF.
- `matchedLetter: optional string`
The ID of the letter this item was matched to.
- `metadata: optional map[unknown]`
See the section on Metadata.
### Item Retrieve Response
- `ItemRetrieveResponse object { id, createdAt, live, 7 more }`
The virtual mailbox item object.
- `id: string`
A unique ID prefixed with virtual_mailbox_item_
- `createdAt: string`
The UTC time at which this resource was created.
- `live: boolean`
`true` if this is a live mode resource else `false`.
- `object: "virtual_mailbox_item"`
Always "virtual_mailbox_item".
- `"virtual_mailbox_item"`
- `updatedAt: string`
The UTC time at which this resource was last updated.
- `virtualMailbox: string`
The ID of the virtual mailbox associated with this item.
- `description: optional string`
An optional string describing this resource. Will be visible in the API and the dashboard.
- `fileURL: optional string`
A URL of the envelope scan PDF.
- `matchedLetter: optional string`
The ID of the letter this item was matched to.
- `metadata: optional map[unknown]`
See the section on Metadata.