# Print Mail

# Contacts

## Create Contact

`client.printMail.contacts.create(ContactCreateParamsbody, RequestOptionsoptions?): Contact`

**post** `/print-mail/v1/contacts`

Creates a contact. This will also verify the contact's address **if you create it using a live API key**. To sucessfully create a contact, either a `firstName`, a `companyName`, or both are required. You can supply both, but you **cannot** supply neither.

You have the option to supply the entire address (except for `countryCode`) via `addressLine1`, in which case PostGrid will parse it automatically. However, this is **not guaranteed to be correct**, so we recommend passing along the structured address fields (`city`, `provinceOrState`, etc) if you have them.

_Note that if you create a contact that has identical information to another contact, this will simply update the description of the existing contact and return it. This avoids creating duplicate contacts._

### Parameters

- `ContactCreateParams = ContactCreateWithFirstName | ContactCreateWithCompanyName`

  - `ContactCreateParamsBase`

    - `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?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: boolean`

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

  - `ContactCreateWithFirstName extends ContactCreateParamsBase`

  - `ContactCreateWithCompanyName extends ContactCreateParamsBase`

### Returns

- `Contact`

  - `id: string`

    A unique ID prefixed with contact_

  - `addressLine1: string`

    The first line of the contact's address.

  - `addressStatus: "verified" | "corrected" | "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?: string`

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

  - `addressLine2?: string`

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

  - `city?: string`

    The city of the contact's address.

  - `companyName?: string`

    Company name of the contact.

  - `description?: string`

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

  - `email?: string`

    Email of the contact.

  - `firstName?: string`

    First name of the contact.

  - `forceVerifiedStatus?: boolean`

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

  - `jobTitle?: string`

    Job title of the contact.

  - `lastName?: string`

    Last name of the contact.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `phoneNumber?: string`

    Phone number of the contact.

  - `postalOrZip?: string`

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

  - `provinceOrState?: string`

    Province or state of the contact's address.

  - `secret?: boolean`

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

  - `skipVerification?: boolean`

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

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const contact = await client.printMail.contacts.create({
  addressLine1: '90 Canal St Suite 600, Boston MA 90210',
  countryCode: 'US',
  firstName: 'Kevin',
  companyName: 'PostGrid',
});

console.log(contact.id);
```

#### Response

```json
{
  "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
  "object": "contact",
  "live": false,
  "companyName": "PostGrid",
  "addressLine1": "90 CANAL ST STE 600",
  "city": "BOSTON",
  "provinceOrState": "MA",
  "postalOrZip": "90210-1234",
  "countryCode": "US",
  "skipVerification": false,
  "forceVerifiedStatus": false,
  "addressStatus": "verified",
  "createdAt": "2022-02-16T15:08:41.052Z",
  "updatedAt": "2022-02-16T15:08:41.052Z"
}
```

## List Contacts

`client.printMail.contacts.list(ContactListParamsquery?, RequestOptionsoptions?): SkipLimit<Contact>`

**get** `/print-mail/v1/contacts`

Get a list of contacts.

### Parameters

- `query: ContactListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `Contact`

  - `id: string`

    A unique ID prefixed with contact_

  - `addressLine1: string`

    The first line of the contact's address.

  - `addressStatus: "verified" | "corrected" | "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?: string`

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

  - `addressLine2?: string`

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

  - `city?: string`

    The city of the contact's address.

  - `companyName?: string`

    Company name of the contact.

  - `description?: string`

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

  - `email?: string`

    Email of the contact.

  - `firstName?: string`

    First name of the contact.

  - `forceVerifiedStatus?: boolean`

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

  - `jobTitle?: string`

    Job title of the contact.

  - `lastName?: string`

    Last name of the contact.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `phoneNumber?: string`

    Phone number of the contact.

  - `postalOrZip?: string`

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

  - `provinceOrState?: string`

    Province or state of the contact's address.

  - `secret?: boolean`

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

  - `skipVerification?: boolean`

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

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const contact of client.printMail.contacts.list()) {
  console.log(contact.id);
}
```

#### Response

```json
{
  "skip": 0,
  "limit": 10,
  "totalCount": 1,
  "object": "list",
  "data": [
    {
      "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
      "object": "contact",
      "live": false,
      "companyName": "PostGrid",
      "addressLine1": "90 CANAL ST STE 600",
      "city": "BOSTON",
      "provinceOrState": "MA",
      "postalOrZip": "90210-1234",
      "countryCode": "US",
      "skipVerification": false,
      "forceVerifiedStatus": false,
      "addressStatus": "verified",
      "createdAt": "2022-02-16T15:08:41.052Z",
      "updatedAt": "2022-02-16T15:08:41.052Z"
    }
  ]
}
```

## Get Contact

`client.printMail.contacts.retrieve(stringid, RequestOptionsoptions?): Contact`

**get** `/print-mail/v1/contacts/{id}`

Retrieve a contact.

### Parameters

- `id: string`

### Returns

- `Contact`

  - `id: string`

    A unique ID prefixed with contact_

  - `addressLine1: string`

    The first line of the contact's address.

  - `addressStatus: "verified" | "corrected" | "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?: string`

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

  - `addressLine2?: string`

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

  - `city?: string`

    The city of the contact's address.

  - `companyName?: string`

    Company name of the contact.

  - `description?: string`

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

  - `email?: string`

    Email of the contact.

  - `firstName?: string`

    First name of the contact.

  - `forceVerifiedStatus?: boolean`

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

  - `jobTitle?: string`

    Job title of the contact.

  - `lastName?: string`

    Last name of the contact.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `phoneNumber?: string`

    Phone number of the contact.

  - `postalOrZip?: string`

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

  - `provinceOrState?: string`

    Province or state of the contact's address.

  - `secret?: boolean`

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

  - `skipVerification?: boolean`

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

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const contact = await client.printMail.contacts.retrieve('id');

console.log(contact.id);
```

#### Response

```json
{
  "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
  "object": "contact",
  "live": false,
  "companyName": "PostGrid",
  "addressLine1": "90 CANAL ST STE 600",
  "city": "BOSTON",
  "provinceOrState": "MA",
  "postalOrZip": "90210-1234",
  "countryCode": "US",
  "skipVerification": false,
  "forceVerifiedStatus": false,
  "addressStatus": "verified",
  "createdAt": "2022-02-16T15:08:41.052Z",
  "updatedAt": "2022-02-16T15:08:41.052Z"
}
```

## Delete Contact

`client.printMail.contacts.delete(stringid, RequestOptionsoptions?): ContactDeleteResponse`

**delete** `/print-mail/v1/contacts/{id}`

Delete a contact. Note that this will not affect orders that were sent to this contact.

### Parameters

- `id: string`

### Returns

- `ContactDeleteResponse`

  - `id: string`

    A unique ID prefixed with contact_

  - `deleted: true`

    - `true`

  - `object: "contact"`

    Always `contact`.

    - `"contact"`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const contact = await client.printMail.contacts.delete('id');

console.log(contact.id);
```

#### Response

```json
{
  "id": "contact_sqF12lZ1VlBb",
  "deleted": true,
  "object": "contact"
}
```

## Domain Types

### Contact

- `Contact`

  - `id: string`

    A unique ID prefixed with contact_

  - `addressLine1: string`

    The first line of the contact's address.

  - `addressStatus: "verified" | "corrected" | "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?: string`

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

  - `addressLine2?: string`

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

  - `city?: string`

    The city of the contact's address.

  - `companyName?: string`

    Company name of the contact.

  - `description?: string`

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

  - `email?: string`

    Email of the contact.

  - `firstName?: string`

    First name of the contact.

  - `forceVerifiedStatus?: boolean`

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

  - `jobTitle?: string`

    Job title of the contact.

  - `lastName?: string`

    Last name of the contact.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `phoneNumber?: string`

    Phone number of the contact.

  - `postalOrZip?: string`

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

  - `provinceOrState?: string`

    Province or state of the contact's address.

  - `secret?: boolean`

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

  - `skipVerification?: boolean`

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

### Contact Create

- `ContactCreate = ContactCreateWithFirstName | ContactCreateWithCompanyName`

  - `ContactCreateWithFirstName`

    - `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?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: boolean`

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

  - `ContactCreateWithCompanyName`

    - `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?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: boolean`

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

### Contact Create With Company Name

- `ContactCreateWithCompanyName`

  - `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?: string`

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

  - `city?: string`

    The city of the contact's address.

  - `description?: string`

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

  - `email?: string`

    Email of the contact.

  - `firstName?: string`

    First name of the contact.

  - `forceVerifiedStatus?: boolean`

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

  - `jobTitle?: string`

    Job title of the contact.

  - `lastName?: string`

    Last name of the contact.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `phoneNumber?: string`

    Phone number of the contact.

  - `postalOrZip?: string`

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

  - `provinceOrState?: string`

    Province or state of the contact's address.

  - `secret?: boolean`

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

  - `skipVerification?: boolean`

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

### Contact Create With First Name

- `ContactCreateWithFirstName`

  - `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?: string`

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

  - `city?: string`

    The city of the contact's address.

  - `companyName?: string`

    Company name of the contact.

  - `description?: string`

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

  - `email?: string`

    Email of the contact.

  - `forceVerifiedStatus?: boolean`

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

  - `jobTitle?: string`

    Job title of the contact.

  - `lastName?: string`

    Last name of the contact.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `phoneNumber?: string`

    Phone number of the contact.

  - `postalOrZip?: string`

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

  - `provinceOrState?: string`

    Province or state of the contact's address.

  - `secret?: boolean`

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

  - `skipVerification?: boolean`

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

### Contact Delete Response

- `ContactDeleteResponse`

  - `id: string`

    A unique ID prefixed with contact_

  - `deleted: true`

    - `true`

  - `object: "contact"`

    Always `contact`.

    - `"contact"`

# Templates

## Create Template

`client.printMail.templates.create(TemplateCreateParamsbody, RequestOptionsoptions?): Template`

**post** `/print-mail/v1/templates`

Create a template. Note that if you want to create a template that works with our template editor, you must use our dashboard.

### Parameters

- `body: TemplateCreateParams`

  - `description?: string`

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

  - `html?: string`

    The HTML content of this template.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Returns

- `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?: string`

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

  - `html?: string`

    The HTML content of this template.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const template = await client.printMail.templates.create({
  description: 'Test',
  html: '<b>Hello</b> {{to.firstName}}',
});

console.log(template.id);
```

#### Response

```json
{
  "id": "template_tBnVEzz878mXLbHQaz86j8",
  "object": "template",
  "live": false,
  "description": "Test",
  "html": "<b>Hello</b> {{to.firstName}}!",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z"
}
```

## List Templates

`client.printMail.templates.list(TemplateListParamsquery?, RequestOptionsoptions?): SkipLimit<Template>`

**get** `/print-mail/v1/templates`

Get a list of templates.

### Parameters

- `query: TemplateListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `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?: string`

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

  - `html?: string`

    The HTML content of this template.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const template of client.printMail.templates.list()) {
  console.log(template.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "template_tBnVEzz878mXLbHQaz86j8",
      "object": "template",
      "live": false,
      "description": "Test",
      "html": "<b>Hello</b> {{to.firstName}}!",
      "createdAt": "2020-11-12T23:23:47.974Z",
      "updatedAt": "2020-11-12T23:23:47.974Z"
    }
  ]
}
```

## Get Template

`client.printMail.templates.retrieve(stringid, RequestOptionsoptions?): Template`

**get** `/print-mail/v1/templates/{id}`

Retrieve a template by ID.

### Parameters

- `id: string`

### Returns

- `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?: string`

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

  - `html?: string`

    The HTML content of this template.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const template = await client.printMail.templates.retrieve('id');

console.log(template.id);
```

#### Response

```json
{
  "id": "template_tBnVEzz878mXLbHQaz86j8",
  "object": "template",
  "live": false,
  "description": "Test",
  "html": "<b>Hello</b> {{to.firstName}}!",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z"
}
```

## Update Template

`client.printMail.templates.update(stringid, TemplateUpdateParamsbody, RequestOptionsoptions?): Template`

**post** `/print-mail/v1/templates/{id}`

Update a template by ID.

### Parameters

- `id: string`

- `body: TemplateUpdateParams`

  - `description?: string`

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

  - `html?: string`

    The HTML content of this template.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Returns

- `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?: string`

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

  - `html?: string`

    The HTML content of this template.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const template = await client.printMail.templates.update('id', {
  description: 'Test',
  html: '<b>Hello</b> {{to.firstName}}!',
});

console.log(template.id);
```

#### Response

```json
{
  "id": "template_tBnVEzz878mXLbHQaz86j8",
  "object": "template",
  "live": false,
  "description": "Test",
  "html": "<b>Hello</b> {{to.firstName}}!",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z"
}
```

## Delete Template

`client.printMail.templates.delete(stringid, RequestOptionsoptions?): TemplateDeleteResponse`

**delete** `/print-mail/v1/templates/{id}`

Delete a template by ID. Note that this operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `TemplateDeleteResponse`

  - `id: string`

    A unique ID prefixed with template_

  - `deleted: true`

    - `true`

  - `object: "template"`

    Always `template`.

    - `"template"`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const template = await client.printMail.templates.delete('id');

console.log(template.id);
```

#### Response

```json
{
  "id": "template_sqF12lZ1VlBb",
  "deleted": true,
  "object": "template"
}
```

## Domain Types

### Template

- `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?: string`

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

  - `html?: string`

    The HTML content of this template.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Template Delete Response

- `TemplateDeleteResponse`

  - `id: string`

    A unique ID prefixed with template_

  - `deleted: true`

    - `true`

  - `object: "template"`

    Always `template`.

    - `"template"`

# Trackers

## Create Tracker

`client.printMail.trackers.create(TrackerCreateParamsbody, RequestOptionsoptions?): TrackerCreateResponse`

**post** `/print-mail/v1/trackers`

Create a Tracker.

### Parameters

- `body: TrackerCreateParams`

  - `redirectURLTemplate: string`

    The base template for URLs generated by this Tracker.

  - `urlExpireAfterDays: 30 | 60 | 90 | 2 more`

    The number of days generated Tracker URLs remain valid.

    - `30`

    - `60`

    - `90`

    - `180`

    - `365`

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Returns

- `TrackerCreateResponse`

  - `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 | 60 | 90 | 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?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const tracker = await client.printMail.trackers.create({
  redirectURLTemplate: 'https://postgrid.com?name={{to.firstName}}',
  urlExpireAfterDays: 30,
});

console.log(tracker.id);
```

#### Response

```json
{
  "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
  "object": "tracker",
  "live": false,
  "redirectURLTemplate": "https://postgrid.com?name={{to.firstName}}",
  "urlExpireAfterDays": 30,
  "visitCount": 0,
  "uniqueVisitCount": 0,
  "createdAt": "2020-11-12T23:30:12.581Z",
  "updatedAt": "2020-11-12T23:30:12.581Z"
}
```

## List Trackers

`client.printMail.trackers.list(TrackerListParamsquery?, RequestOptionsoptions?): SkipLimit<TrackerListResponse>`

**get** `/print-mail/v1/trackers`

Retrieve a paginated list of Trackers.

### Parameters

- `query: TrackerListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `TrackerListResponse`

  - `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 | 60 | 90 | 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?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const trackerListResponse of client.printMail.trackers.list()) {
  console.log(trackerListResponse.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
      "object": "tracker",
      "live": false,
      "redirectURLTemplate": "https://postgrid.com?firstName={{to.firstName}}",
      "urlExpireAfterDays": 90,
      "visitCount": 0,
      "uniqueVisitCount": 0,
      "createdAt": "2020-11-12T23:30:12.581Z",
      "updatedAt": "2020-11-12T23:31:12.581Z"
    }
  ]
}
```

## Update Tracker

`client.printMail.trackers.update(stringid, TrackerUpdateParamsbody, RequestOptionsoptions?): TrackerUpdateResponse`

**post** `/print-mail/v1/trackers/{id}`

Update a Tracker by ID.

### Parameters

- `id: string`

- `body: TrackerUpdateParams`

  - `redirectURLTemplate: string`

    The base template for URLs generated by this Tracker.

  - `urlExpireAfterDays: 30 | 60 | 90 | 2 more`

    The number of days generated Tracker URLs remain valid.

    - `30`

    - `60`

    - `90`

    - `180`

    - `365`

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Returns

- `TrackerUpdateResponse`

  - `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 | 60 | 90 | 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?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const tracker = await client.printMail.trackers.update('id', {
  redirectURLTemplate: 'https://postgrid.com?firstName={{to.firstName}}',
  urlExpireAfterDays: 90,
});

console.log(tracker.id);
```

#### Response

```json
{
  "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
  "object": "tracker",
  "live": false,
  "redirectURLTemplate": "https://postgrid.com?firstName={{to.firstName}}",
  "urlExpireAfterDays": 90,
  "visitCount": 0,
  "uniqueVisitCount": 0,
  "createdAt": "2020-11-12T23:30:12.581Z",
  "updatedAt": "2020-11-12T23:31:12.581Z"
}
```

## Get Tracker

`client.printMail.trackers.retrieve(stringid, RequestOptionsoptions?): TrackerRetrieveResponse`

**get** `/print-mail/v1/trackers/{id}`

Retrieve a Tracker by ID.

### Parameters

- `id: string`

### Returns

- `TrackerRetrieveResponse`

  - `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 | 60 | 90 | 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?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const tracker = await client.printMail.trackers.retrieve('id');

console.log(tracker.id);
```

#### Response

```json
{
  "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
  "object": "tracker",
  "live": false,
  "redirectURLTemplate": "https://postgrid.com?firstName={{to.firstName}}",
  "urlExpireAfterDays": 90,
  "visitCount": 0,
  "uniqueVisitCount": 0,
  "createdAt": "2020-11-12T23:30:12.581Z",
  "updatedAt": "2020-11-12T23:31:12.581Z"
}
```

## Delete Tracker

`client.printMail.trackers.delete(stringid, RequestOptionsoptions?): TrackerDeleteResponse`

**delete** `/print-mail/v1/trackers/{id}`

Delete a Tracker by ID. Note that this operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `TrackerDeleteResponse`

  - `id: string`

    A unique ID prefixed with tracker_

  - `deleted: true`

    - `true`

  - `object: "tracker"`

    Always `tracker`.

    - `"tracker"`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const tracker = await client.printMail.trackers.delete('id');

console.log(tracker.id);
```

#### Response

```json
{
  "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
  "object": "tracker",
  "deleted": true
}
```

## List Tracker Visits

`client.printMail.trackers.retrieveVisits(stringid, TrackerRetrieveVisitsParamsquery?, RequestOptionsoptions?): SkipLimit<TrackerRetrieveVisitsResponse>`

**get** `/print-mail/v1/trackers/{id}/visits`

Retrieve a paginated list of visits for a Tracker.

### Parameters

- `id: string`

- `query: TrackerRetrieveVisitsParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `TrackerRetrieveVisitsResponse`

  - `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.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const trackerRetrieveVisitsResponse of client.printMail.trackers.retrieveVisits('id')) {
  console.log(trackerRetrieveVisitsResponse.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "tracker_visit_123456789abcdefghijklmnopqrstuvwxyz",
      "object": "tracker_visit",
      "live": false,
      "tracker": "tracker_123456789abcdefghijklmnopqrstuvwxyz",
      "orderID": "order_123456789abcdefghijklmnopqrstuvwxyz",
      "device": "Device Unknown",
      "ipAddress": "Unknown IP Address",
      "createdAt": "2020-11-12T23:30:12.581Z",
      "updatedAt": "2020-11-12T23:31:12.581Z"
    }
  ]
}
```

## Domain Types

### Tracker Create Response

- `TrackerCreateResponse`

  - `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 | 60 | 90 | 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?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Tracker List Response

- `TrackerListResponse`

  - `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 | 60 | 90 | 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?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Tracker Update Response

- `TrackerUpdateResponse`

  - `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 | 60 | 90 | 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?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Tracker Retrieve Response

- `TrackerRetrieveResponse`

  - `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 | 60 | 90 | 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?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Tracker Delete Response

- `TrackerDeleteResponse`

  - `id: string`

    A unique ID prefixed with tracker_

  - `deleted: true`

    - `true`

  - `object: "tracker"`

    Always `tracker`.

    - `"tracker"`

### Tracker Retrieve Visits Response

- `TrackerRetrieveVisitsResponse`

  - `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.

# Webhooks

## Create Webhook

`client.printMail.webhooks.create(WebhookCreateParamsbody, RequestOptionsoptions?): Webhook`

**post** `/print-mail/v1/webhooks`

Create a Webhook.

### Parameters

- `body: WebhookCreateParams`

  - `enabledEvents: Array<"letter.created" | "letter.updated" | "postcard.created" | 18 more>`

    The list of event types this webhook listens for.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `url: string`

    An HTTPS URL that PostGrid can invoke for webhook deliveries.

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `payloadFormat?: "jwt" | "json"`

    The format in which a Webhook's event payload is delivered.

    - `"jwt"`

    - `"json"`

  - `secret?: string`

    A webhook signing secret with at least 20 non-whitespace characters.

### Returns

- `Webhook`

  - `id: string`

    A unique ID prefixed with webhook_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `enabled: boolean`

    Whether this webhook is enabled. Disabled webhooks are not triggered.

  - `enabledEvents: Array<"letter.created" | "letter.updated" | "postcard.created" | 18 more>`

    The list of event types this webhook listens for.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "webhook"`

    Always `webhook`.

    - `"webhook"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `url: string`

    An HTTPS URL that PostGrid can invoke for webhook deliveries.

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `payloadFormat?: "jwt" | "json"`

    The format in which a Webhook's event payload is delivered.

    - `"jwt"`

    - `"json"`

  - `secret?: string`

    A webhook signing secret with at least 20 non-whitespace characters.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const webhook = await client.printMail.webhooks.create({
  enabledEvents: ['letter.created'],
  url: 'https://example.com/postgrid-webhook',
  description: 'Letter Created',
});

console.log(webhook.id);
```

#### Response

```json
{
  "id": "webhook_skN2ZTvFwS62oc5tJY1gzw",
  "object": "webhook",
  "live": false,
  "description": "Letter Created",
  "url": "https://example.com/postgrid-webhook",
  "enabledEvents": [
    "letter.created"
  ],
  "payloadFormat": "jwt",
  "enabled": true,
  "secret": "webhook_secret_xkNXtQ4jHevFdkTG3mSf1Q",
  "createdAt": "2022-02-16T18:37:02.048Z",
  "updatedAt": "2022-02-16T18:37:02.048Z"
}
```

## List Webhooks

`client.printMail.webhooks.list(WebhookListParamsquery?, RequestOptionsoptions?): SkipLimit<Webhook>`

**get** `/print-mail/v1/webhooks`

Retrieve a paginated list of Webhooks.

### Parameters

- `query: WebhookListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `Webhook`

  - `id: string`

    A unique ID prefixed with webhook_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `enabled: boolean`

    Whether this webhook is enabled. Disabled webhooks are not triggered.

  - `enabledEvents: Array<"letter.created" | "letter.updated" | "postcard.created" | 18 more>`

    The list of event types this webhook listens for.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "webhook"`

    Always `webhook`.

    - `"webhook"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `url: string`

    An HTTPS URL that PostGrid can invoke for webhook deliveries.

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `payloadFormat?: "jwt" | "json"`

    The format in which a Webhook's event payload is delivered.

    - `"jwt"`

    - `"json"`

  - `secret?: string`

    A webhook signing secret with at least 20 non-whitespace characters.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const webhook of client.printMail.webhooks.list()) {
  console.log(webhook.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "webhook_skN2ZTvFwS62oc5tJY1gzw",
      "object": "webhook",
      "live": false,
      "description": "Letter Created",
      "url": "https://example.com/postgrid-webhook",
      "enabledEvents": [
        "letter.created"
      ],
      "payloadFormat": "jwt",
      "enabled": true,
      "secret": "webhook_secret_xkNXtQ4jHevFdkTG3mSf1Q",
      "createdAt": "2022-02-16T18:37:02.048Z",
      "updatedAt": "2022-02-16T18:37:02.048Z"
    }
  ]
}
```

## Update Webhook

`client.printMail.webhooks.update(stringid, WebhookUpdateParamsbody, RequestOptionsoptions?): Webhook`

**post** `/print-mail/v1/webhooks/{id}`

Update a Webhook by ID.

### Parameters

- `id: string`

- `body: WebhookUpdateParams`

  - `description?: string`

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

  - `enabled?: boolean`

    Whether this webhook is enabled. Disabled webhooks are not triggered.

  - `enabledEvents?: Array<"letter.created" | "letter.updated" | "postcard.created" | 18 more>`

    The list of event types this webhook listens for.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `payloadFormat?: "jwt" | "json"`

    The format in which a Webhook's event payload is delivered.

    - `"jwt"`

    - `"json"`

  - `secret?: string`

    A webhook signing secret with at least 20 non-whitespace characters.

  - `url?: string`

    An HTTPS URL that PostGrid can invoke for webhook deliveries.

### Returns

- `Webhook`

  - `id: string`

    A unique ID prefixed with webhook_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `enabled: boolean`

    Whether this webhook is enabled. Disabled webhooks are not triggered.

  - `enabledEvents: Array<"letter.created" | "letter.updated" | "postcard.created" | 18 more>`

    The list of event types this webhook listens for.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "webhook"`

    Always `webhook`.

    - `"webhook"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `url: string`

    An HTTPS URL that PostGrid can invoke for webhook deliveries.

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `payloadFormat?: "jwt" | "json"`

    The format in which a Webhook's event payload is delivered.

    - `"jwt"`

    - `"json"`

  - `secret?: string`

    A webhook signing secret with at least 20 non-whitespace characters.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const webhook = await client.printMail.webhooks.update('id', {
  description: 'Letter creates and updates',
  enabled: true,
  enabledEvents: ['letter.created', 'letter.updated'],
  url: 'https://example.com/postgrid-webhook',
});

console.log(webhook.id);
```

#### Response

```json
{
  "id": "webhook_skN2ZTvFwS62oc5tJY1gzw",
  "object": "webhook",
  "live": false,
  "description": "Letter creates and updates",
  "url": "https://example.com/postgrid-webhook",
  "enabledEvents": [
    "letter.created",
    "letter.updated"
  ],
  "payloadFormat": "jwt",
  "enabled": true,
  "secret": "webhook_secret_xkNXtQ4jHevFdkTG3mSf1Q",
  "createdAt": "2022-02-16T18:37:02.048Z",
  "updatedAt": "2022-02-16T18:37:14.021Z"
}
```

## Get Webhook

`client.printMail.webhooks.retrieve(stringid, RequestOptionsoptions?): Webhook`

**get** `/print-mail/v1/webhooks/{id}`

Retrieve a Webhook by ID.

### Parameters

- `id: string`

### Returns

- `Webhook`

  - `id: string`

    A unique ID prefixed with webhook_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `enabled: boolean`

    Whether this webhook is enabled. Disabled webhooks are not triggered.

  - `enabledEvents: Array<"letter.created" | "letter.updated" | "postcard.created" | 18 more>`

    The list of event types this webhook listens for.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "webhook"`

    Always `webhook`.

    - `"webhook"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `url: string`

    An HTTPS URL that PostGrid can invoke for webhook deliveries.

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `payloadFormat?: "jwt" | "json"`

    The format in which a Webhook's event payload is delivered.

    - `"jwt"`

    - `"json"`

  - `secret?: string`

    A webhook signing secret with at least 20 non-whitespace characters.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const webhook = await client.printMail.webhooks.retrieve('id');

console.log(webhook.id);
```

#### Response

```json
{
  "id": "webhook_skN2ZTvFwS62oc5tJY1gzw",
  "object": "webhook",
  "live": false,
  "description": "Letter Created",
  "url": "https://example.com/postgrid-webhook",
  "enabledEvents": [
    "letter.created"
  ],
  "payloadFormat": "jwt",
  "enabled": true,
  "secret": "webhook_secret_xkNXtQ4jHevFdkTG3mSf1Q",
  "createdAt": "2022-02-16T18:37:02.048Z",
  "updatedAt": "2022-02-16T18:37:02.048Z"
}
```

## Delete Webhook

`client.printMail.webhooks.delete(stringid, RequestOptionsoptions?): WebhookDeleteResponse`

**delete** `/print-mail/v1/webhooks/{id}`

Delete a Webhook by ID. Note that this operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `WebhookDeleteResponse`

  - `id: string`

    A unique ID prefixed with webhook_

  - `deleted: true`

    - `true`

  - `object: "webhook"`

    Always `webhook`.

    - `"webhook"`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const webhook = await client.printMail.webhooks.delete('id');

console.log(webhook.id);
```

#### Response

```json
{
  "id": "webhook_skN2ZTvFwS62oc5tJY1gzw",
  "object": "webhook",
  "deleted": true
}
```

## List Webhook Invocations

`client.printMail.webhooks.listInvocations(stringid, WebhookListInvocationsParamsquery?, RequestOptionsoptions?): SkipLimit<WebhookInvocation>`

**get** `/print-mail/v1/webhooks/{id}/invocations`

Retrieve a paginated list of invocations for a Webhook.

### Parameters

- `id: string`

- `query: WebhookListInvocationsParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `WebhookInvocation`

  - `id: string`

    A unique ID prefixed with `webhook_invocation_`.

  - `createdAt: string`

    The UTC time at which this invocation was created.

  - `event: string`

    The ID of the event that was delivered in this invocation.

  - `object: "webhook_invocation"`

    Always `webhook_invocation`.

    - `"webhook_invocation"`

  - `statusCode: number`

    The HTTP status code returned by your endpoint for this invocation.

  - `type: "letter.created" | "letter.updated" | "postcard.created" | 18 more`

    The type of event that a Webhook can listen for and that an Event represents.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `updatedAt: string`

    The UTC time at which this invocation was last updated.

  - `webhook: string`

    The ID of the webhook that was invoked.

  - `orderID?: string`

    The ID of the order associated with this invocation, if the event was order-related.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const webhookInvocation of client.printMail.webhooks.listInvocations('id')) {
  console.log(webhookInvocation.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "webhook_invocation_6TAGtJezjUyGFnznTRdX37",
      "object": "webhook_invocation",
      "webhook": "webhook_skN2ZTvFwS62oc5tJY1gzw",
      "event": "event_r1nfP4xAacyqMYtt7PeyFD",
      "orderID": "letter_rqfnwvzq5TUsYR2r6L9V8X",
      "type": "letter.created",
      "statusCode": 200,
      "createdAt": "2021-04-02T02:09:32.066Z",
      "updatedAt": "2021-04-02T02:09:32.066Z"
    }
  ]
}
```

## Domain Types

### Webhook

- `Webhook`

  - `id: string`

    A unique ID prefixed with webhook_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `enabled: boolean`

    Whether this webhook is enabled. Disabled webhooks are not triggered.

  - `enabledEvents: Array<"letter.created" | "letter.updated" | "postcard.created" | 18 more>`

    The list of event types this webhook listens for.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "webhook"`

    Always `webhook`.

    - `"webhook"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `url: string`

    An HTTPS URL that PostGrid can invoke for webhook deliveries.

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `payloadFormat?: "jwt" | "json"`

    The format in which a Webhook's event payload is delivered.

    - `"jwt"`

    - `"json"`

  - `secret?: string`

    A webhook signing secret with at least 20 non-whitespace characters.

### Webhook Invocation

- `WebhookInvocation`

  - `id: string`

    A unique ID prefixed with `webhook_invocation_`.

  - `createdAt: string`

    The UTC time at which this invocation was created.

  - `event: string`

    The ID of the event that was delivered in this invocation.

  - `object: "webhook_invocation"`

    Always `webhook_invocation`.

    - `"webhook_invocation"`

  - `statusCode: number`

    The HTTP status code returned by your endpoint for this invocation.

  - `type: "letter.created" | "letter.updated" | "postcard.created" | 18 more`

    The type of event that a Webhook can listen for and that an Event represents.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `updatedAt: string`

    The UTC time at which this invocation was last updated.

  - `webhook: string`

    The ID of the webhook that was invoked.

  - `orderID?: string`

    The ID of the order associated with this invocation, if the event was order-related.

### Webhook Delete Response

- `WebhookDeleteResponse`

  - `id: string`

    A unique ID prefixed with webhook_

  - `deleted: true`

    - `true`

  - `object: "webhook"`

    Always `webhook`.

    - `"webhook"`

# Events

## List Events

`client.printMail.events.list(EventListParamsquery?, RequestOptionsoptions?): SkipLimit<Event>`

**get** `/print-mail/v1/events`

Retrieve a paginated list of Events.

### Parameters

- `query: EventListParams`

  - `limit?: number`

  - `skip?: number`

  - `type?: Array<"letter.created" | "letter.updated" | "postcard.created" | 18 more>`

    An optional list of event types to filter the results by.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

### Returns

- `Event`

  - `id: string`

    A unique ID prefixed with `event_`.

  - `createdAt: string`

    The UTC time at which this event was created.

  - `live: boolean`

    `true` if this is a live mode event else `false`.

  - `object: "event"`

    Always `event`.

    - `"event"`

  - `type: "letter.created" | "letter.updated" | "postcard.created" | 18 more`

    The type of event that a Webhook can listen for and that an Event represents.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `data?: Record<string, unknown>`

    The data of the resource associated with this event.

  - `updatedFields?: Record<string, unknown>`

    A record containing the updated fields of the resource associated with this event.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const event of client.printMail.events.list()) {
  console.log(event.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "event_r1nfP4xAacyqMYtt7PeyFD",
      "object": "event",
      "live": false,
      "type": "letter.created",
      "data": {
        "id": "letter_rqfnwvzq5TUsYR2r6L9V8X",
        "object": "letter",
        "live": false,
        "description": "letter test 2"
      },
      "createdAt": "2021-04-02T02:06:55.086Z"
    }
  ]
}
```

## Domain Types

### Event

- `Event`

  - `id: string`

    A unique ID prefixed with `event_`.

  - `createdAt: string`

    The UTC time at which this event was created.

  - `live: boolean`

    `true` if this is a live mode event else `false`.

  - `object: "event"`

    Always `event`.

    - `"event"`

  - `type: "letter.created" | "letter.updated" | "postcard.created" | 18 more`

    The type of event that a Webhook can listen for and that an Event represents.

    - `"letter.created"`

    - `"letter.updated"`

    - `"postcard.created"`

    - `"postcard.updated"`

    - `"self_mailer.created"`

    - `"self_mailer.updated"`

    - `"cheque.created"`

    - `"cheque.updated"`

    - `"box.created"`

    - `"box.updated"`

    - `"snap_pack.created"`

    - `"snap_pack.updated"`

    - `"return_envelope_order.created"`

    - `"return_envelope_order.updated"`

    - `"tracker.visited"`

    - `"campaign.created"`

    - `"campaign.updated"`

    - `"virtual_mailbox_item.created"`

    - `"postal_statement.created"`

    - `"document.created"`

    - `"document.updated"`

  - `data?: Record<string, unknown>`

    The data of the resource associated with this event.

  - `updatedFields?: Record<string, unknown>`

    A record containing the updated fields of the resource associated with this event.

# Letters

## Create Letter Create Letter

`client.printMail.letters.create(LetterCreateParamsparams, RequestOptionsoptions?): LetterCreateResponse`

**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 for a PDF for the letter Create a letter via a multipart/form-data request. Accepts the same
  fields as the JSON create body (nested objects are bracket-encoded form
  fields, e.g. `to[firstName]`); use this content type to upload the PDF
  file directly.

### Parameters

- `LetterCreateParams = LetterCreateWithHTML | LetterCreateWithTemplate | LetterCreateWithPdf`

  - `LetterCreateParamsBase`

    - `from: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

      Body param: The contact information of the sender. You can pass contact information inline here just like you can for the `to`.

      - `ContactCreateWithFirstName`

        - `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?: string`

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

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

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

        - `email?: string`

          Email of the contact.

        - `forceVerifiedStatus?: boolean`

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

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

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

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

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

        - `skipVerification?: boolean`

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

      - `ContactCreateWithCompanyName`

        - `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?: string`

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

        - `city?: string`

          The city of the contact's address.

        - `description?: string`

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

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

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

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

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

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

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

        - `skipVerification?: boolean`

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

      - `string`

    - `html: string`

      Body param: The HTML content for the letter. You can supply _either_ this or `template` but not both.

    - `to: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

      Body param: 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`

      - `ContactCreateWithCompanyName`

      - `string`

    - `addressPlacement?: AddressPlacement`

      Body param: Enum representing the placement of the address on the letter.

      - `"top_first_page"`

      - `"insert_blank_page"`

    - `attachedPDF?: AttachedPdf`

      Body param: Model representing an attached PDF.

      - `file: string | Uploadable`

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

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `color?: boolean`

      Body param: Indicates if the letter is in color.

    - `description?: string`

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

    - `doubleSided?: boolean`

      Body param: Indicates if the letter is double-sided.

    - `envelope?: string`

      Body param: The envelope (ID) for the letter. You can either specify a custom envelope ID or use the default `standard` envelope.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Body param: 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?: Record<string, unknown>`

      Body param: 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?: Record<string, unknown>`

      Body param: See the section on Metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (string & {})`

      Body param: 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`.

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `perforatedPage?: 1`

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

      - `1`

    - `plasticCard?: PlasticCard`

      Body param: Model representing a plastic card.

      - `size: "standard"`

        Enum representing the size of the plastic card.

        - `"standard"`

      - `doubleSided?: DoubleSided`

        Model representing a double-sided plastic card.

        - `backHTML?: string`

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

        - `backTemplate?: string`

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

        - `frontHTML?: string`

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

        - `frontTemplate?: string`

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

        - `pdf?: string | Uploadable`

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

          - `string`

          - `Uploadable`

      - `singleSided?: SingleSided`

        Model representing a single-sided plastic card.

        - `html?: string`

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

        - `pdf?: string | Uploadable`

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

          - `string`

          - `Uploadable`

        - `template?: string`

          The template ID for the single-sided plastic card.

    - `returnEnvelope?: string`

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

    - `sendDate?: string`

      Body param: 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?: LetterSize`

      Body param: Enum representing the supported letter sizes.

      - `"us_letter"`

      - `"a4"`

    - `idempotencyKey?: string`

      Header param

  - `LetterCreateWithHTML extends LetterCreateParamsBase`

  - `LetterCreateWithTemplate extends LetterCreateParamsBase`

  - `LetterCreateWithPdf extends LetterCreateParamsBase`

### Returns

- `LetterCreateResponse = Letter | Letter`

  - `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" | "corrected" | "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?: string`

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

      - `addressLine2?: string`

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

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

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

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

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

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

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

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

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

      - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

      - `"ready"`

      - `"printing"`

      - `"processed_for_delivery"`

      - `"completed"`

      - `"cancelled"`

    - `to: Contact`

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

    - `updatedAt: string`

      The UTC time at which this resource was last updated.

    - `attachedPDF?: AttachedPdf`

      Model representing an attached PDF.

      - `file: string | Uploadable`

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

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `cancellation?: Cancellation`

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

      - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

        The reason for the cancellation.

        - `"user_initiated"`

        - `"invalid_content"`

        - `"invalid_order_mailing_class"`

      - `cancelledByUser?: string`

        The user ID who cancelled the order.

      - `note?: string`

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

    - `description?: string`

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

    - `html?: string`

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

    - `imbDate?: string`

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

    - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

      - `"entered_mail_stream"`

      - `"out_for_delivery"`

      - `"returned_to_sender"`

    - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

      See the section on Metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (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`.

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `pdfWorkflowRun?: string`

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

    - `perforatedPage?: 1`

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

      - `1`

    - `plasticCard?: PlasticCard`

      Model representing a plastic card.

      - `size: "standard"`

        Enum representing the size of the plastic card.

        - `"standard"`

      - `doubleSided?: DoubleSided`

        Model representing a double-sided plastic card.

        - `backHTML?: string`

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

        - `backTemplate?: string`

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

        - `frontHTML?: string`

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

        - `frontTemplate?: string`

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

        - `pdf?: string | Uploadable`

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

          - `string`

          - `Uploadable`

      - `singleSided?: SingleSided`

        Model representing a single-sided plastic card.

        - `html?: string`

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

        - `pdf?: string | Uploadable`

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

          - `string`

          - `Uploadable`

        - `template?: string`

          The template ID for the single-sided plastic card.

    - `returnEnvelope?: string`

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

    - `template?: string`

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

    - `trackingNumber?: string`

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

    - `uploadedPDF?: string`

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

    - `url?: 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`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const letter = await client.printMail.letters.create({
  from: 'contact_123',
  html: '<html>Content</html>',
  to: 'contact_123',
  paper: 'standard',
});

console.log(letter);
```

#### Response

```json
{
  "id": "letter_sqF12lZ1VlBb",
  "addressPlacement": "top_first_page",
  "color": true,
  "createdAt": "2019-12-27T18:11:19.117Z",
  "doubleSided": true,
  "envelope": "envelope",
  "from": {
    "id": "contact_sqF12lZ1VlBb",
    "addressLine1": "addressLine1",
    "addressStatus": "verified",
    "countryCode": "countryCode",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "live": true,
    "object": "contact",
    "updatedAt": "2019-12-27T18:11:19.117Z",
    "addressErrors": "addressErrors",
    "addressLine2": "addressLine2",
    "city": "city",
    "companyName": "companyName",
    "description": "description",
    "email": "email",
    "firstName": "firstName",
    "forceVerifiedStatus": true,
    "jobTitle": "jobTitle",
    "lastName": "lastName",
    "metadata": {
      "foo": "bar"
    },
    "phoneNumber": "phoneNumber",
    "postalOrZip": "postalOrZip",
    "provinceOrState": "provinceOrState",
    "secret": true,
    "skipVerification": true
  },
  "live": true,
  "mailingClass": "first_class",
  "object": "letter",
  "sendDate": "2019-12-27T18:11:19.117Z",
  "size": "us_letter",
  "status": "ready",
  "to": {
    "id": "contact_sqF12lZ1VlBb",
    "addressLine1": "addressLine1",
    "addressStatus": "verified",
    "countryCode": "countryCode",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "live": true,
    "object": "contact",
    "updatedAt": "2019-12-27T18:11:19.117Z",
    "addressErrors": "addressErrors",
    "addressLine2": "addressLine2",
    "city": "city",
    "companyName": "companyName",
    "description": "description",
    "email": "email",
    "firstName": "firstName",
    "forceVerifiedStatus": true,
    "jobTitle": "jobTitle",
    "lastName": "lastName",
    "metadata": {
      "foo": "bar"
    },
    "phoneNumber": "phoneNumber",
    "postalOrZip": "postalOrZip",
    "provinceOrState": "provinceOrState",
    "secret": true,
    "skipVerification": true
  },
  "updatedAt": "2019-12-27T18:11:19.117Z",
  "attachedPDF": {
    "file": "https://example.com",
    "placement": "before_template"
  },
  "cancellation": {
    "reason": "user_initiated",
    "cancelledByUser": "cancelledByUser",
    "note": "note"
  },
  "description": "description",
  "html": "html",
  "imbDate": "2019-12-27T18:11:19.117Z",
  "imbStatus": "entered_mail_stream",
  "imbZIPCode": "imbZIPCode",
  "mergeVariables": {
    "foo": "bar"
  },
  "metadata": {
    "foo": "bar"
  },
  "paper": "standard",
  "pdfWorkflowRun": "pdfWorkflowRun",
  "perforatedPage": 1,
  "plasticCard": {
    "size": "standard",
    "doubleSided": {
      "backHTML": "backHTML",
      "backTemplate": "backTemplate",
      "frontHTML": "frontHTML",
      "frontTemplate": "frontTemplate",
      "pdf": "https://example.com"
    },
    "singleSided": {
      "html": "html",
      "pdf": "https://example.com",
      "template": "template"
    }
  },
  "returnEnvelope": "returnEnvelope",
  "template": "template",
  "trackingNumber": "trackingNumber",
  "uploadedPDF": "https://example.com",
  "url": "https://example.com"
}
```

## List Letters

`client.printMail.letters.list(LetterListParamsquery?, RequestOptionsoptions?): SkipLimit<Letter>`

**get** `/print-mail/v1/letters`

Get a list of letters.

### Parameters

- `query: LetterListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `attachedPDF?: AttachedPdf`

    Model representing an attached PDF.

    - `file: string | Uploadable`

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

      - `string`

      - `Uploadable`

    - `placement: "before_template" | "after_template"`

      Enum representing the placement of the attached PDF.

      - `"before_template"`

      - `"after_template"`

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `html?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (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`.

    - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

      - `"standard"`

      - `"premium_paper_letter_standard_white_70lb"`

      - `"premium_paper_letter_standard_white_80lb"`

    - `(string & {})`

  - `pdfWorkflowRun?: string`

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

  - `perforatedPage?: 1`

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

    - `1`

  - `plasticCard?: PlasticCard`

    Model representing a plastic card.

    - `size: "standard"`

      Enum representing the size of the plastic card.

      - `"standard"`

    - `doubleSided?: DoubleSided`

      Model representing a double-sided plastic card.

      - `backHTML?: string`

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

      - `backTemplate?: string`

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

      - `frontHTML?: string`

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

      - `frontTemplate?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

    - `singleSided?: SingleSided`

      Model representing a single-sided plastic card.

      - `html?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

      - `template?: string`

        The template ID for the single-sided plastic card.

  - `returnEnvelope?: string`

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

  - `template?: string`

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

  - `trackingNumber?: string`

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

  - `uploadedPDF?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const letter of client.printMail.letters.list()) {
  console.log(letter.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "letter_123456",
      "object": "letter",
      "status": "ready",
      "live": false,
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "from": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "size": "us_letter",
      "doubleSided": true,
      "color": false,
      "paper": "standard",
      "sendDate": "2020-11-12T23:23:47.974Z",
      "createdAt": "2020-11-12T23:23:47.974Z",
      "updatedAt": "2020-11-12T23:23:47.974Z",
      "mailingClass": "first_class",
      "envelope": "standard",
      "addressPlacement": "top_first_page",
      "html": "<html>Content</html>"
    }
  ]
}
```

## Get Letter

`client.printMail.letters.retrieve(stringid, RequestOptionsoptions?): Letter`

**get** `/print-mail/v1/letters/{id}`

Retrieve a letter by ID.

### Parameters

- `id: string`

### Returns

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `attachedPDF?: AttachedPdf`

    Model representing an attached PDF.

    - `file: string | Uploadable`

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

      - `string`

      - `Uploadable`

    - `placement: "before_template" | "after_template"`

      Enum representing the placement of the attached PDF.

      - `"before_template"`

      - `"after_template"`

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `html?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (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`.

    - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

      - `"standard"`

      - `"premium_paper_letter_standard_white_70lb"`

      - `"premium_paper_letter_standard_white_80lb"`

    - `(string & {})`

  - `pdfWorkflowRun?: string`

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

  - `perforatedPage?: 1`

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

    - `1`

  - `plasticCard?: PlasticCard`

    Model representing a plastic card.

    - `size: "standard"`

      Enum representing the size of the plastic card.

      - `"standard"`

    - `doubleSided?: DoubleSided`

      Model representing a double-sided plastic card.

      - `backHTML?: string`

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

      - `backTemplate?: string`

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

      - `frontHTML?: string`

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

      - `frontTemplate?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

    - `singleSided?: SingleSided`

      Model representing a single-sided plastic card.

      - `html?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

      - `template?: string`

        The template ID for the single-sided plastic card.

  - `returnEnvelope?: string`

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

  - `template?: string`

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

  - `trackingNumber?: string`

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

  - `uploadedPDF?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const letter = await client.printMail.letters.retrieve('id');

console.log(letter.id);
```

#### Response

```json
{
  "id": "letter_123456",
  "object": "letter",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "us_letter",
  "doubleSided": true,
  "color": false,
  "paper": "standard",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class",
  "envelope": "standard",
  "addressPlacement": "top_first_page",
  "html": "<html>Content</html>"
}
```

## Cancel Letter

`client.printMail.letters.delete(stringid, RequestOptionsoptions?): Letter`

**delete** `/print-mail/v1/letters/{id}`

Cancel a letter by ID. Note that this operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `attachedPDF?: AttachedPdf`

    Model representing an attached PDF.

    - `file: string | Uploadable`

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

      - `string`

      - `Uploadable`

    - `placement: "before_template" | "after_template"`

      Enum representing the placement of the attached PDF.

      - `"before_template"`

      - `"after_template"`

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `html?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (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`.

    - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

      - `"standard"`

      - `"premium_paper_letter_standard_white_70lb"`

      - `"premium_paper_letter_standard_white_80lb"`

    - `(string & {})`

  - `pdfWorkflowRun?: string`

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

  - `perforatedPage?: 1`

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

    - `1`

  - `plasticCard?: PlasticCard`

    Model representing a plastic card.

    - `size: "standard"`

      Enum representing the size of the plastic card.

      - `"standard"`

    - `doubleSided?: DoubleSided`

      Model representing a double-sided plastic card.

      - `backHTML?: string`

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

      - `backTemplate?: string`

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

      - `frontHTML?: string`

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

      - `frontTemplate?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

    - `singleSided?: SingleSided`

      Model representing a single-sided plastic card.

      - `html?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

      - `template?: string`

        The template ID for the single-sided plastic card.

  - `returnEnvelope?: string`

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

  - `template?: string`

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

  - `trackingNumber?: string`

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

  - `uploadedPDF?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const letter = await client.printMail.letters.delete('id');

console.log(letter.id);
```

#### Response

```json
{
  "id": "letter_123456",
  "object": "letter",
  "status": "cancelled",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "us_letter",
  "doubleSided": true,
  "color": false,
  "paper": "standard",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class",
  "envelope": "standard",
  "addressPlacement": "top_first_page",
  "html": "<html>Content</html>"
}
```

## Get Letter Preview

`client.printMail.letters.retrieveURL(stringid, RequestOptionsoptions?): LetterRetrieveURLResponse`

**get** `/print-mail/v1/letters/{id}/url`

Retrieve a letter preview URL.

This is only available for customers with our document management addon, which offers
document generation and hosting capabilities. This endpoint has a much higher rate limit
than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases.

### Parameters

- `id: string`

### Returns

- `LetterRetrieveURLResponse`

  - `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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const response = await client.printMail.letters.retrieveURL('id');

console.log(response.id);
```

#### Response

```json
{
  "id": "letter_123456",
  "object": "letter_url",
  "url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/letter_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D"
}
```

## Cancel Letter With Note

`client.printMail.letters.cancel(stringid, LetterCancelParamsbody, RequestOptionsoptions?): Letter`

**post** `/print-mail/v1/letters/{id}/cancellation`

Cancel a letter by ID with a note. Note that this operation
cannot be undone and that only letters with a status of `ready` can be
cancelled.

### Parameters

- `id: string`

- `body: LetterCancelParams`

  - `note: string`

### Returns

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `attachedPDF?: AttachedPdf`

    Model representing an attached PDF.

    - `file: string | Uploadable`

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

      - `string`

      - `Uploadable`

    - `placement: "before_template" | "after_template"`

      Enum representing the placement of the attached PDF.

      - `"before_template"`

      - `"after_template"`

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `html?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (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`.

    - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

      - `"standard"`

      - `"premium_paper_letter_standard_white_70lb"`

      - `"premium_paper_letter_standard_white_80lb"`

    - `(string & {})`

  - `pdfWorkflowRun?: string`

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

  - `perforatedPage?: 1`

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

    - `1`

  - `plasticCard?: PlasticCard`

    Model representing a plastic card.

    - `size: "standard"`

      Enum representing the size of the plastic card.

      - `"standard"`

    - `doubleSided?: DoubleSided`

      Model representing a double-sided plastic card.

      - `backHTML?: string`

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

      - `backTemplate?: string`

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

      - `frontHTML?: string`

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

      - `frontTemplate?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

    - `singleSided?: SingleSided`

      Model representing a single-sided plastic card.

      - `html?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

      - `template?: string`

        The template ID for the single-sided plastic card.

  - `returnEnvelope?: string`

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

  - `template?: string`

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

  - `trackingNumber?: string`

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

  - `uploadedPDF?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const letter = await client.printMail.letters.cancel('id', { note: 'Cancelling this letter' });

console.log(letter.id);
```

#### Response

```json
{
  "id": "letter_123456",
  "object": "letter",
  "status": "cancelled",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "us_letter",
  "doubleSided": true,
  "color": false,
  "paper": "standard",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class",
  "envelope": "standard",
  "addressPlacement": "top_first_page",
  "html": "<html>Content</html>"
}
```

## Progress Status

`client.printMail.letters.progress(stringid, RequestOptionsoptions?): Letter`

**post** `/print-mail/v1/letters/{id}/progressions`

Progresses a letter's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.

Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.

### Parameters

- `id: string`

### Returns

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `attachedPDF?: AttachedPdf`

    Model representing an attached PDF.

    - `file: string | Uploadable`

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

      - `string`

      - `Uploadable`

    - `placement: "before_template" | "after_template"`

      Enum representing the placement of the attached PDF.

      - `"before_template"`

      - `"after_template"`

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `html?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (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`.

    - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

      - `"standard"`

      - `"premium_paper_letter_standard_white_70lb"`

      - `"premium_paper_letter_standard_white_80lb"`

    - `(string & {})`

  - `pdfWorkflowRun?: string`

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

  - `perforatedPage?: 1`

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

    - `1`

  - `plasticCard?: PlasticCard`

    Model representing a plastic card.

    - `size: "standard"`

      Enum representing the size of the plastic card.

      - `"standard"`

    - `doubleSided?: DoubleSided`

      Model representing a double-sided plastic card.

      - `backHTML?: string`

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

      - `backTemplate?: string`

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

      - `frontHTML?: string`

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

      - `frontTemplate?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

    - `singleSided?: SingleSided`

      Model representing a single-sided plastic card.

      - `html?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

      - `template?: string`

        The template ID for the single-sided plastic card.

  - `returnEnvelope?: string`

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

  - `template?: string`

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

  - `trackingNumber?: string`

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

  - `uploadedPDF?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const letter = await client.printMail.letters.progress('id');

console.log(letter.id);
```

#### Response

```json
{
  "id": "letter_123456",
  "object": "letter",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "us_letter",
  "doubleSided": true,
  "color": false,
  "paper": "standard",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class",
  "envelope": "standard",
  "addressPlacement": "top_first_page",
  "html": "<html>Content</html>"
}
```

## Domain Types

### Address Placement

- `AddressPlacement = "top_first_page" | "insert_blank_page"`

  Enum representing the placement of the address on the letter.

  - `"top_first_page"`

  - `"insert_blank_page"`

### Attached Pdf

- `AttachedPdf`

  Model representing an attached PDF.

  - `file: string | Uploadable`

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

    - `string`

    - `Uploadable`

  - `placement: "before_template" | "after_template"`

    Enum representing the placement of the attached PDF.

    - `"before_template"`

    - `"after_template"`

### Letter

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `attachedPDF?: AttachedPdf`

    Model representing an attached PDF.

    - `file: string | Uploadable`

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

      - `string`

      - `Uploadable`

    - `placement: "before_template" | "after_template"`

      Enum representing the placement of the attached PDF.

      - `"before_template"`

      - `"after_template"`

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `html?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (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`.

    - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

      - `"standard"`

      - `"premium_paper_letter_standard_white_70lb"`

      - `"premium_paper_letter_standard_white_80lb"`

    - `(string & {})`

  - `pdfWorkflowRun?: string`

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

  - `perforatedPage?: 1`

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

    - `1`

  - `plasticCard?: PlasticCard`

    Model representing a plastic card.

    - `size: "standard"`

      Enum representing the size of the plastic card.

      - `"standard"`

    - `doubleSided?: DoubleSided`

      Model representing a double-sided plastic card.

      - `backHTML?: string`

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

      - `backTemplate?: string`

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

      - `frontHTML?: string`

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

      - `frontTemplate?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

    - `singleSided?: SingleSided`

      Model representing a single-sided plastic card.

      - `html?: string`

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

      - `pdf?: string | Uploadable`

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

        - `string`

        - `Uploadable`

      - `template?: string`

        The template ID for the single-sided plastic card.

  - `returnEnvelope?: string`

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

  - `template?: string`

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

  - `trackingNumber?: string`

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

  - `uploadedPDF?: string`

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

  - `url?: 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" | "a4"`

  Enum representing the supported letter sizes.

  - `"us_letter"`

  - `"a4"`

### Plastic Card

- `PlasticCard`

  Model representing a plastic card.

  - `size: "standard"`

    Enum representing the size of the plastic card.

    - `"standard"`

  - `doubleSided?: DoubleSided`

    Model representing a double-sided plastic card.

    - `backHTML?: string`

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

    - `backTemplate?: string`

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

    - `frontHTML?: string`

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

    - `frontTemplate?: string`

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

    - `pdf?: string | Uploadable`

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

      - `string`

      - `Uploadable`

  - `singleSided?: SingleSided`

    Model representing a single-sided plastic card.

    - `html?: string`

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

    - `pdf?: string | Uploadable`

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

      - `string`

      - `Uploadable`

    - `template?: string`

      The template ID for the single-sided plastic card.

### Letter Create Response

- `LetterCreateResponse = Letter | Letter`

  - `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" | "corrected" | "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?: string`

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

      - `addressLine2?: string`

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

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

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

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

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

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

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

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

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

      - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

      - `"ready"`

      - `"printing"`

      - `"processed_for_delivery"`

      - `"completed"`

      - `"cancelled"`

    - `to: Contact`

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

    - `updatedAt: string`

      The UTC time at which this resource was last updated.

    - `attachedPDF?: AttachedPdf`

      Model representing an attached PDF.

      - `file: string | Uploadable`

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

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `cancellation?: Cancellation`

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

      - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

        The reason for the cancellation.

        - `"user_initiated"`

        - `"invalid_content"`

        - `"invalid_order_mailing_class"`

      - `cancelledByUser?: string`

        The user ID who cancelled the order.

      - `note?: string`

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

    - `description?: string`

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

    - `html?: string`

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

    - `imbDate?: string`

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

    - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

      - `"entered_mail_stream"`

      - `"out_for_delivery"`

      - `"returned_to_sender"`

    - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

      See the section on Metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (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`.

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `pdfWorkflowRun?: string`

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

    - `perforatedPage?: 1`

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

      - `1`

    - `plasticCard?: PlasticCard`

      Model representing a plastic card.

      - `size: "standard"`

        Enum representing the size of the plastic card.

        - `"standard"`

      - `doubleSided?: DoubleSided`

        Model representing a double-sided plastic card.

        - `backHTML?: string`

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

        - `backTemplate?: string`

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

        - `frontHTML?: string`

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

        - `frontTemplate?: string`

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

        - `pdf?: string | Uploadable`

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

          - `string`

          - `Uploadable`

      - `singleSided?: SingleSided`

        Model representing a single-sided plastic card.

        - `html?: string`

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

        - `pdf?: string | Uploadable`

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

          - `string`

          - `Uploadable`

        - `template?: string`

          The template ID for the single-sided plastic card.

    - `returnEnvelope?: string`

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

    - `template?: string`

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

    - `trackingNumber?: string`

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

    - `uploadedPDF?: string`

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

    - `url?: 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`

### Letter Retrieve URL Response

- `LetterRetrieveURLResponse`

  - `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 Create Postcard

`client.printMail.postcards.create(PostcardCreateParamsparams, RequestOptionsoptions?): PostcardCreateResponse`

**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 for a 2 page PDF where the first page is the front of the postcard and the second page is the back Create a postcard via a multipart/form-data request. Accepts the same
  fields as the JSON create body (nested objects are bracket-encoded form
  fields, e.g. `to[firstName]`); use this content type to upload the PDF
  file directly.

### Parameters

- `PostcardCreateParams = PostcardCreateWithHTML | PostcardCreateWithTemplate | PostcardCreateWithPdfurl | PostcardCreateWithPdfFile`

  - `PostcardCreateParamsBase`

    - `backHTML: string`

      Body param: The HTML content for the back of the postcard. You can supply _either_ this or `backTemplate` but not both.

    - `frontHTML: string`

      Body param: The HTML content for the front of the postcard. You can supply _either_ this or `frontTemplate` but not both.

    - `size: "6x4" | "9x6" | "11x6"`

      Body param: Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

    - `to: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

      Body param: 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`

        - `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?: string`

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

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

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

        - `email?: string`

          Email of the contact.

        - `forceVerifiedStatus?: boolean`

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

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

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

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

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

        - `skipVerification?: boolean`

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

      - `ContactCreateWithCompanyName`

        - `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?: string`

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

        - `city?: string`

          The city of the contact's address.

        - `description?: string`

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

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

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

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

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

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

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

        - `skipVerification?: boolean`

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

      - `string`

    - `description?: string`

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

    - `from?: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

      Body param: 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`

      - `ContactCreateWithCompanyName`

      - `string`

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Body param: 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?: Record<string, unknown>`

      Body param: 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?: Record<string, unknown>`

      Body param: See the section on Metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (string & {})`

      Body param: 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`.

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `sendDate?: string`

      Body param: 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.

    - `idempotencyKey?: string`

      Header param

  - `PostcardCreateWithHTML extends PostcardCreateParamsBase`

  - `PostcardCreateWithTemplate extends PostcardCreateParamsBase`

  - `PostcardCreateWithPdfurl extends PostcardCreateParamsBase`

  - `PostcardCreateWithPdfFile extends PostcardCreateParamsBase`

### Returns

- `PostcardCreateResponse = Postcard | Postcard`

  - `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" | "standard_class" | "express" | 23 more`

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

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `object: "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" | "9x6" | "11x6"`

      Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

    - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

      - `"ready"`

      - `"printing"`

      - `"processed_for_delivery"`

      - `"completed"`

      - `"cancelled"`

    - `to: Contact`

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

      - `id: string`

        A unique ID prefixed with contact_

      - `addressLine1: string`

        The first line of the contact's address.

      - `addressStatus: "verified" | "corrected" | "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?: string`

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

      - `addressLine2?: string`

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

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

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

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

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

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

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

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

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

      - `skipVerification?: 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?: Cancellation`

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

      - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

        The reason for the cancellation.

        - `"user_initiated"`

        - `"invalid_content"`

        - `"invalid_order_mailing_class"`

      - `cancelledByUser?: string`

        The user ID who cancelled the order.

      - `note?: string`

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

    - `description?: string`

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

    - `from?: Contact`

      The contact information of the sender.

    - `imbDate?: string`

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

    - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

      - `"entered_mail_stream"`

      - `"out_for_delivery"`

      - `"returned_to_sender"`

    - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

      See the section on Metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (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`.

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `trackingNumber?: string`

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

    - `url?: 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`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const postcard = await client.printMail.postcards.create({
  backHTML: '<html>Back</html>',
  frontHTML: '<html>Front</html>',
  size: '6x4',
  to: 'contact_456',
  from: 'contact_123',
  paper: 'standard',
});

console.log(postcard);
```

#### Response

```json
{
  "id": "postcard_sqF12lZ1VlBb",
  "createdAt": "2019-12-27T18:11:19.117Z",
  "live": true,
  "mailingClass": "first_class",
  "object": "postcard",
  "sendDate": "2019-12-27T18:11:19.117Z",
  "size": "6x4",
  "status": "ready",
  "to": {
    "id": "contact_sqF12lZ1VlBb",
    "addressLine1": "addressLine1",
    "addressStatus": "verified",
    "countryCode": "countryCode",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "live": true,
    "object": "contact",
    "updatedAt": "2019-12-27T18:11:19.117Z",
    "addressErrors": "addressErrors",
    "addressLine2": "addressLine2",
    "city": "city",
    "companyName": "companyName",
    "description": "description",
    "email": "email",
    "firstName": "firstName",
    "forceVerifiedStatus": true,
    "jobTitle": "jobTitle",
    "lastName": "lastName",
    "metadata": {
      "foo": "bar"
    },
    "phoneNumber": "phoneNumber",
    "postalOrZip": "postalOrZip",
    "provinceOrState": "provinceOrState",
    "secret": true,
    "skipVerification": true
  },
  "updatedAt": "2019-12-27T18:11:19.117Z",
  "cancellation": {
    "reason": "user_initiated",
    "cancelledByUser": "cancelledByUser",
    "note": "note"
  },
  "description": "description",
  "from": {
    "id": "contact_sqF12lZ1VlBb",
    "addressLine1": "addressLine1",
    "addressStatus": "verified",
    "countryCode": "countryCode",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "live": true,
    "object": "contact",
    "updatedAt": "2019-12-27T18:11:19.117Z",
    "addressErrors": "addressErrors",
    "addressLine2": "addressLine2",
    "city": "city",
    "companyName": "companyName",
    "description": "description",
    "email": "email",
    "firstName": "firstName",
    "forceVerifiedStatus": true,
    "jobTitle": "jobTitle",
    "lastName": "lastName",
    "metadata": {
      "foo": "bar"
    },
    "phoneNumber": "phoneNumber",
    "postalOrZip": "postalOrZip",
    "provinceOrState": "provinceOrState",
    "secret": true,
    "skipVerification": true
  },
  "imbDate": "2019-12-27T18:11:19.117Z",
  "imbStatus": "entered_mail_stream",
  "imbZIPCode": "imbZIPCode",
  "mergeVariables": {
    "foo": "bar"
  },
  "metadata": {
    "foo": "bar"
  },
  "paper": "standard",
  "trackingNumber": "trackingNumber",
  "url": "https://example.com"
}
```

## List Postcards

`client.printMail.postcards.list(PostcardListParamsquery?, RequestOptionsoptions?): SkipLimit<Postcard>`

**get** `/print-mail/v1/postcards`

Get a list of postcards.

### Parameters

- `query: PostcardListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "9x6" | "11x6"`

    Enum representing the supported postcard sizes.

    - `"6x4"`

    - `"9x6"`

    - `"11x6"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `from?: Contact`

    The contact information of the sender.

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (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`.

    - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

      - `"standard"`

      - `"premium_paper_heavy_1_glossy"`

      - `"premium_paper_postcard_uv_glossy_ss"`

      - `"premium_paper_postcard_uv_glossy_ss_120lb"`

      - `"premium_paper_postcard_satin_ds"`

    - `(string & {})`

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const postcard of client.printMail.postcards.list()) {
  console.log(postcard.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "postcard_123456",
      "object": "postcard",
      "status": "ready",
      "live": false,
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "from": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "size": "6x4",
      "sendDate": "2020-11-12T23:23:47.974Z",
      "createdAt": "2020-11-12T23:23:47.974Z",
      "updatedAt": "2020-11-12T23:23:47.974Z",
      "mailingClass": "first_class",
      "paper": "standard"
    }
  ]
}
```

## Get Postcard

`client.printMail.postcards.retrieve(stringid, RequestOptionsoptions?): Postcard`

**get** `/print-mail/v1/postcards/{id}`

Retrieve a postcard by ID.

### Parameters

- `id: string`

### Returns

- `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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "9x6" | "11x6"`

    Enum representing the supported postcard sizes.

    - `"6x4"`

    - `"9x6"`

    - `"11x6"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `from?: Contact`

    The contact information of the sender.

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (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`.

    - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

      - `"standard"`

      - `"premium_paper_heavy_1_glossy"`

      - `"premium_paper_postcard_uv_glossy_ss"`

      - `"premium_paper_postcard_uv_glossy_ss_120lb"`

      - `"premium_paper_postcard_satin_ds"`

    - `(string & {})`

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const postcard = await client.printMail.postcards.retrieve('id');

console.log(postcard.id);
```

#### Response

```json
{
  "id": "postcard_123456",
  "object": "postcard",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "6x4",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class",
  "paper": "standard"
}
```

## Cancel Postcard

`client.printMail.postcards.delete(stringid, RequestOptionsoptions?): Postcard`

**delete** `/print-mail/v1/postcards/{id}`

Cancel a postcard by ID. Note that this operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "9x6" | "11x6"`

    Enum representing the supported postcard sizes.

    - `"6x4"`

    - `"9x6"`

    - `"11x6"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `from?: Contact`

    The contact information of the sender.

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (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`.

    - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

      - `"standard"`

      - `"premium_paper_heavy_1_glossy"`

      - `"premium_paper_postcard_uv_glossy_ss"`

      - `"premium_paper_postcard_uv_glossy_ss_120lb"`

      - `"premium_paper_postcard_satin_ds"`

    - `(string & {})`

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const postcard = await client.printMail.postcards.delete('id');

console.log(postcard.id);
```

#### Response

```json
{
  "id": "postcard_123456",
  "object": "postcard",
  "status": "cancelled",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "6x4",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class",
  "paper": "standard"
}
```

## Get Postcard Preview

`client.printMail.postcards.retrieveURL(stringid, RequestOptionsoptions?): PostcardRetrieveURLResponse`

**get** `/print-mail/v1/postcards/{id}/url`

Retrieve a postcard preview URL.

This is only available for customers with our document management addon, which offers
document generation and hosting capabilities. This endpoint has a much higher rate limit
than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases.

### Parameters

- `id: string`

### Returns

- `PostcardRetrieveURLResponse`

  - `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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const response = await client.printMail.postcards.retrieveURL('id');

console.log(response.id);
```

#### Response

```json
{
  "id": "postcard_123456",
  "object": "postcard_url",
  "url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/postcard_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D"
}
```

## Cancel Postcard With Note

`client.printMail.postcards.cancel(stringid, PostcardCancelParamsbody, RequestOptionsoptions?): Postcard`

**post** `/print-mail/v1/postcards/{id}/cancellation`

Cancel a postcard by ID with a note. Note that this operation
cannot be undone and that only postcards with a status of `ready` can be
cancelled.

### Parameters

- `id: string`

- `body: PostcardCancelParams`

  - `note: string`

### Returns

- `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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "9x6" | "11x6"`

    Enum representing the supported postcard sizes.

    - `"6x4"`

    - `"9x6"`

    - `"11x6"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `from?: Contact`

    The contact information of the sender.

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (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`.

    - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

      - `"standard"`

      - `"premium_paper_heavy_1_glossy"`

      - `"premium_paper_postcard_uv_glossy_ss"`

      - `"premium_paper_postcard_uv_glossy_ss_120lb"`

      - `"premium_paper_postcard_satin_ds"`

    - `(string & {})`

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const postcard = await client.printMail.postcards.cancel('id', {
  note: 'Cancelling this postcard',
});

console.log(postcard.id);
```

#### Response

```json
{
  "id": "postcard_123456",
  "object": "postcard",
  "status": "cancelled",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "6x4",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class",
  "paper": "standard"
}
```

## Progress Status

`client.printMail.postcards.progress(stringid, RequestOptionsoptions?): Postcard`

**post** `/print-mail/v1/postcards/{id}/progressions`

Progresses a postcard's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.

Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.

### Parameters

- `id: string`

### Returns

- `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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "9x6" | "11x6"`

    Enum representing the supported postcard sizes.

    - `"6x4"`

    - `"9x6"`

    - `"11x6"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `from?: Contact`

    The contact information of the sender.

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (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`.

    - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

      - `"standard"`

      - `"premium_paper_heavy_1_glossy"`

      - `"premium_paper_postcard_uv_glossy_ss"`

      - `"premium_paper_postcard_uv_glossy_ss_120lb"`

      - `"premium_paper_postcard_satin_ds"`

    - `(string & {})`

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const postcard = await client.printMail.postcards.progress('id');

console.log(postcard.id);
```

#### Response

```json
{
  "id": "postcard_123456",
  "object": "postcard",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "6x4",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class",
  "paper": "standard"
}
```

## Domain Types

### Postcard

- `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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "9x6" | "11x6"`

    Enum representing the supported postcard sizes.

    - `"6x4"`

    - `"9x6"`

    - `"11x6"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `from?: Contact`

    The contact information of the sender.

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (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`.

    - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

      - `"standard"`

      - `"premium_paper_heavy_1_glossy"`

      - `"premium_paper_postcard_uv_glossy_ss"`

      - `"premium_paper_postcard_uv_glossy_ss_120lb"`

      - `"premium_paper_postcard_satin_ds"`

    - `(string & {})`

  - `trackingNumber?: string`

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

  - `url?: 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 Create Response

- `PostcardCreateResponse = Postcard | Postcard`

  - `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" | "standard_class" | "express" | 23 more`

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

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `object: "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" | "9x6" | "11x6"`

      Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

    - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

      - `"ready"`

      - `"printing"`

      - `"processed_for_delivery"`

      - `"completed"`

      - `"cancelled"`

    - `to: Contact`

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

      - `id: string`

        A unique ID prefixed with contact_

      - `addressLine1: string`

        The first line of the contact's address.

      - `addressStatus: "verified" | "corrected" | "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?: string`

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

      - `addressLine2?: string`

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

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

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

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

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

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

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

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

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

      - `skipVerification?: 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?: Cancellation`

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

      - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

        The reason for the cancellation.

        - `"user_initiated"`

        - `"invalid_content"`

        - `"invalid_order_mailing_class"`

      - `cancelledByUser?: string`

        The user ID who cancelled the order.

      - `note?: string`

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

    - `description?: string`

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

    - `from?: Contact`

      The contact information of the sender.

    - `imbDate?: string`

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

    - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

      - `"entered_mail_stream"`

      - `"out_for_delivery"`

      - `"returned_to_sender"`

    - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

      See the section on Metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (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`.

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `trackingNumber?: string`

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

    - `url?: 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`

### Postcard Retrieve URL Response

- `PostcardRetrieveURLResponse`

  - `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

`client.printMail.bankAccounts.create(BankAccountCreateParamsbody, RequestOptionsoptions?): BankAccount`

**post** `/print-mail/v1/bank_accounts`

Create a bank account. A US bank account is created by setting `bankCountryCode` to `US` and providing `accountNumber` and `routingNumber`. A canadian bank account can be created by specifying `bankCountryCode` as `CA` and setting `accountNumber`, `routeNumber`, and `transitNumber` accordingly.

You must specify _either_ `signatureImage` or `signatureText`. The image can be supplied as either a URL or a multipart file upload.

Note that the reasonable character limit for `signatureText` is 6 capital letters or 20 lowercase letters — anything exceeding that will likely overflow onto a new line.

### Parameters

- `BankAccountCreateParams = BankAccountCreateSignatureText | BankAccountCreateSignatureImageURL | BankAccountCreateSignatureImageFile`

  - `BankAccountCreateParamsBase`

    - `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?: string`

      The primary address line of the bank.

    - `bankSecondaryLine?: string`

      The secondary address line of the bank.

    - `caDesignationNumber?: string`

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

    - `description?: string`

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

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `routeNumber?: string`

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

    - `routingNumber?: string`

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

    - `transitNumber?: string`

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

  - `BankAccountCreateSignatureText extends BankAccountCreateParamsBase`

  - `BankAccountCreateSignatureImageURL extends BankAccountCreateParamsBase`

  - `BankAccountCreateSignatureImageFile extends BankAccountCreateParamsBase`

### Returns

- `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?: string`

    The primary address line of the bank.

  - `bankSecondaryLine?: string`

    The secondary address line of the bank.

  - `caDesignationNumber?: string`

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

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `routeNumber?: string`

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

  - `routingNumber?: string`

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

  - `signatureImage?: string`

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

  - `signatureText?: 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?: string`

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

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const bankAccount = await client.printMail.bankAccounts.create({
  accountNumber: '1234567',
  bankCountryCode: 'US',
  bankName: 'Test Bank',
  signatureText: 'Example',
  bankPrimaryLine: '145 mulberry st',
  bankSecondaryLine: 'new york ny 10013',
  routingNumber: '123456789',
});

console.log(bankAccount.id);
```

#### Response

```json
{
  "id": "bank_account_12345",
  "object": "bank_account",
  "live": false,
  "bankName": "Test Bank",
  "bankPrimaryLine": "145 mulberry st",
  "bankSecondaryLine": "new york ny 10013",
  "bankCountryCode": "US",
  "accountNumber": "1234567",
  "routingNumber": "123456789",
  "signatureText": "Signature",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z"
}
```

## List Bank Accounts

`client.printMail.bankAccounts.list(BankAccountListParamsquery?, RequestOptionsoptions?): SkipLimit<BankAccount>`

**get** `/print-mail/v1/bank_accounts`

Get a list of bank accounts.

Note that we do not return the complete account number or the signature image for security reasons.

### Parameters

- `query: BankAccountListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `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?: string`

    The primary address line of the bank.

  - `bankSecondaryLine?: string`

    The secondary address line of the bank.

  - `caDesignationNumber?: string`

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

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `routeNumber?: string`

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

  - `routingNumber?: string`

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

  - `signatureImage?: string`

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

  - `signatureText?: 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?: string`

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

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const bankAccount of client.printMail.bankAccounts.list()) {
  console.log(bankAccount.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "bank_account_12345",
      "object": "bank_account",
      "live": false,
      "bankName": "Test Bank",
      "bankPrimaryLine": "145 mulberry st",
      "bankSecondaryLine": "new york ny 10013",
      "bankCountryCode": "US",
      "accountNumber": "1234567",
      "routingNumber": "123456789",
      "signatureText": "Signature",
      "createdAt": "2020-11-12T23:23:47.974Z",
      "updatedAt": "2020-11-12T23:23:47.974Z"
    }
  ]
}
```

## Get Bank Account

`client.printMail.bankAccounts.retrieve(stringid, RequestOptionsoptions?): BankAccount`

**get** `/print-mail/v1/bank_accounts/{id}`

Retrieve a bank account by ID.

Note that we do not return the complete account number or the signature image for security reasons.

### Parameters

- `id: string`

### Returns

- `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?: string`

    The primary address line of the bank.

  - `bankSecondaryLine?: string`

    The secondary address line of the bank.

  - `caDesignationNumber?: string`

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

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `routeNumber?: string`

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

  - `routingNumber?: string`

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

  - `signatureImage?: string`

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

  - `signatureText?: 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?: string`

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

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const bankAccount = await client.printMail.bankAccounts.retrieve('id');

console.log(bankAccount.id);
```

#### Response

```json
{
  "id": "bank_account_12345",
  "object": "bank_account",
  "live": false,
  "bankName": "Test Bank",
  "bankPrimaryLine": "145 mulberry st",
  "bankSecondaryLine": "new york ny 10013",
  "bankCountryCode": "US",
  "accountNumber": "1234567",
  "routingNumber": "123456789",
  "signatureText": "Signature",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z"
}
```

## Delete Bank Account

`client.printMail.bankAccounts.delete(stringid, RequestOptionsoptions?): BankAccountDeleteResponse`

**delete** `/print-mail/v1/bank_accounts/{id}`

Delete a bank account by ID. Note that this operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `BankAccountDeleteResponse`

  - `id: string`

    A unique ID prefixed with bank_account_

  - `deleted: true`

    - `true`

  - `object: "bank_account"`

    Always `bank_account`.

    - `"bank_account"`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const bankAccount = await client.printMail.bankAccounts.delete('id');

console.log(bankAccount.id);
```

#### Response

```json
{
  "id": "bank_account_sqF12lZ1VlBb",
  "deleted": true,
  "object": "bank_account"
}
```

## Domain Types

### Bank Account

- `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?: string`

    The primary address line of the bank.

  - `bankSecondaryLine?: string`

    The secondary address line of the bank.

  - `caDesignationNumber?: string`

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

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `routeNumber?: string`

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

  - `routingNumber?: string`

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

  - `signatureImage?: string`

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

  - `signatureText?: 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?: string`

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

### Bank Account Country Code

- `BankAccountCountryCode = "CA" | "US"`

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

  - `"CA"`

  - `"US"`

### Bank Account Delete Response

- `BankAccountDeleteResponse`

  - `id: string`

    A unique ID prefixed with bank_account_

  - `deleted: true`

    - `true`

  - `object: "bank_account"`

    Always `bank_account`.

    - `"bank_account"`

# Cheques

## Create Cheque

`client.printMail.cheques.create(ChequeCreateParamsparams, RequestOptionsoptions?): 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.
Digital-only cheques are not sent out — they are created with a `cancelled` status and a
cancellation reason of `digital_only`.

Example request body:

```json
{
  "from": "contact_123",
  "bankAccount": "bank_123",
  "amount": 1000,
  "currencyCode": "USD",
  "number": 123456,
  "size": "us_letter",
  "digitalOnly": {
    "watermark": "VOID"
  }
}
```

### Parameters

- `params: ChequeCreateParams`

  - `amount: number`

    Body param: The amount of the cheque in cents.

  - `bankAccount: string`

    Body param: The bank account (ID) associated with the cheque.

  - `from: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

    Body param: The contact information of the sender. You can pass contact information inline here just like you can for the `to`.

    - `ContactCreateWithFirstName`

      - `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?: string`

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

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

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

      - `email?: string`

        Email of the contact.

      - `forceVerifiedStatus?: boolean`

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

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

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

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

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

      - `skipVerification?: boolean`

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

    - `ContactCreateWithCompanyName`

      - `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?: string`

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

      - `city?: string`

        The city of the contact's address.

      - `description?: string`

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

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

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

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

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

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

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

      - `skipVerification?: boolean`

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

    - `string`

  - `to: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

    Body param: 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`

    - `ContactCreateWithCompanyName`

    - `string`

  - `currencyCode?: "USD" | "CAD"`

    Body param: 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?: string`

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

  - `digitalOnly?: DigitalOnly`

    Body param: 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.

    - `payee?: Payee`

      The payee of the digital cheque. Supplying `payee.name` lets you create a
      digital-only cheque without a `to` contact — when it is provided, the
      top-level `to` field may be omitted.

      - `name: string`

        The name of the payee.

  - `envelope?: "standard" | (string & {})`

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

    - `"standard"`

      - `"standard"`

    - `(string & {})`

  - `letterHTML?: string`

    Body param: The raw HTML content for a letter attached to the cheque, if any. You can supply _either_ this, `letterTemplate`, or `letterPDF`, but not more than one.

  - `letterPDF?: string | Uploadable`

    Body param: A URL pointing to a PDF for the letter attached to the cheque, or the PDF file itself when uploaded via a multipart form request. You can supply _either_ this, `letterHTML`, or `letterTemplate`, but not more than one.

    - `string`

    - `Uploadable`

  - `letterSettings?: LetterSettings`

    Body param: Settings for a letter attached to a cheque.

    - `placement?: "before_cheque" | "after_cheque"`

      Enum representing where a letter attached to a cheque is placed relative to
      the cheque page.

      - `"before_cheque"`

      - `"after_cheque"`

  - `letterTemplate?: string`

    Body param: A Template ID for the letter attached to the cheque, if any.

  - `logo?: string`

    Body param: 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?: "first_class" | "standard_class" | "express" | 23 more`

    Body param: 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?: string`

    Body param: The memo of the cheque.

  - `mergeVariables?: Record<string, unknown>`

    Body param: 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?: string`

    Body param: The message of the cheque.

  - `metadata?: Record<string, unknown>`

    Body param: See the section on Metadata.

  - `number?: number`

    Body param: 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?: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

    Body param: 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`

    - `ContactCreateWithCompanyName`

    - `string`

  - `returnEnvelope?: string`

    Body param: The return envelope (ID) sent out with the cheque, if any. Note that you must first order return envelopes using the Return Envelopes API.

  - `sendDate?: string`

    Body param: 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?: ChequeSize`

    Body param: Enum representing the supported cheque sizes.

    - `"us_letter"`

    - `"us_legal"`

  - `idempotencyKey?: string`

    Header param

### Returns

- `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" | "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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `depositReadyPDFURL?: string`

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

  - `description?: string`

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

  - `digitalOnly?: 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.

    - `payee?: Payee`

      The payee of the digital cheque. Supplying `payee.name` lets you create a
      digital-only cheque without a `to` contact — when it is provided, the
      top-level `to` field may be omitted.

      - `name: string`

        The name of the payee.

  - `envelope?: "standard" | (string & {})`

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

    - `"standard"`

      - `"standard"`

    - `(string & {})`

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: string`

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

  - `letterHTML?: string`

    The raw HTML content for a letter attached to the cheque, if any. You can supply _either_ this, `letterTemplate`, or `letterPDF`, but not more than one.

  - `letterTemplate?: string`

    A Template ID for the letter attached to the cheque, if any.

  - `letterUploadedPDF?: string`

    A signed URL pointing to the original PDF of the letter attached to the cheque, if any.

  - `logo?: 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?: string`

    The memo of the cheque.

  - `mergeVariables?: Record<string, 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?: string`

    The message of the cheque.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `number?: 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.

  - `returnEnvelope?: string`

    The return envelope (ID) sent out with the cheque, if any. Note that you must first order return envelopes using the Return Envelopes API.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const cheque = await client.printMail.cheques.create({
  amount: 1000,
  bankAccount: 'bank_123',
  from: 'contact_123',
  to: 'contact_123',
  currencyCode: 'USD',
  number: 123456,
  size: 'us_letter',
});

console.log(cheque.id);
```

#### Response

```json
{
  "id": "cheque_123456",
  "object": "cheque",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "bankAccount": "bank_123",
  "amount": 1000,
  "currencyCode": "USD",
  "number": 123456,
  "size": "us_letter",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class"
}
```

## List Cheques

`client.printMail.cheques.list(ChequeListParamsquery?, RequestOptionsoptions?): SkipLimit<Cheque>`

**get** `/print-mail/v1/cheques`

Get a list of cheques.

### Parameters

- `query: ChequeListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `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" | "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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `depositReadyPDFURL?: string`

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

  - `description?: string`

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

  - `digitalOnly?: 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.

    - `payee?: Payee`

      The payee of the digital cheque. Supplying `payee.name` lets you create a
      digital-only cheque without a `to` contact — when it is provided, the
      top-level `to` field may be omitted.

      - `name: string`

        The name of the payee.

  - `envelope?: "standard" | (string & {})`

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

    - `"standard"`

      - `"standard"`

    - `(string & {})`

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: string`

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

  - `letterHTML?: string`

    The raw HTML content for a letter attached to the cheque, if any. You can supply _either_ this, `letterTemplate`, or `letterPDF`, but not more than one.

  - `letterTemplate?: string`

    A Template ID for the letter attached to the cheque, if any.

  - `letterUploadedPDF?: string`

    A signed URL pointing to the original PDF of the letter attached to the cheque, if any.

  - `logo?: 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?: string`

    The memo of the cheque.

  - `mergeVariables?: Record<string, 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?: string`

    The message of the cheque.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `number?: 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.

  - `returnEnvelope?: string`

    The return envelope (ID) sent out with the cheque, if any. Note that you must first order return envelopes using the Return Envelopes API.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const cheque of client.printMail.cheques.list()) {
  console.log(cheque.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "cheque_123456",
      "object": "cheque",
      "status": "ready",
      "live": false,
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "from": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "bankAccount": "bank_123",
      "amount": 1000,
      "currencyCode": "USD",
      "number": 123456,
      "size": "us_letter",
      "sendDate": "2020-11-12T23:23:47.974Z",
      "createdAt": "2020-11-12T23:23:47.974Z",
      "updatedAt": "2020-11-12T23:23:47.974Z",
      "mailingClass": "first_class"
    }
  ]
}
```

## Get Cheque

`client.printMail.cheques.retrieve(stringid, RequestOptionsoptions?): Cheque`

**get** `/print-mail/v1/cheques/{id}`

Retrieve a cheque by ID.

### Parameters

- `id: string`

### Returns

- `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" | "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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `depositReadyPDFURL?: string`

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

  - `description?: string`

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

  - `digitalOnly?: 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.

    - `payee?: Payee`

      The payee of the digital cheque. Supplying `payee.name` lets you create a
      digital-only cheque without a `to` contact — when it is provided, the
      top-level `to` field may be omitted.

      - `name: string`

        The name of the payee.

  - `envelope?: "standard" | (string & {})`

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

    - `"standard"`

      - `"standard"`

    - `(string & {})`

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: string`

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

  - `letterHTML?: string`

    The raw HTML content for a letter attached to the cheque, if any. You can supply _either_ this, `letterTemplate`, or `letterPDF`, but not more than one.

  - `letterTemplate?: string`

    A Template ID for the letter attached to the cheque, if any.

  - `letterUploadedPDF?: string`

    A signed URL pointing to the original PDF of the letter attached to the cheque, if any.

  - `logo?: 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?: string`

    The memo of the cheque.

  - `mergeVariables?: Record<string, 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?: string`

    The message of the cheque.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `number?: 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.

  - `returnEnvelope?: string`

    The return envelope (ID) sent out with the cheque, if any. Note that you must first order return envelopes using the Return Envelopes API.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const cheque = await client.printMail.cheques.retrieve('id');

console.log(cheque.id);
```

#### Response

```json
{
  "id": "cheque_123456",
  "object": "cheque",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "bankAccount": "bank_123",
  "amount": 1000,
  "currencyCode": "USD",
  "number": 123456,
  "size": "us_letter",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class"
}
```

## Cancel Cheque

`client.printMail.cheques.delete(stringid, RequestOptionsoptions?): Cheque`

**delete** `/print-mail/v1/cheques/{id}`

Cancel a cheque by ID. Note that this operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `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" | "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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `depositReadyPDFURL?: string`

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

  - `description?: string`

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

  - `digitalOnly?: 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.

    - `payee?: Payee`

      The payee of the digital cheque. Supplying `payee.name` lets you create a
      digital-only cheque without a `to` contact — when it is provided, the
      top-level `to` field may be omitted.

      - `name: string`

        The name of the payee.

  - `envelope?: "standard" | (string & {})`

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

    - `"standard"`

      - `"standard"`

    - `(string & {})`

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: string`

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

  - `letterHTML?: string`

    The raw HTML content for a letter attached to the cheque, if any. You can supply _either_ this, `letterTemplate`, or `letterPDF`, but not more than one.

  - `letterTemplate?: string`

    A Template ID for the letter attached to the cheque, if any.

  - `letterUploadedPDF?: string`

    A signed URL pointing to the original PDF of the letter attached to the cheque, if any.

  - `logo?: 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?: string`

    The memo of the cheque.

  - `mergeVariables?: Record<string, 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?: string`

    The message of the cheque.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `number?: 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.

  - `returnEnvelope?: string`

    The return envelope (ID) sent out with the cheque, if any. Note that you must first order return envelopes using the Return Envelopes API.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const cheque = await client.printMail.cheques.delete('id');

console.log(cheque.id);
```

#### Response

```json
{
  "id": "cheque_123456",
  "object": "cheque",
  "status": "cancelled",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "bankAccount": "bank_123",
  "amount": 1000,
  "currencyCode": "USD",
  "number": 123456,
  "size": "us_letter",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class"
}
```

## Get Cheque Preview

`client.printMail.cheques.retrieveURL(stringid, RequestOptionsoptions?): ChequeRetrieveURLResponse`

**get** `/print-mail/v1/cheques/{id}/url`

Retrieve a cheque preview URL.

This is only available for customers with our document management addon, which offers
document generation and hosting capabilities. This endpoint has a much higher rate limit
than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases.

### Parameters

- `id: string`

### Returns

- `ChequeRetrieveURLResponse`

  - `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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const response = await client.printMail.cheques.retrieveURL('id');

console.log(response.id);
```

#### Response

```json
{
  "id": "cheque_123456",
  "object": "cheque_url",
  "url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/cheque_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D"
}
```

## Retrieve Cheque Deposit-Ready PDF (Digital Only)

`client.printMail.cheques.retrieveWithDepositReadyPdf(stringid, RequestOptionsoptions?): Cheque`

**get** `/print-mail/v1/cheques/{id}/with_deposit_ready_pdf`

Retrieve the deposit-ready PDF for a digital-only cheque. The endpoint can only be called by users with 'Admin' role.
In test mode, the preview PDF of the digitalOnly cheque and the deposit-ready PDF are the same.
In live mode, the deposit-ready will have the full account number.

### Parameters

- `id: string`

### Returns

- `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" | "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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `depositReadyPDFURL?: string`

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

  - `description?: string`

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

  - `digitalOnly?: 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.

    - `payee?: Payee`

      The payee of the digital cheque. Supplying `payee.name` lets you create a
      digital-only cheque without a `to` contact — when it is provided, the
      top-level `to` field may be omitted.

      - `name: string`

        The name of the payee.

  - `envelope?: "standard" | (string & {})`

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

    - `"standard"`

      - `"standard"`

    - `(string & {})`

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: string`

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

  - `letterHTML?: string`

    The raw HTML content for a letter attached to the cheque, if any. You can supply _either_ this, `letterTemplate`, or `letterPDF`, but not more than one.

  - `letterTemplate?: string`

    A Template ID for the letter attached to the cheque, if any.

  - `letterUploadedPDF?: string`

    A signed URL pointing to the original PDF of the letter attached to the cheque, if any.

  - `logo?: 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?: string`

    The memo of the cheque.

  - `mergeVariables?: Record<string, 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?: string`

    The message of the cheque.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `number?: 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.

  - `returnEnvelope?: string`

    The return envelope (ID) sent out with the cheque, if any. Note that you must first order return envelopes using the Return Envelopes API.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const cheque = await client.printMail.cheques.retrieveWithDepositReadyPdf('id');

console.log(cheque.id);
```

#### Response

```json
{
  "id": "cheque_123456",
  "object": "cheque",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "bankAccount": "bank_123",
  "amount": 1000,
  "currencyCode": "USD",
  "number": 123456,
  "size": "us_letter",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class",
  "digitalOnly": {
    "watermark": "TEST"
  },
  "depositReadyPDFURL": "https://example.s3.amazonaws.com/deposit_ready.pdf"
}
```

## Cancel Cheque With Note

`client.printMail.cheques.cancel(stringid, ChequeCancelParamsbody, RequestOptionsoptions?): Cheque`

**post** `/print-mail/v1/cheques/{id}/cancellation`

Cancel a cheque by ID with a note. Note that this operation
cannot be undone and that only cheques with a status of `ready` can be
cancelled.

### Parameters

- `id: string`

- `body: ChequeCancelParams`

  - `note: string`

### Returns

- `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" | "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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `depositReadyPDFURL?: string`

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

  - `description?: string`

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

  - `digitalOnly?: 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.

    - `payee?: Payee`

      The payee of the digital cheque. Supplying `payee.name` lets you create a
      digital-only cheque without a `to` contact — when it is provided, the
      top-level `to` field may be omitted.

      - `name: string`

        The name of the payee.

  - `envelope?: "standard" | (string & {})`

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

    - `"standard"`

      - `"standard"`

    - `(string & {})`

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: string`

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

  - `letterHTML?: string`

    The raw HTML content for a letter attached to the cheque, if any. You can supply _either_ this, `letterTemplate`, or `letterPDF`, but not more than one.

  - `letterTemplate?: string`

    A Template ID for the letter attached to the cheque, if any.

  - `letterUploadedPDF?: string`

    A signed URL pointing to the original PDF of the letter attached to the cheque, if any.

  - `logo?: 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?: string`

    The memo of the cheque.

  - `mergeVariables?: Record<string, 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?: string`

    The message of the cheque.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `number?: 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.

  - `returnEnvelope?: string`

    The return envelope (ID) sent out with the cheque, if any. Note that you must first order return envelopes using the Return Envelopes API.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const cheque = await client.printMail.cheques.cancel('id', { note: 'Cancelling this cheque' });

console.log(cheque.id);
```

#### Response

```json
{
  "id": "cheque_123456",
  "object": "cheque",
  "status": "cancelled",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "bankAccount": "bank_123",
  "amount": 1000,
  "currencyCode": "USD",
  "number": 123456,
  "size": "us_letter",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class"
}
```

## Progress Status

`client.printMail.cheques.progress(stringid, RequestOptionsoptions?): Cheque`

**post** `/print-mail/v1/cheques/{id}/progressions`

Progresses a cheque's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.

Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.

### Parameters

- `id: string`

### Returns

- `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" | "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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `depositReadyPDFURL?: string`

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

  - `description?: string`

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

  - `digitalOnly?: 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.

    - `payee?: Payee`

      The payee of the digital cheque. Supplying `payee.name` lets you create a
      digital-only cheque without a `to` contact — when it is provided, the
      top-level `to` field may be omitted.

      - `name: string`

        The name of the payee.

  - `envelope?: "standard" | (string & {})`

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

    - `"standard"`

      - `"standard"`

    - `(string & {})`

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: string`

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

  - `letterHTML?: string`

    The raw HTML content for a letter attached to the cheque, if any. You can supply _either_ this, `letterTemplate`, or `letterPDF`, but not more than one.

  - `letterTemplate?: string`

    A Template ID for the letter attached to the cheque, if any.

  - `letterUploadedPDF?: string`

    A signed URL pointing to the original PDF of the letter attached to the cheque, if any.

  - `logo?: 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?: string`

    The memo of the cheque.

  - `mergeVariables?: Record<string, 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?: string`

    The message of the cheque.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `number?: 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.

  - `returnEnvelope?: string`

    The return envelope (ID) sent out with the cheque, if any. Note that you must first order return envelopes using the Return Envelopes API.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const cheque = await client.printMail.cheques.progress('id');

console.log(cheque.id);
```

#### Response

```json
{
  "id": "cheque_123456",
  "object": "cheque",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "bankAccount": "bank_123",
  "amount": 1000,
  "currencyCode": "USD",
  "number": 123456,
  "size": "us_letter",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class"
}
```

## Domain Types

### Cheque

- `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" | "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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `depositReadyPDFURL?: string`

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

  - `description?: string`

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

  - `digitalOnly?: 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.

    - `payee?: Payee`

      The payee of the digital cheque. Supplying `payee.name` lets you create a
      digital-only cheque without a `to` contact — when it is provided, the
      top-level `to` field may be omitted.

      - `name: string`

        The name of the payee.

  - `envelope?: "standard" | (string & {})`

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

    - `"standard"`

      - `"standard"`

    - `(string & {})`

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: string`

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

  - `letterHTML?: string`

    The raw HTML content for a letter attached to the cheque, if any. You can supply _either_ this, `letterTemplate`, or `letterPDF`, but not more than one.

  - `letterTemplate?: string`

    A Template ID for the letter attached to the cheque, if any.

  - `letterUploadedPDF?: string`

    A signed URL pointing to the original PDF of the letter attached to the cheque, if any.

  - `logo?: 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?: string`

    The memo of the cheque.

  - `mergeVariables?: Record<string, 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?: string`

    The message of the cheque.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `number?: 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.

  - `returnEnvelope?: string`

    The return envelope (ID) sent out with the cheque, if any. Note that you must first order return envelopes using the Return Envelopes API.

  - `trackingNumber?: string`

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

  - `url?: 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" | "us_legal"`

  Enum representing the supported cheque sizes.

  - `"us_letter"`

  - `"us_legal"`

### Digital Only

- `DigitalOnly`

  - `watermark: string`

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

  - `payee?: Payee`

    The payee of the digital cheque. Supplying `payee.name` lets you create a
    digital-only cheque without a `to` contact — when it is provided, the
    top-level `to` field may be omitted.

    - `name: string`

      The name of the payee.

### Cheque Retrieve URL Response

- `ChequeRetrieveURLResponse`

  - `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 Create Self Mailer

`client.printMail.selfMailers.create(SelfMailerCreateParamsparams, RequestOptionsoptions?): SelfMailerCreateResponse`

**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 for a 2 page PDF where the first page is the outside of the self-mailer and the second page is the inside Create a self-mailer via a multipart/form-data request. Accepts the same
  fields as the JSON create body (nested objects are bracket-encoded form
  fields, e.g. `to[firstName]`); use this content type to upload the PDF
  file directly.

### Parameters

- `SelfMailerCreateParams = SelfMailerCreateWithHTML | SelfMailerCreateWithTemplate | SelfMailerCreateWithPdfurl | SelfMailerCreateWithPdfFile`

  - `SelfMailerCreateParamsBase`

    - `from: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

      Body param: The contact information of the sender. You can pass contact information inline here just like you can for the `to`.

      - `ContactCreateWithFirstName`

        - `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?: string`

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

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

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

        - `email?: string`

          Email of the contact.

        - `forceVerifiedStatus?: boolean`

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

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

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

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

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

        - `skipVerification?: boolean`

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

      - `ContactCreateWithCompanyName`

        - `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?: string`

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

        - `city?: string`

          The city of the contact's address.

        - `description?: string`

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

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

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

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

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

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

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

        - `skipVerification?: boolean`

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

      - `string`

    - `insideHTML: string`

      Body param: The HTML content for the inside of the self-mailer. You can supply _either_ this or `insideTemplate` but not both.

    - `outsideHTML: string`

      Body param: The HTML content for the outside of the self-mailer. You can supply _either_ this or `outsideTemplate` but not both.

    - `size: "8.5x11_bifold" | "8.5x11_trifold" | "9.5x16_trifold"`

      Body param: Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

    - `to: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

      Body param: 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`

      - `ContactCreateWithCompanyName`

      - `string`

    - `description?: string`

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

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Body param: 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?: Record<string, unknown>`

      Body param: 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?: Record<string, unknown>`

      Body param: See the section on Metadata.

    - `sendDate?: string`

      Body param: 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.

    - `idempotencyKey?: string`

      Header param

  - `SelfMailerCreateWithHTML extends SelfMailerCreateParamsBase`

  - `SelfMailerCreateWithTemplate extends SelfMailerCreateParamsBase`

  - `SelfMailerCreateWithPdfurl extends SelfMailerCreateParamsBase`

  - `SelfMailerCreateWithPdfFile extends SelfMailerCreateParamsBase`

### Returns

- `SelfMailerCreateResponse = SelfMailer | SelfMailer`

  - `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" | "corrected" | "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?: string`

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

      - `addressLine2?: string`

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

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

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

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

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

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

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

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

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

      - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `object: "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" | "8.5x11_trifold" | "9.5x16_trifold"`

      Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

    - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

      - `"ready"`

      - `"printing"`

      - `"processed_for_delivery"`

      - `"completed"`

      - `"cancelled"`

    - `to: Contact`

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

    - `updatedAt: string`

      The UTC time at which this resource was last updated.

    - `cancellation?: Cancellation`

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

      - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

        The reason for the cancellation.

        - `"user_initiated"`

        - `"invalid_content"`

        - `"invalid_order_mailing_class"`

      - `cancelledByUser?: string`

        The user ID who cancelled the order.

      - `note?: string`

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

    - `description?: string`

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

    - `imbDate?: string`

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

    - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

      - `"entered_mail_stream"`

      - `"out_for_delivery"`

      - `"returned_to_sender"`

    - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

      See the section on Metadata.

    - `trackingNumber?: string`

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

    - `url?: 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.

  - `SelfMailer`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const selfMailer = await client.printMail.selfMailers.create({
  from: 'contact_123',
  insideHTML: '<html>Inside</html>',
  outsideHTML: '<html>Outside</html>',
  size: '8.5x11_bifold',
  to: 'contact_456',
});

console.log(selfMailer);
```

#### Response

```json
{
  "id": "self_mailer_sqF12lZ1VlBb",
  "createdAt": "2019-12-27T18:11:19.117Z",
  "from": {
    "id": "contact_sqF12lZ1VlBb",
    "addressLine1": "addressLine1",
    "addressStatus": "verified",
    "countryCode": "countryCode",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "live": true,
    "object": "contact",
    "updatedAt": "2019-12-27T18:11:19.117Z",
    "addressErrors": "addressErrors",
    "addressLine2": "addressLine2",
    "city": "city",
    "companyName": "companyName",
    "description": "description",
    "email": "email",
    "firstName": "firstName",
    "forceVerifiedStatus": true,
    "jobTitle": "jobTitle",
    "lastName": "lastName",
    "metadata": {
      "foo": "bar"
    },
    "phoneNumber": "phoneNumber",
    "postalOrZip": "postalOrZip",
    "provinceOrState": "provinceOrState",
    "secret": true,
    "skipVerification": true
  },
  "live": true,
  "mailingClass": "first_class",
  "object": "self_mailer",
  "sendDate": "2019-12-27T18:11:19.117Z",
  "size": "8.5x11_bifold",
  "status": "ready",
  "to": {
    "id": "contact_sqF12lZ1VlBb",
    "addressLine1": "addressLine1",
    "addressStatus": "verified",
    "countryCode": "countryCode",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "live": true,
    "object": "contact",
    "updatedAt": "2019-12-27T18:11:19.117Z",
    "addressErrors": "addressErrors",
    "addressLine2": "addressLine2",
    "city": "city",
    "companyName": "companyName",
    "description": "description",
    "email": "email",
    "firstName": "firstName",
    "forceVerifiedStatus": true,
    "jobTitle": "jobTitle",
    "lastName": "lastName",
    "metadata": {
      "foo": "bar"
    },
    "phoneNumber": "phoneNumber",
    "postalOrZip": "postalOrZip",
    "provinceOrState": "provinceOrState",
    "secret": true,
    "skipVerification": true
  },
  "updatedAt": "2019-12-27T18:11:19.117Z",
  "cancellation": {
    "reason": "user_initiated",
    "cancelledByUser": "cancelledByUser",
    "note": "note"
  },
  "description": "description",
  "imbDate": "2019-12-27T18:11:19.117Z",
  "imbStatus": "entered_mail_stream",
  "imbZIPCode": "imbZIPCode",
  "mergeVariables": {
    "foo": "bar"
  },
  "metadata": {
    "foo": "bar"
  },
  "trackingNumber": "trackingNumber",
  "url": "https://example.com"
}
```

## List Self Mailers

`client.printMail.selfMailers.list(SelfMailerListParamsquery?, RequestOptionsoptions?): SkipLimit<SelfMailer>`

**get** `/print-mail/v1/self_mailers`

Get a list of self-mailers.

### Parameters

- `query: SelfMailerListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "8.5x11_trifold" | "9.5x16_trifold"`

    Enum representing the supported self-mailer sizes.

    - `"8.5x11_bifold"`

    - `"8.5x11_trifold"`

    - `"9.5x16_trifold"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const selfMailer of client.printMail.selfMailers.list()) {
  console.log(selfMailer.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "self_mailer_123456",
      "object": "self_mailer",
      "status": "ready",
      "live": false,
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "from": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "size": "8.5x11_bifold",
      "sendDate": "2020-11-12T23:23:47.974Z",
      "createdAt": "2020-11-12T23:23:47.974Z",
      "updatedAt": "2020-11-12T23:23:47.974Z",
      "mailingClass": "first_class"
    }
  ]
}
```

## Get Self Mailer

`client.printMail.selfMailers.retrieve(stringid, RequestOptionsoptions?): SelfMailer`

**get** `/print-mail/v1/self_mailers/{id}`

Retrieve a self-mailer by ID.

### Parameters

- `id: string`

### Returns

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "8.5x11_trifold" | "9.5x16_trifold"`

    Enum representing the supported self-mailer sizes.

    - `"8.5x11_bifold"`

    - `"8.5x11_trifold"`

    - `"9.5x16_trifold"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const selfMailer = await client.printMail.selfMailers.retrieve('id');

console.log(selfMailer.id);
```

#### Response

```json
{
  "id": "self_mailer_123456",
  "object": "self_mailer",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "8.5x11_bifold",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class"
}
```

## Cancel Self Mailer

`client.printMail.selfMailers.delete(stringid, RequestOptionsoptions?): SelfMailer`

**delete** `/print-mail/v1/self_mailers/{id}`

Cancel a self-mailer by ID. Note that this operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "8.5x11_trifold" | "9.5x16_trifold"`

    Enum representing the supported self-mailer sizes.

    - `"8.5x11_bifold"`

    - `"8.5x11_trifold"`

    - `"9.5x16_trifold"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const selfMailer = await client.printMail.selfMailers.delete('id');

console.log(selfMailer.id);
```

#### Response

```json
{
  "id": "self_mailer_123456",
  "object": "self_mailer",
  "status": "cancelled",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "8.5x11_bifold",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class"
}
```

## Get Self Mailer Preview

`client.printMail.selfMailers.retrieveURL(stringid, RequestOptionsoptions?): SelfMailerRetrieveURLResponse`

**get** `/print-mail/v1/self_mailers/{id}/url`

Retrieve a self-mailer preview URL.

This is only available for customers with our document management addon, which offers
document generation and hosting capabilities. This endpoint has a much higher rate limit
than the regular order retrieval endpoint, so it is suitable for customer-facing use-cases.

### Parameters

- `id: string`

### Returns

- `SelfMailerRetrieveURLResponse`

  - `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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const response = await client.printMail.selfMailers.retrieveURL('id');

console.log(response.id);
```

#### Response

```json
{
  "id": "self_mailer_123456",
  "object": "self_mailer_url",
  "url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/self_mailer_uzTtdAPiBVC25hjEYDvyLk?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1736192587&Signature=GS6kJK3fgWWy49jq1Yb%2FRn%2BQjD4%3D"
}
```

## Progress Status

`client.printMail.selfMailers.progress(stringid, RequestOptionsoptions?): SelfMailer`

**post** `/print-mail/v1/self_mailers/{id}/progressions`

Progresses a self-mailer's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.

Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.

### Parameters

- `id: string`

### Returns

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "8.5x11_trifold" | "9.5x16_trifold"`

    Enum representing the supported self-mailer sizes.

    - `"8.5x11_bifold"`

    - `"8.5x11_trifold"`

    - `"9.5x16_trifold"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

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

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const selfMailer = await client.printMail.selfMailers.progress('id');

console.log(selfMailer.id);
```

#### Response

```json
{
  "id": "self_mailer_123456",
  "object": "self_mailer",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "8.5x11_bifold",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z",
  "mailingClass": "first_class"
}
```

## Domain Types

### Self Mailer

- `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" | "corrected" | "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?: string`

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

    - `addressLine2?: string`

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

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

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

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

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

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

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

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

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

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "8.5x11_trifold" | "9.5x16_trifold"`

    Enum representing the supported self-mailer sizes.

    - `"8.5x11_bifold"`

    - `"8.5x11_trifold"`

    - `"9.5x16_trifold"`

  - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

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

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

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

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

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

  - `description?: string`

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

  - `imbDate?: string`

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

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

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

  - `url?: 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 Create Response

- `SelfMailerCreateResponse = SelfMailer | SelfMailer`

  - `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" | "corrected" | "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?: string`

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

      - `addressLine2?: string`

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

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

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

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

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

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

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

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

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

      - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

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

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `object: "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" | "8.5x11_trifold" | "9.5x16_trifold"`

      Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

    - `status: "ready" | "printing" | "processed_for_delivery" | 2 more`

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

      - `"ready"`

      - `"printing"`

      - `"processed_for_delivery"`

      - `"completed"`

      - `"cancelled"`

    - `to: Contact`

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

    - `updatedAt: string`

      The UTC time at which this resource was last updated.

    - `cancellation?: Cancellation`

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

      - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

        The reason for the cancellation.

        - `"user_initiated"`

        - `"invalid_content"`

        - `"invalid_order_mailing_class"`

      - `cancelledByUser?: string`

        The user ID who cancelled the order.

      - `note?: string`

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

    - `description?: string`

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

    - `imbDate?: string`

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

    - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

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

      - `"entered_mail_stream"`

      - `"out_for_delivery"`

      - `"returned_to_sender"`

    - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

      See the section on Metadata.

    - `trackingNumber?: string`

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

    - `url?: 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.

  - `SelfMailer`

### Self Mailer Retrieve URL Response

- `SelfMailerRetrieveURLResponse`

  - `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.

# Return Envelopes

## Create Return Envelope

`client.printMail.returnEnvelopes.create(ReturnEnvelopeCreateParamsparams, RequestOptionsoptions?): ReturnEnvelope`

**post** `/print-mail/v1/return_envelopes`

Creates a new return envelope. Note that if there is already a return
envelope for the destination contact, this will fail with a
`return_envelope_already_exists_error`.

### Parameters

- `params: ReturnEnvelopeCreateParams`

  - `to: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

    Body param: A contact ID or a contact object containing the address that will be
    printed onto the return envelope.

    - `ContactCreateWithFirstName`

      - `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?: string`

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

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

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

      - `email?: string`

        Email of the contact.

      - `forceVerifiedStatus?: boolean`

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

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

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

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

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

      - `skipVerification?: boolean`

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

    - `ContactCreateWithCompanyName`

      - `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?: string`

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

      - `city?: string`

        The city of the contact's address.

      - `description?: string`

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

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

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

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

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

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

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

      - `skipVerification?: boolean`

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

    - `string`

  - `description?: string`

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

  - `metadata?: Record<string, unknown>`

    Body param: See the section on Metadata.

  - `idempotencyKey?: string`

    Header param

### Returns

- `ReturnEnvelope`

  - `id: string`

    A unique ID prefixed with return_envelope_

  - `available: number`

    The number of return envelopes available to use in your orders
    immediately. This increases when a return envelope order is filled and
    decreases as you send orders which include this return envelope.

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope"`

    Always `return_envelope`.

    - `"return_envelope"`

  - `to: To`

    The contact denormalized onto a return envelope when it is created. Unlike
    a full contact it is not a standalone resource, so it has no `object`,
    `live`, `createdAt`, or `updatedAt` fields.

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" | "corrected" | "failed"`

      One of `verified`, `corrected`, or `failed`.

      - `"verified"`

      - `"corrected"`

      - `"failed"`

    - `countryCode: string`

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

    - `addressErrors?: string`

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

    - `addressLine2?: string`

      Second line of the contact's address, if applicable.

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification?: 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.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const returnEnvelope = await client.printMail.returnEnvelopes.create({
  to: 'contact_kFjQtFqJtRXgahx5vgc9mA',
});

console.log(returnEnvelope.id);
```

#### Response

```json
{
  "id": "return_envelope_7mhJUt25TnagyYzy1N81SJ",
  "object": "return_envelope",
  "live": false,
  "available": 0,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "addressStatus": "verified"
  },
  "createdAt": "2021-12-16T03:06:17.419Z",
  "updatedAt": "2021-12-16T03:06:17.419Z"
}
```

## List Return Envelopes

`client.printMail.returnEnvelopes.list(ReturnEnvelopeListParamsquery?, RequestOptionsoptions?): SkipLimit<ReturnEnvelope>`

**get** `/print-mail/v1/return_envelopes`

Gets a list of return envelopes for the user.

### Parameters

- `query: ReturnEnvelopeListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `ReturnEnvelope`

  - `id: string`

    A unique ID prefixed with return_envelope_

  - `available: number`

    The number of return envelopes available to use in your orders
    immediately. This increases when a return envelope order is filled and
    decreases as you send orders which include this return envelope.

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope"`

    Always `return_envelope`.

    - `"return_envelope"`

  - `to: To`

    The contact denormalized onto a return envelope when it is created. Unlike
    a full contact it is not a standalone resource, so it has no `object`,
    `live`, `createdAt`, or `updatedAt` fields.

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" | "corrected" | "failed"`

      One of `verified`, `corrected`, or `failed`.

      - `"verified"`

      - `"corrected"`

      - `"failed"`

    - `countryCode: string`

      The ISO 3611-1 country code of the contact's address.

    - `addressErrors?: string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2?: string`

      Second line of the contact's address, if applicable.

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification?: 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.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const returnEnvelope of client.printMail.returnEnvelopes.list()) {
  console.log(returnEnvelope.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "return_envelope_7mhJUt25TnagyYzy1N81SJ",
      "object": "return_envelope",
      "live": false,
      "available": 0,
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "addressStatus": "verified"
      },
      "createdAt": "2021-12-16T03:06:17.419Z",
      "updatedAt": "2021-12-16T03:06:17.419Z"
    }
  ]
}
```

## Get Return Envelope

`client.printMail.returnEnvelopes.retrieve(stringid, RequestOptionsoptions?): ReturnEnvelope`

**get** `/print-mail/v1/return_envelopes/{id}`

Gets the information for a return envelope by `id`. This should be a
unique identifying string starting with `return_envelope_`.

### Parameters

- `id: string`

### Returns

- `ReturnEnvelope`

  - `id: string`

    A unique ID prefixed with return_envelope_

  - `available: number`

    The number of return envelopes available to use in your orders
    immediately. This increases when a return envelope order is filled and
    decreases as you send orders which include this return envelope.

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope"`

    Always `return_envelope`.

    - `"return_envelope"`

  - `to: To`

    The contact denormalized onto a return envelope when it is created. Unlike
    a full contact it is not a standalone resource, so it has no `object`,
    `live`, `createdAt`, or `updatedAt` fields.

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" | "corrected" | "failed"`

      One of `verified`, `corrected`, or `failed`.

      - `"verified"`

      - `"corrected"`

      - `"failed"`

    - `countryCode: string`

      The ISO 3611-1 country code of the contact's address.

    - `addressErrors?: string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2?: string`

      Second line of the contact's address, if applicable.

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification?: 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.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const returnEnvelope = await client.printMail.returnEnvelopes.retrieve('id');

console.log(returnEnvelope.id);
```

#### Response

```json
{
  "id": "return_envelope_7mhJUt25TnagyYzy1N81SJ",
  "object": "return_envelope",
  "live": false,
  "available": 0,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "addressStatus": "verified"
  },
  "createdAt": "2021-12-16T03:06:17.419Z",
  "updatedAt": "2021-12-16T03:06:17.419Z"
}
```

## Domain Types

### Return Envelope

- `ReturnEnvelope`

  - `id: string`

    A unique ID prefixed with return_envelope_

  - `available: number`

    The number of return envelopes available to use in your orders
    immediately. This increases when a return envelope order is filled and
    decreases as you send orders which include this return envelope.

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope"`

    Always `return_envelope`.

    - `"return_envelope"`

  - `to: To`

    The contact denormalized onto a return envelope when it is created. Unlike
    a full contact it is not a standalone resource, so it has no `object`,
    `live`, `createdAt`, or `updatedAt` fields.

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" | "corrected" | "failed"`

      One of `verified`, `corrected`, or `failed`.

      - `"verified"`

      - `"corrected"`

      - `"failed"`

    - `countryCode: string`

      The ISO 3611-1 country code of the contact's address.

    - `addressErrors?: string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2?: string`

      Second line of the contact's address, if applicable.

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification?: 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.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

# Orders

## Create Return Envelope Order

`client.printMail.returnEnvelopes.orders.create(stringid, OrderCreateParamsbody, RequestOptionsoptions?): ReturnEnvelopeOrder`

**post** `/print-mail/v1/return_envelopes/{id}/orders`

Creates a batch order of return envelopes. The minimum order quantity is
5000.

### Parameters

- `id: string`

- `body: OrderCreateParams`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Returns

- `ReturnEnvelopeOrder`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string | ReturnEnvelope`

    The ID of the return envelope that this order replenishes. Expanded
    into the full return envelope object on the individual order retrieval
    and cancellation endpoints when `expand[]=returnEnvelope` is supplied.

    - `string`

    - `ReturnEnvelope`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        The number of return envelopes available to use in your orders
        immediately. This increases when a return envelope order is filled and
        decreases as you send orders which include this return envelope.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: To`

        The contact denormalized onto a return envelope when it is created. Unlike
        a full contact it is not a standalone resource, so it has no `object`,
        `live`, `createdAt`, or `updatedAt` fields.

        - `id: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" | "corrected" | "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors?: string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: 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.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

  - `status: "placed" | "filled" | "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `quantityFilled?: number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const returnEnvelopeOrder = await client.printMail.returnEnvelopes.orders.create('id', {
  quantityOrdered: 5000,
  description: 'A batch of 5000',
});

console.log(returnEnvelopeOrder.id);
```

#### Response

```json
{
  "id": "return_envelope_order_cJhFxQhs69MGhxu3L5NvyA",
  "object": "return_envelope_order",
  "live": false,
  "returnEnvelope": "return_envelope_7mhJUt25TnagyYzy1N81SJ",
  "quantityOrdered": 5000,
  "status": "placed",
  "createdAt": "2021-12-16T03:23:22.617Z",
  "updatedAt": "2021-12-16T03:23:22.617Z"
}
```

## List Return Envelope Orders

`client.printMail.returnEnvelopes.orders.list(stringid, OrderListParamsquery?, RequestOptionsoptions?): SkipLimit<ReturnEnvelopeOrder>`

**get** `/print-mail/v1/return_envelopes/{id}/orders`

Gets a list of orders for the return envelope by `id`.

### Parameters

- `id: string`

- `query: OrderListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `ReturnEnvelopeOrder`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string | ReturnEnvelope`

    The ID of the return envelope that this order replenishes. Expanded
    into the full return envelope object on the individual order retrieval
    and cancellation endpoints when `expand[]=returnEnvelope` is supplied.

    - `string`

    - `ReturnEnvelope`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        The number of return envelopes available to use in your orders
        immediately. This increases when a return envelope order is filled and
        decreases as you send orders which include this return envelope.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: To`

        The contact denormalized onto a return envelope when it is created. Unlike
        a full contact it is not a standalone resource, so it has no `object`,
        `live`, `createdAt`, or `updatedAt` fields.

        - `id: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" | "corrected" | "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors?: string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: 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.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

  - `status: "placed" | "filled" | "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `quantityFilled?: number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const returnEnvelopeOrder of client.printMail.returnEnvelopes.orders.list('id')) {
  console.log(returnEnvelopeOrder.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "return_envelope_order_cJhFxQhs69MGhxu3L5NvyA",
      "object": "return_envelope_order",
      "live": false,
      "returnEnvelope": "return_envelope_7mhJUt25TnagyYzy1N81SJ",
      "quantityOrdered": 5000,
      "status": "placed",
      "createdAt": "2021-12-16T03:23:22.617Z",
      "updatedAt": "2021-12-16T03:23:22.617Z"
    }
  ]
}
```

## Get Return Envelope Order

`client.printMail.returnEnvelopes.orders.retrieve(stringorderID, OrderRetrieveParamsparams, RequestOptionsoptions?): ReturnEnvelopeOrder`

**get** `/print-mail/v1/return_envelopes/{id}/orders/{orderID}`

Gets a specific return envelope order by return envelope ID as `id` and
return envelope order ID as `orderID`.

### Parameters

- `orderID: string`

- `params: OrderRetrieveParams`

  - `id: string`

    Path param: The ID of the return envelope.

  - `expand?: Array<"returnEnvelope">`

    Query param: Pass `expand[]=returnEnvelope` to expand the order's
    `returnEnvelope` field into the full return envelope object.

    - `"returnEnvelope"`

### Returns

- `ReturnEnvelopeOrder`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string | ReturnEnvelope`

    The ID of the return envelope that this order replenishes. Expanded
    into the full return envelope object on the individual order retrieval
    and cancellation endpoints when `expand[]=returnEnvelope` is supplied.

    - `string`

    - `ReturnEnvelope`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        The number of return envelopes available to use in your orders
        immediately. This increases when a return envelope order is filled and
        decreases as you send orders which include this return envelope.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: To`

        The contact denormalized onto a return envelope when it is created. Unlike
        a full contact it is not a standalone resource, so it has no `object`,
        `live`, `createdAt`, or `updatedAt` fields.

        - `id: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" | "corrected" | "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors?: string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: 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.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

  - `status: "placed" | "filled" | "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `quantityFilled?: number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const returnEnvelopeOrder = await client.printMail.returnEnvelopes.orders.retrieve('orderID', {
  id: 'id',
});

console.log(returnEnvelopeOrder.id);
```

#### Response

```json
{
  "id": "return_envelope_order_cJhFxQhs69MGhxu3L5NvyA",
  "object": "return_envelope_order",
  "live": false,
  "returnEnvelope": "return_envelope_7mhJUt25TnagyYzy1N81SJ",
  "quantityOrdered": 5000,
  "status": "placed",
  "createdAt": "2021-12-16T03:23:22.617Z",
  "updatedAt": "2021-12-16T03:23:22.617Z"
}
```

## Fill Test Return Envelope Order

`client.printMail.returnEnvelopes.orders.fill(stringorderID, OrderFillParamsparams, RequestOptionsoptions?): ReturnEnvelopeOrder`

**post** `/print-mail/v1/return_envelopes/{id}/orders/{orderID}/fills`

Fills the return envelope order by `orderID` for the return envelope by
`id`. This is only available in test mode and can be used to simulate
how a live order would be filled.

Note: this will fail with a `return_envelope_order_cannot_fill_error` if
the order's status is not `placed`.

### Parameters

- `orderID: string`

- `params: OrderFillParams`

  - `id: string`

    The ID of the return envelope.

### Returns

- `ReturnEnvelopeOrder`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string | ReturnEnvelope`

    The ID of the return envelope that this order replenishes. Expanded
    into the full return envelope object on the individual order retrieval
    and cancellation endpoints when `expand[]=returnEnvelope` is supplied.

    - `string`

    - `ReturnEnvelope`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        The number of return envelopes available to use in your orders
        immediately. This increases when a return envelope order is filled and
        decreases as you send orders which include this return envelope.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: To`

        The contact denormalized onto a return envelope when it is created. Unlike
        a full contact it is not a standalone resource, so it has no `object`,
        `live`, `createdAt`, or `updatedAt` fields.

        - `id: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" | "corrected" | "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors?: string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: 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.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

  - `status: "placed" | "filled" | "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `quantityFilled?: number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const returnEnvelopeOrder = await client.printMail.returnEnvelopes.orders.fill('orderID', {
  id: 'id',
});

console.log(returnEnvelopeOrder.id);
```

#### Response

```json
{
  "id": "return_envelope_order_cJhFxQhs69MGhxu3L5NvyA",
  "object": "return_envelope_order",
  "live": false,
  "returnEnvelope": "return_envelope_7mhJUt25TnagyYzy1N81SJ",
  "quantityOrdered": 5000,
  "status": "filled",
  "createdAt": "2021-12-16T03:23:22.617Z",
  "updatedAt": "2021-12-16T03:23:22.617Z",
  "quantityFilled": 5000
}
```

## Cancel Return Envelope Order

`client.printMail.returnEnvelopes.orders.cancel(stringorderID, OrderCancelParamsparams, RequestOptionsoptions?): ReturnEnvelopeOrder`

**delete** `/print-mail/v1/return_envelopes/{id}/orders/{orderID}`

Cancels the return envelope order by `orderID` for the return envelope
by `id`. Note that this operation cannot be undone.

### Parameters

- `orderID: string`

- `params: OrderCancelParams`

  - `id: string`

    Path param: The ID of the return envelope.

  - `expand?: Array<"returnEnvelope">`

    Query param: Pass `expand[]=returnEnvelope` to expand the order's
    `returnEnvelope` field into the full return envelope object.

    - `"returnEnvelope"`

### Returns

- `ReturnEnvelopeOrder`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string | ReturnEnvelope`

    The ID of the return envelope that this order replenishes. Expanded
    into the full return envelope object on the individual order retrieval
    and cancellation endpoints when `expand[]=returnEnvelope` is supplied.

    - `string`

    - `ReturnEnvelope`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        The number of return envelopes available to use in your orders
        immediately. This increases when a return envelope order is filled and
        decreases as you send orders which include this return envelope.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: To`

        The contact denormalized onto a return envelope when it is created. Unlike
        a full contact it is not a standalone resource, so it has no `object`,
        `live`, `createdAt`, or `updatedAt` fields.

        - `id: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" | "corrected" | "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors?: string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: 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.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

  - `status: "placed" | "filled" | "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `quantityFilled?: number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const returnEnvelopeOrder = await client.printMail.returnEnvelopes.orders.cancel('orderID', {
  id: 'id',
});

console.log(returnEnvelopeOrder.id);
```

#### Response

```json
{
  "id": "return_envelope_order_cJhFxQhs69MGhxu3L5NvyA",
  "object": "return_envelope_order",
  "live": false,
  "returnEnvelope": "return_envelope_7mhJUt25TnagyYzy1N81SJ",
  "quantityOrdered": 5000,
  "status": "cancelled",
  "createdAt": "2021-12-16T03:23:22.617Z",
  "updatedAt": "2021-12-16T03:23:22.617Z"
}
```

## Domain Types

### Return Envelope Order

- `ReturnEnvelopeOrder`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string | ReturnEnvelope`

    The ID of the return envelope that this order replenishes. Expanded
    into the full return envelope object on the individual order retrieval
    and cancellation endpoints when `expand[]=returnEnvelope` is supplied.

    - `string`

    - `ReturnEnvelope`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        The number of return envelopes available to use in your orders
        immediately. This increases when a return envelope order is filled and
        decreases as you send orders which include this return envelope.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: To`

        The contact denormalized onto a return envelope when it is created. Unlike
        a full contact it is not a standalone resource, so it has no `object`,
        `live`, `createdAt`, or `updatedAt` fields.

        - `id: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" | "corrected" | "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors?: string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: 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.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

  - `status: "placed" | "filled" | "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `quantityFilled?: number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

# Campaigns

## Create Campaign

`client.printMail.campaigns.create(CampaignCreateParamsparams, RequestOptionsoptions?): Campaign`

**post** `/print-mail/v1/campaigns`

Create a new campaign.

A campaign links a mailing list with a specific mail piece configuration (letter, postcard, cheque, self-mailer, or snap pack)
to send bulk mail. Only one collateral type can be set per campaign.

Upon creation, the campaign enters the `drafting` status while assets are validated.

### Parameters

- `params: CampaignCreateParams`

  - `mailingList: string`

    Body param: The ID of the mailing list associated with this campaign.

  - `cheque?: Cheque`

    Body param: Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `bankAccount?: string`

      ID of the bank account to use for the cheque.

    - `currencyCode?: "CAD" | "USD"`

      Enum representing the supported currency codes.

      - `"CAD"`

      - `"USD"`

    - `description?: string`

      An optional description.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `letterPDF?: string | Uploadable`

      PDF file for an optional attached letter. Cannot be used with `letterTemplate`.

      - `string`

      - `Uploadable`

    - `letterSettings?: LetterSettings`

      Settings for the attached letter (e.g., color printing).

      - `color?: boolean`

        Whether to print the attached letter in color.

    - `letterTemplate?: string`

      ID of a template for an optional attached letter. Cannot be used with `letterPDF`.

    - `logo?: string`

      A publicly accessible URL for the logo to print on the cheque.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the cheque.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `memo?: string`

      Memo line text for the cheque.

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the cheque.

    - `message?: string`

      Message included on the cheque stub.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: ChequeSize`

      Enum representing the supported cheque sizes.

      - `"us_letter"`

      - `"us_legal"`

  - `defaultSenderContact?: string`

    Body param: The ID of the default sender contact to use for orders if not specified per recipient.

  - `description?: string`

    Body param: An optional string describing this resource. Will be visible in the API and the dashboard.

  - `letter?: Letter`

    Body param: Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `addressPlacement?: AddressPlacement`

      Enum representing the placement of the address on the letter.

      - `"top_first_page"`

      - `"insert_blank_page"`

    - `attachedPDF?: AttachedPdf`

      Model representing an attached PDF.

      - `file: string | Uploadable`

        The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `color?: boolean`

      Whether to print in color.

    - `description?: string`

      An optional description.

    - `doubleSided?: boolean`

      Whether to print on both sides of the paper.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `envelopeType?: "standard_double_window" | "flat"`

      The type of envelope used for the letter.

      - `"standard_double_window"`

      - `"flat"`

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the letter.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the letter.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `pdf?: string | Uploadable`

      A PDF file or URL for the letter content. Cannot be used with `template`.

      - `string`

      - `Uploadable`

    - `perforatedPage?: 1`

      Which page number should be perforated (if any).

      - `1`

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: LetterSize`

      Enum representing the supported letter sizes.

      - `"us_letter"`

      - `"a4"`

    - `template?: string`

      ID of a template for the letter content. Cannot be used with `pdf`.

  - `metadata?: Record<string, unknown>`

    Body param: See the section on Metadata.

  - `postcard?: Postcard`

    Body param: Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `backTemplate?: string`

      ID of the template for the back side. Cannot be used with `pdf`.

    - `description?: string`

      An optional description.

    - `frontTemplate?: string`

      ID of the template for the front side. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the postcard.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the postcard.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `pdf?: string | Uploadable`

      A 2-page PDF file for the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`.

      - `string`

      - `Uploadable`

    - `size?: "6x4" | "9x6" | "11x6"`

      Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

  - `selfMailer?: SelfMailer`

    Body param: Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the self-mailer.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the self-mailer.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `pdf?: string | Uploadable`

      A 2-page PDF file for the self-mailer content. Cannot be used with `insideTemplate`/`outsideTemplate`.

      - `string`

      - `Uploadable`

    - `size?: "8.5x11_bifold" | "8.5x11_trifold" | "9.5x16_trifold"`

      Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

  - `sendDate?: string`

    Body param: The scheduled date and time for the campaign to be sent.

  - `snapPack?: SnapPack`

    Body param: Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the snap pack.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the snap pack.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `pdf?: string | Uploadable`

      A 2-page PDF file for the snap pack content. Cannot be used with `insideTemplate`/`outsideTemplate`.

      - `string`

      - `Uploadable`

    - `size?: "8.5x11_bifold_v"`

      Enum representing the supported snap pack sizes.

      - `"8.5x11_bifold_v"`

  - `idempotencyKey?: string`

    Header param

### Returns

- `Campaign`

  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" | "changes_required" | "creating_orders" | 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?: Cheque`

    Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `bankAccount?: string`

      ID of the bank account to use for the cheque.

    - `currencyCode?: "CAD" | "USD"`

      Enum representing the supported currency codes.

      - `"CAD"`

      - `"USD"`

    - `description?: string`

      An optional description.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `letterSettings?: LetterSettings`

      Settings for the attached letter (e.g., color printing).

      - `color?: boolean`

        Whether to print the attached letter in color.

    - `letterTemplate?: string`

      ID of a template for an optional attached letter. Cannot be used with `letterPDF`.

    - `letterUploadedPDF?: string`

      A signed URL to the attached letter PDF, if any.

    - `logo?: string`

      A publicly accessible URL for the logo to print on the cheque.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the cheque.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `memo?: string`

      Memo line text for the cheque.

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the cheque.

    - `message?: string`

      Message included on the cheque stub.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: ChequeSize`

      Enum representing the supported cheque sizes.

      - `"us_letter"`

      - `"us_legal"`

  - `defaultSenderContact?: string`

    The ID of the default sender contact to use for orders if not specified per recipient.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "internal_error"`

      Type of error encountered during campaign processing.

      - `"processing_error"`

      - `"internal_error"`

  - `letter?: Letter`

    Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `addressPlacement?: AddressPlacement`

      Enum representing the placement of the address on the letter.

      - `"top_first_page"`

      - `"insert_blank_page"`

    - `attachedPDF?: AttachedPdf`

      Model representing an attached PDF.

      - `file: string | Uploadable`

        The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `color?: boolean`

      Whether to print in color.

    - `description?: string`

      An optional description.

    - `doubleSided?: boolean`

      Whether to print on both sides of the paper.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `envelopeType?: "standard_double_window" | "flat"`

      The type of envelope used for the letter.

      - `"standard_double_window"`

      - `"flat"`

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the letter.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the letter.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `perforatedPage?: 1`

      Which page number should be perforated (if any).

      - `1`

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: LetterSize`

      Enum representing the supported letter sizes.

      - `"us_letter"`

      - `"a4"`

    - `template?: string`

      ID of a template for the letter content. Cannot be used with `pdf`.

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `orderPreviewURL?: string`

    A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.

  - `postcard?: Postcard`

    Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `backTemplate?: string`

      ID of the template for the back side. Cannot be used with `pdf`.

    - `description?: string`

      An optional description.

    - `frontTemplate?: string`

      ID of the template for the front side. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the postcard.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the postcard.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `size?: "6x4" | "9x6" | "11x6"`

      Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the campaign is in the `ready` status.

  - `selfMailer?: SelfMailer`

    Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the self-mailer.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the self-mailer.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold" | "8.5x11_trifold" | "9.5x16_trifold"`

      Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `sendDate?: string`

    The scheduled date and time for the campaign to be sent.

  - `snapPack?: SnapPack`

    Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the snap pack.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the snap pack.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold_v"`

      Enum representing the supported snap pack sizes.

      - `"8.5x11_bifold_v"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const campaign = await client.printMail.campaigns.create({ mailingList: 'mailingList' });

console.log(campaign.id);
```

#### Response

```json
{
  "id": "campaign_sqF12lZ1VlBb",
  "createdAt": "2019-12-27T18:11:19.117Z",
  "createdCount": 0,
  "live": true,
  "mailingList": "mailingList",
  "status": "drafting",
  "updatedAt": "2019-12-27T18:11:19.117Z",
  "cheque": {
    "bankAccount": "bankAccount",
    "currencyCode": "CAD",
    "description": "description",
    "envelope": "envelope",
    "letterSettings": {
      "color": true
    },
    "letterTemplate": "letterTemplate",
    "letterUploadedPDF": "https://example.com",
    "logo": "https://example.com",
    "mailingClass": "first_class",
    "memo": "memo",
    "mergeVariables": {
      "foo": "bar"
    },
    "message": "message",
    "metadata": {
      "foo": "string"
    },
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter"
  },
  "defaultSenderContact": "defaultSenderContact",
  "description": "description",
  "errors": [
    {
      "message": "message",
      "type": "processing_error"
    }
  ],
  "letter": {
    "addressPlacement": "top_first_page",
    "attachedPDF": {
      "file": "https://example.com",
      "placement": "before_template"
    },
    "color": true,
    "description": "description",
    "doubleSided": true,
    "envelope": "envelope",
    "envelopeType": "standard_double_window",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "perforatedPage": 1,
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter",
    "template": "template",
    "uploadedPDF": "https://example.com"
  },
  "metadata": {
    "foo": "bar"
  },
  "orderPreviewURL": "https://example.com",
  "postcard": {
    "backTemplate": "backTemplate",
    "description": "description",
    "frontTemplate": "frontTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "size": "6x4",
    "uploadedPDF": "https://example.com"
  },
  "reportURL": "https://example.com",
  "selfMailer": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold",
    "uploadedPDF": "https://example.com"
  },
  "sendDate": "2019-12-27T18:11:19.117Z",
  "snapPack": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold_v",
    "uploadedPDF": "https://example.com"
  }
}
```

## List Campaigns

`client.printMail.campaigns.list(CampaignListParamsquery?, RequestOptionsoptions?): SkipLimit<Campaign>`

**get** `/print-mail/v1/campaigns`

Retrieve a list of campaigns.

Returns a paginated list of campaigns associated with the authenticated organization,
filterable by various parameters.

### Parameters

- `query: CampaignListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `Campaign`

  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" | "changes_required" | "creating_orders" | 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?: Cheque`

    Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `bankAccount?: string`

      ID of the bank account to use for the cheque.

    - `currencyCode?: "CAD" | "USD"`

      Enum representing the supported currency codes.

      - `"CAD"`

      - `"USD"`

    - `description?: string`

      An optional description.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `letterSettings?: LetterSettings`

      Settings for the attached letter (e.g., color printing).

      - `color?: boolean`

        Whether to print the attached letter in color.

    - `letterTemplate?: string`

      ID of a template for an optional attached letter. Cannot be used with `letterPDF`.

    - `letterUploadedPDF?: string`

      A signed URL to the attached letter PDF, if any.

    - `logo?: string`

      A publicly accessible URL for the logo to print on the cheque.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the cheque.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `memo?: string`

      Memo line text for the cheque.

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the cheque.

    - `message?: string`

      Message included on the cheque stub.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: ChequeSize`

      Enum representing the supported cheque sizes.

      - `"us_letter"`

      - `"us_legal"`

  - `defaultSenderContact?: string`

    The ID of the default sender contact to use for orders if not specified per recipient.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "internal_error"`

      Type of error encountered during campaign processing.

      - `"processing_error"`

      - `"internal_error"`

  - `letter?: Letter`

    Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `addressPlacement?: AddressPlacement`

      Enum representing the placement of the address on the letter.

      - `"top_first_page"`

      - `"insert_blank_page"`

    - `attachedPDF?: AttachedPdf`

      Model representing an attached PDF.

      - `file: string | Uploadable`

        The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `color?: boolean`

      Whether to print in color.

    - `description?: string`

      An optional description.

    - `doubleSided?: boolean`

      Whether to print on both sides of the paper.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `envelopeType?: "standard_double_window" | "flat"`

      The type of envelope used for the letter.

      - `"standard_double_window"`

      - `"flat"`

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the letter.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the letter.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `perforatedPage?: 1`

      Which page number should be perforated (if any).

      - `1`

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: LetterSize`

      Enum representing the supported letter sizes.

      - `"us_letter"`

      - `"a4"`

    - `template?: string`

      ID of a template for the letter content. Cannot be used with `pdf`.

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `orderPreviewURL?: string`

    A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.

  - `postcard?: Postcard`

    Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `backTemplate?: string`

      ID of the template for the back side. Cannot be used with `pdf`.

    - `description?: string`

      An optional description.

    - `frontTemplate?: string`

      ID of the template for the front side. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the postcard.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the postcard.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `size?: "6x4" | "9x6" | "11x6"`

      Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the campaign is in the `ready` status.

  - `selfMailer?: SelfMailer`

    Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the self-mailer.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the self-mailer.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold" | "8.5x11_trifold" | "9.5x16_trifold"`

      Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `sendDate?: string`

    The scheduled date and time for the campaign to be sent.

  - `snapPack?: SnapPack`

    Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the snap pack.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the snap pack.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold_v"`

      Enum representing the supported snap pack sizes.

      - `"8.5x11_bifold_v"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const campaign of client.printMail.campaigns.list()) {
  console.log(campaign.id);
}
```

#### Response

```json
{
  "data": [
    {
      "id": "campaign_sqF12lZ1VlBb",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "createdCount": 0,
      "live": true,
      "mailingList": "mailingList",
      "status": "drafting",
      "updatedAt": "2019-12-27T18:11:19.117Z",
      "cheque": {
        "bankAccount": "bankAccount",
        "currencyCode": "CAD",
        "description": "description",
        "envelope": "envelope",
        "letterSettings": {
          "color": true
        },
        "letterTemplate": "letterTemplate",
        "letterUploadedPDF": "https://example.com",
        "logo": "https://example.com",
        "mailingClass": "first_class",
        "memo": "memo",
        "mergeVariables": {
          "foo": "bar"
        },
        "message": "message",
        "metadata": {
          "foo": "string"
        },
        "returnEnvelope": "returnEnvelope",
        "size": "us_letter"
      },
      "defaultSenderContact": "defaultSenderContact",
      "description": "description",
      "errors": [
        {
          "message": "message",
          "type": "processing_error"
        }
      ],
      "letter": {
        "addressPlacement": "top_first_page",
        "attachedPDF": {
          "file": "https://example.com",
          "placement": "before_template"
        },
        "color": true,
        "description": "description",
        "doubleSided": true,
        "envelope": "envelope",
        "envelopeType": "standard_double_window",
        "mailingClass": "first_class",
        "mergeVariables": {
          "foo": "bar"
        },
        "metadata": {
          "foo": "string"
        },
        "paper": "standard",
        "perforatedPage": 1,
        "returnEnvelope": "returnEnvelope",
        "size": "us_letter",
        "template": "template",
        "uploadedPDF": "https://example.com"
      },
      "metadata": {
        "foo": "bar"
      },
      "orderPreviewURL": "https://example.com",
      "postcard": {
        "backTemplate": "backTemplate",
        "description": "description",
        "frontTemplate": "frontTemplate",
        "mailingClass": "first_class",
        "mergeVariables": {
          "foo": "bar"
        },
        "metadata": {
          "foo": "string"
        },
        "paper": "standard",
        "size": "6x4",
        "uploadedPDF": "https://example.com"
      },
      "reportURL": "https://example.com",
      "selfMailer": {
        "description": "description",
        "insideTemplate": "insideTemplate",
        "mailingClass": "first_class",
        "mergeVariables": {
          "foo": "bar"
        },
        "metadata": {
          "foo": "string"
        },
        "outsideTemplate": "outsideTemplate",
        "size": "8.5x11_bifold",
        "uploadedPDF": "https://example.com"
      },
      "sendDate": "2019-12-27T18:11:19.117Z",
      "snapPack": {
        "description": "description",
        "insideTemplate": "insideTemplate",
        "mailingClass": "first_class",
        "mergeVariables": {
          "foo": "bar"
        },
        "metadata": {
          "foo": "string"
        },
        "outsideTemplate": "outsideTemplate",
        "size": "8.5x11_bifold_v",
        "uploadedPDF": "https://example.com"
      }
    }
  ],
  "limit": 0,
  "object": "list",
  "skip": 0,
  "totalCount": 0
}
```

## Get Campaign

`client.printMail.campaigns.retrieve(stringid, RequestOptionsoptions?): Campaign`

**get** `/print-mail/v1/campaigns/{id}`

Retrieve a specific campaign by its ID.

### Parameters

- `id: string`

### Returns

- `Campaign`

  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" | "changes_required" | "creating_orders" | 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?: Cheque`

    Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `bankAccount?: string`

      ID of the bank account to use for the cheque.

    - `currencyCode?: "CAD" | "USD"`

      Enum representing the supported currency codes.

      - `"CAD"`

      - `"USD"`

    - `description?: string`

      An optional description.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `letterSettings?: LetterSettings`

      Settings for the attached letter (e.g., color printing).

      - `color?: boolean`

        Whether to print the attached letter in color.

    - `letterTemplate?: string`

      ID of a template for an optional attached letter. Cannot be used with `letterPDF`.

    - `letterUploadedPDF?: string`

      A signed URL to the attached letter PDF, if any.

    - `logo?: string`

      A publicly accessible URL for the logo to print on the cheque.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the cheque.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `memo?: string`

      Memo line text for the cheque.

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the cheque.

    - `message?: string`

      Message included on the cheque stub.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: ChequeSize`

      Enum representing the supported cheque sizes.

      - `"us_letter"`

      - `"us_legal"`

  - `defaultSenderContact?: string`

    The ID of the default sender contact to use for orders if not specified per recipient.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "internal_error"`

      Type of error encountered during campaign processing.

      - `"processing_error"`

      - `"internal_error"`

  - `letter?: Letter`

    Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `addressPlacement?: AddressPlacement`

      Enum representing the placement of the address on the letter.

      - `"top_first_page"`

      - `"insert_blank_page"`

    - `attachedPDF?: AttachedPdf`

      Model representing an attached PDF.

      - `file: string | Uploadable`

        The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `color?: boolean`

      Whether to print in color.

    - `description?: string`

      An optional description.

    - `doubleSided?: boolean`

      Whether to print on both sides of the paper.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `envelopeType?: "standard_double_window" | "flat"`

      The type of envelope used for the letter.

      - `"standard_double_window"`

      - `"flat"`

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the letter.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the letter.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `perforatedPage?: 1`

      Which page number should be perforated (if any).

      - `1`

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: LetterSize`

      Enum representing the supported letter sizes.

      - `"us_letter"`

      - `"a4"`

    - `template?: string`

      ID of a template for the letter content. Cannot be used with `pdf`.

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `orderPreviewURL?: string`

    A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.

  - `postcard?: Postcard`

    Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `backTemplate?: string`

      ID of the template for the back side. Cannot be used with `pdf`.

    - `description?: string`

      An optional description.

    - `frontTemplate?: string`

      ID of the template for the front side. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the postcard.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the postcard.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `size?: "6x4" | "9x6" | "11x6"`

      Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the campaign is in the `ready` status.

  - `selfMailer?: SelfMailer`

    Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the self-mailer.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the self-mailer.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold" | "8.5x11_trifold" | "9.5x16_trifold"`

      Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `sendDate?: string`

    The scheduled date and time for the campaign to be sent.

  - `snapPack?: SnapPack`

    Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the snap pack.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the snap pack.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold_v"`

      Enum representing the supported snap pack sizes.

      - `"8.5x11_bifold_v"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const campaign = await client.printMail.campaigns.retrieve('id');

console.log(campaign.id);
```

#### Response

```json
{
  "id": "campaign_sqF12lZ1VlBb",
  "createdAt": "2019-12-27T18:11:19.117Z",
  "createdCount": 0,
  "live": true,
  "mailingList": "mailingList",
  "status": "drafting",
  "updatedAt": "2019-12-27T18:11:19.117Z",
  "cheque": {
    "bankAccount": "bankAccount",
    "currencyCode": "CAD",
    "description": "description",
    "envelope": "envelope",
    "letterSettings": {
      "color": true
    },
    "letterTemplate": "letterTemplate",
    "letterUploadedPDF": "https://example.com",
    "logo": "https://example.com",
    "mailingClass": "first_class",
    "memo": "memo",
    "mergeVariables": {
      "foo": "bar"
    },
    "message": "message",
    "metadata": {
      "foo": "string"
    },
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter"
  },
  "defaultSenderContact": "defaultSenderContact",
  "description": "description",
  "errors": [
    {
      "message": "message",
      "type": "processing_error"
    }
  ],
  "letter": {
    "addressPlacement": "top_first_page",
    "attachedPDF": {
      "file": "https://example.com",
      "placement": "before_template"
    },
    "color": true,
    "description": "description",
    "doubleSided": true,
    "envelope": "envelope",
    "envelopeType": "standard_double_window",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "perforatedPage": 1,
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter",
    "template": "template",
    "uploadedPDF": "https://example.com"
  },
  "metadata": {
    "foo": "bar"
  },
  "orderPreviewURL": "https://example.com",
  "postcard": {
    "backTemplate": "backTemplate",
    "description": "description",
    "frontTemplate": "frontTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "size": "6x4",
    "uploadedPDF": "https://example.com"
  },
  "reportURL": "https://example.com",
  "selfMailer": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold",
    "uploadedPDF": "https://example.com"
  },
  "sendDate": "2019-12-27T18:11:19.117Z",
  "snapPack": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold_v",
    "uploadedPDF": "https://example.com"
  }
}
```

## Update Campaign

`client.printMail.campaigns.update(stringid, CampaignUpdateParamsbody, RequestOptionsoptions?): Campaign`

**post** `/print-mail/v1/campaigns/{id}`

Update an existing campaign.

Campaigns can only be updated if they are in the `draft` or `changes_required` status.
Updating a campaign will trigger reprocessing and set its status back to `drafting`.

### Parameters

- `id: string`

- `body: CampaignUpdateParams`

  - `cheque?: Cheque | null`

    Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `bankAccount?: string`

      ID of the bank account to use for the cheque.

    - `currencyCode?: "CAD" | "USD"`

      Enum representing the supported currency codes.

      - `"CAD"`

      - `"USD"`

    - `description?: string`

      An optional description.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `letterPDF?: string | Uploadable`

      PDF file for an optional attached letter. Cannot be used with `letterTemplate`.

      - `string`

      - `Uploadable`

    - `letterSettings?: LetterSettings`

      Settings for the attached letter (e.g., color printing).

      - `color?: boolean`

        Whether to print the attached letter in color.

    - `letterTemplate?: string`

      ID of a template for an optional attached letter. Cannot be used with `letterPDF`.

    - `logo?: string`

      A publicly accessible URL for the logo to print on the cheque.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the cheque.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `memo?: string`

      Memo line text for the cheque.

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the cheque.

    - `message?: string`

      Message included on the cheque stub.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: ChequeSize`

      Enum representing the supported cheque sizes.

      - `"us_letter"`

      - `"us_legal"`

  - `defaultSenderContact?: string | null`

    The ID of the default sender contact. Set to `null` to remove.

  - `description?: string | null`

    An optional description for the campaign. Set to `null` to remove the existing description.

  - `letter?: Letter | null`

    Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `addressPlacement?: AddressPlacement`

      Enum representing the placement of the address on the letter.

      - `"top_first_page"`

      - `"insert_blank_page"`

    - `attachedPDF?: AttachedPdf`

      Model representing an attached PDF.

      - `file: string | Uploadable`

        The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `color?: boolean`

      Whether to print in color.

    - `description?: string`

      An optional description.

    - `doubleSided?: boolean`

      Whether to print on both sides of the paper.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `envelopeType?: "standard_double_window" | "flat"`

      The type of envelope used for the letter.

      - `"standard_double_window"`

      - `"flat"`

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the letter.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the letter.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `pdf?: string | Uploadable`

      A PDF file or URL for the letter content. Cannot be used with `template`.

      - `string`

      - `Uploadable`

    - `perforatedPage?: 1`

      Which page number should be perforated (if any).

      - `1`

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: LetterSize`

      Enum representing the supported letter sizes.

      - `"us_letter"`

      - `"a4"`

    - `template?: string`

      ID of a template for the letter content. Cannot be used with `pdf`.

  - `mailingList?: string`

    The ID of the mailing list to associate with this campaign.

  - `metadata?: Record<string, string> | null`

    Optional key-value data associated with the campaign. Set to `null` to remove existing metadata.

  - `postcard?: Postcard | null`

    Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `backTemplate?: string`

      ID of the template for the back side. Cannot be used with `pdf`.

    - `description?: string`

      An optional description.

    - `frontTemplate?: string`

      ID of the template for the front side. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the postcard.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the postcard.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `pdf?: string | Uploadable`

      A 2-page PDF file for the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`.

      - `string`

      - `Uploadable`

    - `size?: "6x4" | "9x6" | "11x6"`

      Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

  - `selfMailer?: SelfMailer | null`

    Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the self-mailer.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the self-mailer.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `pdf?: string | Uploadable`

      A 2-page PDF file for the self-mailer content. Cannot be used with `insideTemplate`/`outsideTemplate`.

      - `string`

      - `Uploadable`

    - `size?: "8.5x11_bifold" | "8.5x11_trifold" | "9.5x16_trifold"`

      Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

  - `snapPack?: SnapPack | null`

    Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the snap pack.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the snap pack.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `pdf?: string | Uploadable`

      A 2-page PDF file for the snap pack content. Cannot be used with `insideTemplate`/`outsideTemplate`.

      - `string`

      - `Uploadable`

    - `size?: "8.5x11_bifold_v"`

      Enum representing the supported snap pack sizes.

      - `"8.5x11_bifold_v"`

### Returns

- `Campaign`

  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" | "changes_required" | "creating_orders" | 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?: Cheque`

    Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `bankAccount?: string`

      ID of the bank account to use for the cheque.

    - `currencyCode?: "CAD" | "USD"`

      Enum representing the supported currency codes.

      - `"CAD"`

      - `"USD"`

    - `description?: string`

      An optional description.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `letterSettings?: LetterSettings`

      Settings for the attached letter (e.g., color printing).

      - `color?: boolean`

        Whether to print the attached letter in color.

    - `letterTemplate?: string`

      ID of a template for an optional attached letter. Cannot be used with `letterPDF`.

    - `letterUploadedPDF?: string`

      A signed URL to the attached letter PDF, if any.

    - `logo?: string`

      A publicly accessible URL for the logo to print on the cheque.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the cheque.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `memo?: string`

      Memo line text for the cheque.

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the cheque.

    - `message?: string`

      Message included on the cheque stub.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: ChequeSize`

      Enum representing the supported cheque sizes.

      - `"us_letter"`

      - `"us_legal"`

  - `defaultSenderContact?: string`

    The ID of the default sender contact to use for orders if not specified per recipient.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "internal_error"`

      Type of error encountered during campaign processing.

      - `"processing_error"`

      - `"internal_error"`

  - `letter?: Letter`

    Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `addressPlacement?: AddressPlacement`

      Enum representing the placement of the address on the letter.

      - `"top_first_page"`

      - `"insert_blank_page"`

    - `attachedPDF?: AttachedPdf`

      Model representing an attached PDF.

      - `file: string | Uploadable`

        The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `color?: boolean`

      Whether to print in color.

    - `description?: string`

      An optional description.

    - `doubleSided?: boolean`

      Whether to print on both sides of the paper.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `envelopeType?: "standard_double_window" | "flat"`

      The type of envelope used for the letter.

      - `"standard_double_window"`

      - `"flat"`

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the letter.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the letter.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `perforatedPage?: 1`

      Which page number should be perforated (if any).

      - `1`

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: LetterSize`

      Enum representing the supported letter sizes.

      - `"us_letter"`

      - `"a4"`

    - `template?: string`

      ID of a template for the letter content. Cannot be used with `pdf`.

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `orderPreviewURL?: string`

    A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.

  - `postcard?: Postcard`

    Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `backTemplate?: string`

      ID of the template for the back side. Cannot be used with `pdf`.

    - `description?: string`

      An optional description.

    - `frontTemplate?: string`

      ID of the template for the front side. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the postcard.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the postcard.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `size?: "6x4" | "9x6" | "11x6"`

      Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the campaign is in the `ready` status.

  - `selfMailer?: SelfMailer`

    Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the self-mailer.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the self-mailer.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold" | "8.5x11_trifold" | "9.5x16_trifold"`

      Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `sendDate?: string`

    The scheduled date and time for the campaign to be sent.

  - `snapPack?: SnapPack`

    Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the snap pack.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the snap pack.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold_v"`

      Enum representing the supported snap pack sizes.

      - `"8.5x11_bifold_v"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const campaign = await client.printMail.campaigns.update('id');

console.log(campaign.id);
```

#### Response

```json
{
  "id": "campaign_sqF12lZ1VlBb",
  "createdAt": "2019-12-27T18:11:19.117Z",
  "createdCount": 0,
  "live": true,
  "mailingList": "mailingList",
  "status": "drafting",
  "updatedAt": "2019-12-27T18:11:19.117Z",
  "cheque": {
    "bankAccount": "bankAccount",
    "currencyCode": "CAD",
    "description": "description",
    "envelope": "envelope",
    "letterSettings": {
      "color": true
    },
    "letterTemplate": "letterTemplate",
    "letterUploadedPDF": "https://example.com",
    "logo": "https://example.com",
    "mailingClass": "first_class",
    "memo": "memo",
    "mergeVariables": {
      "foo": "bar"
    },
    "message": "message",
    "metadata": {
      "foo": "string"
    },
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter"
  },
  "defaultSenderContact": "defaultSenderContact",
  "description": "description",
  "errors": [
    {
      "message": "message",
      "type": "processing_error"
    }
  ],
  "letter": {
    "addressPlacement": "top_first_page",
    "attachedPDF": {
      "file": "https://example.com",
      "placement": "before_template"
    },
    "color": true,
    "description": "description",
    "doubleSided": true,
    "envelope": "envelope",
    "envelopeType": "standard_double_window",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "perforatedPage": 1,
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter",
    "template": "template",
    "uploadedPDF": "https://example.com"
  },
  "metadata": {
    "foo": "bar"
  },
  "orderPreviewURL": "https://example.com",
  "postcard": {
    "backTemplate": "backTemplate",
    "description": "description",
    "frontTemplate": "frontTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "size": "6x4",
    "uploadedPDF": "https://example.com"
  },
  "reportURL": "https://example.com",
  "selfMailer": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold",
    "uploadedPDF": "https://example.com"
  },
  "sendDate": "2019-12-27T18:11:19.117Z",
  "snapPack": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold_v",
    "uploadedPDF": "https://example.com"
  }
}
```

## Delete Campaign

`client.printMail.campaigns.delete(stringid, RequestOptionsoptions?): CampaignDeleteResponse`

**delete** `/print-mail/v1/campaigns/{id}`

Delete a campaign.

Campaigns can only be deleted if they are in `draft`, `changes_required`, or `ready` status.
This also permanently deletes associated resources. This operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `CampaignDeleteResponse`

  - `id: string`

    A unique ID prefixed with campaign_

  - `deleted: true`

    - `true`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const campaign = await client.printMail.campaigns.delete('id');

console.log(campaign.id);
```

#### Response

```json
{
  "id": "campaign_sqF12lZ1VlBb",
  "deleted": true
}
```

## Send Campaign

`client.printMail.campaigns.send(stringid, CampaignSendParamsbody, RequestOptionsoptions?): Campaign`

**post** `/print-mail/v1/campaigns/{id}/send`

Send a campaign for processing.

This action transitions a campaign from the `draft` status to `creating_orders`.
You can optionally specify a future `sendDate`. Once sent, the campaign cannot be updated.

### Parameters

- `id: string`

- `body: CampaignSendParams`

  - `sendDate?: (string & {}) | 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`

  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" | "changes_required" | "creating_orders" | 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?: Cheque`

    Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `bankAccount?: string`

      ID of the bank account to use for the cheque.

    - `currencyCode?: "CAD" | "USD"`

      Enum representing the supported currency codes.

      - `"CAD"`

      - `"USD"`

    - `description?: string`

      An optional description.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `letterSettings?: LetterSettings`

      Settings for the attached letter (e.g., color printing).

      - `color?: boolean`

        Whether to print the attached letter in color.

    - `letterTemplate?: string`

      ID of a template for an optional attached letter. Cannot be used with `letterPDF`.

    - `letterUploadedPDF?: string`

      A signed URL to the attached letter PDF, if any.

    - `logo?: string`

      A publicly accessible URL for the logo to print on the cheque.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the cheque.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `memo?: string`

      Memo line text for the cheque.

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the cheque.

    - `message?: string`

      Message included on the cheque stub.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: ChequeSize`

      Enum representing the supported cheque sizes.

      - `"us_letter"`

      - `"us_legal"`

  - `defaultSenderContact?: string`

    The ID of the default sender contact to use for orders if not specified per recipient.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "internal_error"`

      Type of error encountered during campaign processing.

      - `"processing_error"`

      - `"internal_error"`

  - `letter?: Letter`

    Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `addressPlacement?: AddressPlacement`

      Enum representing the placement of the address on the letter.

      - `"top_first_page"`

      - `"insert_blank_page"`

    - `attachedPDF?: AttachedPdf`

      Model representing an attached PDF.

      - `file: string | Uploadable`

        The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `color?: boolean`

      Whether to print in color.

    - `description?: string`

      An optional description.

    - `doubleSided?: boolean`

      Whether to print on both sides of the paper.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `envelopeType?: "standard_double_window" | "flat"`

      The type of envelope used for the letter.

      - `"standard_double_window"`

      - `"flat"`

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the letter.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the letter.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `perforatedPage?: 1`

      Which page number should be perforated (if any).

      - `1`

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: LetterSize`

      Enum representing the supported letter sizes.

      - `"us_letter"`

      - `"a4"`

    - `template?: string`

      ID of a template for the letter content. Cannot be used with `pdf`.

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `orderPreviewURL?: string`

    A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.

  - `postcard?: Postcard`

    Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `backTemplate?: string`

      ID of the template for the back side. Cannot be used with `pdf`.

    - `description?: string`

      An optional description.

    - `frontTemplate?: string`

      ID of the template for the front side. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the postcard.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the postcard.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `size?: "6x4" | "9x6" | "11x6"`

      Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the campaign is in the `ready` status.

  - `selfMailer?: SelfMailer`

    Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the self-mailer.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the self-mailer.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold" | "8.5x11_trifold" | "9.5x16_trifold"`

      Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `sendDate?: string`

    The scheduled date and time for the campaign to be sent.

  - `snapPack?: SnapPack`

    Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the snap pack.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the snap pack.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold_v"`

      Enum representing the supported snap pack sizes.

      - `"8.5x11_bifold_v"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const campaign = await client.printMail.campaigns.send('id');

console.log(campaign.id);
```

#### Response

```json
{
  "id": "campaign_sqF12lZ1VlBb",
  "createdAt": "2019-12-27T18:11:19.117Z",
  "createdCount": 0,
  "live": true,
  "mailingList": "mailingList",
  "status": "drafting",
  "updatedAt": "2019-12-27T18:11:19.117Z",
  "cheque": {
    "bankAccount": "bankAccount",
    "currencyCode": "CAD",
    "description": "description",
    "envelope": "envelope",
    "letterSettings": {
      "color": true
    },
    "letterTemplate": "letterTemplate",
    "letterUploadedPDF": "https://example.com",
    "logo": "https://example.com",
    "mailingClass": "first_class",
    "memo": "memo",
    "mergeVariables": {
      "foo": "bar"
    },
    "message": "message",
    "metadata": {
      "foo": "string"
    },
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter"
  },
  "defaultSenderContact": "defaultSenderContact",
  "description": "description",
  "errors": [
    {
      "message": "message",
      "type": "processing_error"
    }
  ],
  "letter": {
    "addressPlacement": "top_first_page",
    "attachedPDF": {
      "file": "https://example.com",
      "placement": "before_template"
    },
    "color": true,
    "description": "description",
    "doubleSided": true,
    "envelope": "envelope",
    "envelopeType": "standard_double_window",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "perforatedPage": 1,
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter",
    "template": "template",
    "uploadedPDF": "https://example.com"
  },
  "metadata": {
    "foo": "bar"
  },
  "orderPreviewURL": "https://example.com",
  "postcard": {
    "backTemplate": "backTemplate",
    "description": "description",
    "frontTemplate": "frontTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "size": "6x4",
    "uploadedPDF": "https://example.com"
  },
  "reportURL": "https://example.com",
  "selfMailer": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold",
    "uploadedPDF": "https://example.com"
  },
  "sendDate": "2019-12-27T18:11:19.117Z",
  "snapPack": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold_v",
    "uploadedPDF": "https://example.com"
  }
}
```

## Domain Types

### Campaign

- `Campaign`

  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" | "changes_required" | "creating_orders" | 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?: Cheque`

    Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `bankAccount?: string`

      ID of the bank account to use for the cheque.

    - `currencyCode?: "CAD" | "USD"`

      Enum representing the supported currency codes.

      - `"CAD"`

      - `"USD"`

    - `description?: string`

      An optional description.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `letterSettings?: LetterSettings`

      Settings for the attached letter (e.g., color printing).

      - `color?: boolean`

        Whether to print the attached letter in color.

    - `letterTemplate?: string`

      ID of a template for an optional attached letter. Cannot be used with `letterPDF`.

    - `letterUploadedPDF?: string`

      A signed URL to the attached letter PDF, if any.

    - `logo?: string`

      A publicly accessible URL for the logo to print on the cheque.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the cheque.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `memo?: string`

      Memo line text for the cheque.

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the cheque.

    - `message?: string`

      Message included on the cheque stub.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: ChequeSize`

      Enum representing the supported cheque sizes.

      - `"us_letter"`

      - `"us_legal"`

  - `defaultSenderContact?: string`

    The ID of the default sender contact to use for orders if not specified per recipient.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "internal_error"`

      Type of error encountered during campaign processing.

      - `"processing_error"`

      - `"internal_error"`

  - `letter?: Letter`

    Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `addressPlacement?: AddressPlacement`

      Enum representing the placement of the address on the letter.

      - `"top_first_page"`

      - `"insert_blank_page"`

    - `attachedPDF?: AttachedPdf`

      Model representing an attached PDF.

      - `file: string | Uploadable`

        The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

        - `string`

        - `Uploadable`

      - `placement: "before_template" | "after_template"`

        Enum representing the placement of the attached PDF.

        - `"before_template"`

        - `"after_template"`

    - `color?: boolean`

      Whether to print in color.

    - `description?: string`

      An optional description.

    - `doubleSided?: boolean`

      Whether to print on both sides of the paper.

    - `envelope?: string`

      The custom envelope ID or `"standard"`.

    - `envelopeType?: "standard_double_window" | "flat"`

      The type of envelope used for the letter.

      - `"standard_double_window"`

      - `"flat"`

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the letter.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the letter.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb" | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_letter_standard_white_70lb" | "premium_paper_letter_standard_white_80lb"`

        - `"standard"`

        - `"premium_paper_letter_standard_white_70lb"`

        - `"premium_paper_letter_standard_white_80lb"`

      - `(string & {})`

    - `perforatedPage?: 1`

      Which page number should be perforated (if any).

      - `1`

    - `returnEnvelope?: string`

      ID of a return envelope to include.

    - `size?: LetterSize`

      Enum representing the supported letter sizes.

      - `"us_letter"`

      - `"a4"`

    - `template?: string`

      ID of a template for the letter content. Cannot be used with `pdf`.

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `orderPreviewURL?: string`

    A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.

  - `postcard?: Postcard`

    Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `backTemplate?: string`

      ID of the template for the back side. Cannot be used with `pdf`.

    - `description?: string`

      An optional description.

    - `frontTemplate?: string`

      ID of the template for the front side. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the postcard.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the postcard.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `paper?: "standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more | (string & {})`

      Premium paper selection ("standard" or a premium paper ID). If omitted, org default is used when configured; otherwise "standard".

      - `"standard" | "premium_paper_heavy_1_glossy" | "premium_paper_postcard_uv_glossy_ss" | 2 more`

        - `"standard"`

        - `"premium_paper_heavy_1_glossy"`

        - `"premium_paper_postcard_uv_glossy_ss"`

        - `"premium_paper_postcard_uv_glossy_ss_120lb"`

        - `"premium_paper_postcard_satin_ds"`

      - `(string & {})`

    - `size?: "6x4" | "9x6" | "11x6"`

      Enum representing the supported postcard sizes.

      - `"6x4"`

      - `"9x6"`

      - `"11x6"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the campaign is in the `ready` status.

  - `selfMailer?: SelfMailer`

    Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the self-mailer.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the self-mailer.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold" | "8.5x11_trifold" | "9.5x16_trifold"`

      Enum representing the supported self-mailer sizes.

      - `"8.5x11_bifold"`

      - `"8.5x11_trifold"`

      - `"9.5x16_trifold"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

  - `sendDate?: string`

    The scheduled date and time for the campaign to be sent.

  - `snapPack?: SnapPack`

    Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

    - `description?: string`

      An optional description.

    - `insideTemplate?: string`

      ID of the template for the inside. Cannot be used with `pdf`.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Mailing class for the snap pack.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `mergeVariables?: Record<string, unknown>`

      Default merge variables for the snap pack.

    - `metadata?: Record<string, string>`

      Optional key-value metadata.

    - `outsideTemplate?: string`

      ID of the template for the outside. Cannot be used with `pdf`.

    - `size?: "8.5x11_bifold_v"`

      Enum representing the supported snap pack sizes.

      - `"8.5x11_bifold_v"`

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF, if any.

### Campaign Delete Response

- `CampaignDeleteResponse`

  - `id: string`

    A unique ID prefixed with campaign_

  - `deleted: true`

    - `true`

# Mailing List Imports

## Create Mailing List Import

`client.printMail.mailingListImports.create(MailingListImportCreateParamsparams, RequestOptionsoptions?): MailingListImportResponse`

**post** `/print-mail/v1/mailing_list_imports`

Create a new mailing list import.

Initiates the import process for a contact list file. The import enters the
`validating` status while contacts are processed and verified.

### Parameters

- `params: MailingListImportCreateParams`

  - `file: string`

    Body param: The CSV file for this import.

  - `fileType: FileType`

    Body param: Type of file supported for mailing list imports.

    - `"csv"`

  - `receiverAddressMapping: Record<string, string>`

    Body param: Mapping of columns for receiver addresses.

  - `description?: string`

    Body param: An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    Body param: See the section on Metadata.

  - `receiverMergeVariableMapping?: Record<string, string>`

    Body param: Optional mapping of columns for receiver merge variables.

  - `senderAddressMapping?: Record<string, string>`

    Body param: Optional mapping of columns for sender addresses.
    If this is present, then all receivers should have a corresponding sender.

  - `senderMergeVariableMapping?: Record<string, string>`

    Body param: Optional mapping of columns for sender merge variables.

  - `idempotencyKey?: string`

    Header param

### Returns

- `MailingListImportResponse`

  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<Error>`

    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" | "multiple_countries_error" | "invalid_contact_count_error" | "internal_service_error"`

      Type of error encountered during import processing.

      - `"no_valid_contacts_error"`

      - `"multiple_countries_error"`

      - `"invalid_contact_count_error"`

      - `"internal_service_error"`

  - `file: File`

    The file object your controller returns: all the mappings plus a signed URL.

    - `fileType: FileType`

      Type of file supported for mailing list imports.

      - `"csv"`

    - `receiverAddressMapping: Record<string, 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?: Record<string, string>`

      Optional mapping of columns for receiver merge variables.

    - `senderAddressMapping?: Record<string, string>`

      Optional mapping of columns for sender addresses.

    - `senderMergeVariableMapping?: Record<string, 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<Note>`

    Additional notes about the import process.

    - `message: string`

      A human-readable message describing the note.

    - `type: "truncated_test_file" | "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" | "completed" | "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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the import is completed.

  - `senderStatusCount?: VerificationStatusCount`

    Count of contact verification statuses.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const mailingListImportResponse = await client.printMail.mailingListImports.create({
  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',
  },
});

console.log(mailingListImportResponse.id);
```

#### Response

```json
{
  "id": "mailing_list_import_123",
  "live": false,
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:05:00Z",
  "status": "completed",
  "reportURL": "https://signed-report-url.csv",
  "errors": [],
  "notes": [],
  "validRowCount": 100,
  "invalidRowCount": 0,
  "receiverStatusCount": {
    "verifiedCount": 100,
    "correctedCount": 0,
    "failedCount": 0
  },
  "senderStatusCount": {
    "verifiedCount": 100,
    "correctedCount": 0,
    "failedCount": 0
  },
  "organization": "org_123",
  "file": {
    "fileType": "csv",
    "receiverAddressMapping": {
      "description": "Description",
      "firstName": "First Name",
      "lastName": "Last Name",
      "email": "Email",
      "addressLine1": "Address",
      "addressLine2": "Address Line 2",
      "city": "City",
      "postalOrZip": "Postal Code",
      "provinceOrState": "Province",
      "countryCode": "Country"
    },
    "url": "https://signed.url/import_123.csv"
  }
}
```

## List Mailing List Imports

`client.printMail.mailingListImports.list(MailingListImportListParamsquery?, RequestOptionsoptions?): SkipLimit<MailingListImportResponse>`

**get** `/print-mail/v1/mailing_list_imports`

Retrieve a list of mailing list imports.

Returns a paginated list of imports associated with the authenticated organization,
filterable by various parameters.

### Parameters

- `query: MailingListImportListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `MailingListImportResponse`

  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<Error>`

    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" | "multiple_countries_error" | "invalid_contact_count_error" | "internal_service_error"`

      Type of error encountered during import processing.

      - `"no_valid_contacts_error"`

      - `"multiple_countries_error"`

      - `"invalid_contact_count_error"`

      - `"internal_service_error"`

  - `file: File`

    The file object your controller returns: all the mappings plus a signed URL.

    - `fileType: FileType`

      Type of file supported for mailing list imports.

      - `"csv"`

    - `receiverAddressMapping: Record<string, 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?: Record<string, string>`

      Optional mapping of columns for receiver merge variables.

    - `senderAddressMapping?: Record<string, string>`

      Optional mapping of columns for sender addresses.

    - `senderMergeVariableMapping?: Record<string, 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<Note>`

    Additional notes about the import process.

    - `message: string`

      A human-readable message describing the note.

    - `type: "truncated_test_file" | "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" | "completed" | "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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the import is completed.

  - `senderStatusCount?: VerificationStatusCount`

    Count of contact verification statuses.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const mailingListImportResponse of client.printMail.mailingListImports.list()) {
  console.log(mailingListImportResponse.id);
}
```

#### Response

```json
{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "mailing_list_import_123",
      "live": false,
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:05:00Z",
      "status": "completed",
      "reportURL": "https://signed-report-url.csv",
      "errors": [],
      "notes": [],
      "validRowCount": 100,
      "invalidRowCount": 0,
      "receiverStatusCount": {
        "verifiedCount": 100,
        "correctedCount": 0,
        "failedCount": 0
      },
      "senderStatusCount": {
        "verifiedCount": 100,
        "correctedCount": 0,
        "failedCount": 0
      },
      "organization": "org_123",
      "file": {
        "fileType": "csv",
        "receiverAddressMapping": {
          "description": "Description",
          "firstName": "First Name",
          "lastName": "Last Name",
          "email": "Email",
          "addressLine1": "Address",
          "addressLine2": "Address Line 2",
          "city": "City",
          "postalOrZip": "Postal Code",
          "provinceOrState": "Province",
          "countryCode": "Country"
        },
        "url": "https://signed.url/import_123.csv"
      }
    }
  ]
}
```

## Update Mailing List Import

`client.printMail.mailingListImports.update(stringid, MailingListImportUpdateParamsbody, RequestOptionsoptions?): MailingListImportResponse`

**post** `/print-mail/v1/mailing_list_imports/{id}`

Update an existing mailing list import.

### Parameters

- `id: string`

- `body: MailingListImportUpdateParams`

  - `description?: string | null`

    An optional description for the import. Set to `null` to remove the existing description.

  - `metadata?: Record<string, string> | null`

    Optional key-value data associated with the import. Set to `null` to remove existing metadata.

### Returns

- `MailingListImportResponse`

  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<Error>`

    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" | "multiple_countries_error" | "invalid_contact_count_error" | "internal_service_error"`

      Type of error encountered during import processing.

      - `"no_valid_contacts_error"`

      - `"multiple_countries_error"`

      - `"invalid_contact_count_error"`

      - `"internal_service_error"`

  - `file: File`

    The file object your controller returns: all the mappings plus a signed URL.

    - `fileType: FileType`

      Type of file supported for mailing list imports.

      - `"csv"`

    - `receiverAddressMapping: Record<string, 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?: Record<string, string>`

      Optional mapping of columns for receiver merge variables.

    - `senderAddressMapping?: Record<string, string>`

      Optional mapping of columns for sender addresses.

    - `senderMergeVariableMapping?: Record<string, 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<Note>`

    Additional notes about the import process.

    - `message: string`

      A human-readable message describing the note.

    - `type: "truncated_test_file" | "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" | "completed" | "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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the import is completed.

  - `senderStatusCount?: VerificationStatusCount`

    Count of contact verification statuses.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const mailingListImportResponse = await client.printMail.mailingListImports.update('id', {
  description: 'Corrected description',
  metadata: { batch: 'spring_sale' },
});

console.log(mailingListImportResponse.id);
```

#### Response

```json
{
  "id": "mailing_list_import_123",
  "live": false,
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:05:00Z",
  "status": "completed",
  "reportURL": "https://signed-report-url.csv",
  "errors": [],
  "notes": [],
  "validRowCount": 100,
  "invalidRowCount": 0,
  "receiverStatusCount": {
    "verifiedCount": 100,
    "correctedCount": 0,
    "failedCount": 0
  },
  "senderStatusCount": {
    "verifiedCount": 100,
    "correctedCount": 0,
    "failedCount": 0
  },
  "organization": "org_123",
  "file": {
    "fileType": "csv",
    "receiverAddressMapping": {
      "description": "Description",
      "firstName": "First Name",
      "lastName": "Last Name",
      "email": "Email",
      "addressLine1": "Address",
      "addressLine2": "Address Line 2",
      "city": "City",
      "postalOrZip": "Postal Code",
      "provinceOrState": "Province",
      "countryCode": "Country"
    },
    "url": "https://signed.url/import_123.csv"
  }
}
```

## Get Mailing List Import

`client.printMail.mailingListImports.retrieve(stringid, RequestOptionsoptions?): MailingListImportResponse`

**get** `/print-mail/v1/mailing_list_imports/{id}`

Retrieve a specific mailing list import by its ID.

### Parameters

- `id: string`

### Returns

- `MailingListImportResponse`

  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<Error>`

    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" | "multiple_countries_error" | "invalid_contact_count_error" | "internal_service_error"`

      Type of error encountered during import processing.

      - `"no_valid_contacts_error"`

      - `"multiple_countries_error"`

      - `"invalid_contact_count_error"`

      - `"internal_service_error"`

  - `file: File`

    The file object your controller returns: all the mappings plus a signed URL.

    - `fileType: FileType`

      Type of file supported for mailing list imports.

      - `"csv"`

    - `receiverAddressMapping: Record<string, 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?: Record<string, string>`

      Optional mapping of columns for receiver merge variables.

    - `senderAddressMapping?: Record<string, string>`

      Optional mapping of columns for sender addresses.

    - `senderMergeVariableMapping?: Record<string, 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<Note>`

    Additional notes about the import process.

    - `message: string`

      A human-readable message describing the note.

    - `type: "truncated_test_file" | "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" | "completed" | "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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the import is completed.

  - `senderStatusCount?: VerificationStatusCount`

    Count of contact verification statuses.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const mailingListImportResponse = await client.printMail.mailingListImports.retrieve('id');

console.log(mailingListImportResponse.id);
```

#### Response

```json
{
  "id": "mailing_list_import_123",
  "live": false,
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:05:00Z",
  "status": "completed",
  "reportURL": "https://signed-report-url.csv",
  "errors": [],
  "notes": [],
  "validRowCount": 100,
  "invalidRowCount": 0,
  "receiverStatusCount": {
    "verifiedCount": 100,
    "correctedCount": 0,
    "failedCount": 0
  },
  "senderStatusCount": {
    "verifiedCount": 100,
    "correctedCount": 0,
    "failedCount": 0
  },
  "organization": "org_123",
  "file": {
    "fileType": "csv",
    "receiverAddressMapping": {
      "description": "Description",
      "firstName": "First Name",
      "lastName": "Last Name",
      "email": "Email",
      "addressLine1": "Address",
      "addressLine2": "Address Line 2",
      "city": "City",
      "postalOrZip": "Postal Code",
      "provinceOrState": "Province",
      "countryCode": "Country"
    },
    "url": "https://signed.url/import_123.csv"
  }
}
```

## Delete Mailing List Import

`client.printMail.mailingListImports.delete(stringid, RequestOptionsoptions?): MailingListImportDeleteResponse`

**delete** `/print-mail/v1/mailing_list_imports/{id}`

Delete a mailing list import.

This permanently deletes the import and its associated resources.
This operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `MailingListImportDeleteResponse`

  - `id: string`

    A unique ID prefixed with mailing_list_import_

  - `deleted: true`

    - `true`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const mailingListImport = await client.printMail.mailingListImports.delete('id');

console.log(mailingListImport.id);
```

#### 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`

  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<Error>`

    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" | "multiple_countries_error" | "invalid_contact_count_error" | "internal_service_error"`

      Type of error encountered during import processing.

      - `"no_valid_contacts_error"`

      - `"multiple_countries_error"`

      - `"invalid_contact_count_error"`

      - `"internal_service_error"`

  - `file: File`

    The file object your controller returns: all the mappings plus a signed URL.

    - `fileType: FileType`

      Type of file supported for mailing list imports.

      - `"csv"`

    - `receiverAddressMapping: Record<string, 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?: Record<string, string>`

      Optional mapping of columns for receiver merge variables.

    - `senderAddressMapping?: Record<string, string>`

      Optional mapping of columns for sender addresses.

    - `senderMergeVariableMapping?: Record<string, 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<Note>`

    Additional notes about the import process.

    - `message: string`

      A human-readable message describing the note.

    - `type: "truncated_test_file" | "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" | "completed" | "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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `reportURL?: string`

    A temporary URL to download the processing report, available once the import is completed.

  - `senderStatusCount?: VerificationStatusCount`

    Count of contact verification statuses.

### Verification Status Count

- `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.

### Mailing List Import Delete Response

- `MailingListImportDeleteResponse`

  - `id: string`

    A unique ID prefixed with mailing_list_import_

  - `deleted: true`

    - `true`

# Mailing Lists

## Create Mailing List

`client.printMail.mailingLists.create(MailingListCreateParamsparams, RequestOptionsoptions?): MailingList`

**post** `/print-mail/v1/mailing_lists`

Create a new mailing list.

### Parameters

- `params: MailingListCreateParams`

  - `description?: string`

    Body param: An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    Body param: See the section on Metadata.

  - `idempotencyKey?: string`

    Header param

### Returns

- `MailingList`

  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" | "removing_contacts" | "counting_recipient_country_codes" | "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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    A list of processing errors encountered, if any.

    - `message: string`

      A human-readable message describing the error.

    - `type: "mailing_list_imports_not_found_error" | "download_file_error" | "operational_error" | "internal_service_error"`

      Type of error encountered during mailing list processing.

      - `"mailing_list_imports_not_found_error"`

      - `"download_file_error"`

      - `"operational_error"`

      - `"internal_service_error"`

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const mailingList = await client.printMail.mailingLists.create({
  description: 'Test Mailing List',
  metadata: { campaign: 'launch' },
});

console.log(mailingList.id);
```

#### Response

```json
{
  "id": "mailing_list_123",
  "live": false,
  "description": "Test Mailing List",
  "metadata": {
    "campaign": "launch"
  },
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z",
  "status": "completed",
  "errors": []
}
```

## List Mailing Lists

`client.printMail.mailingLists.list(MailingListListParamsquery?, RequestOptionsoptions?): SkipLimit<MailingList>`

**get** `/print-mail/v1/mailing_lists`

Retrieve a list of mailing lists.

Returns a paginated list of mailing lists associated with the authenticated organization,
filterable by various parameters.

### Parameters

- `query: MailingListListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `MailingList`

  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" | "removing_contacts" | "counting_recipient_country_codes" | "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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    A list of processing errors encountered, if any.

    - `message: string`

      A human-readable message describing the error.

    - `type: "mailing_list_imports_not_found_error" | "download_file_error" | "operational_error" | "internal_service_error"`

      Type of error encountered during mailing list processing.

      - `"mailing_list_imports_not_found_error"`

      - `"download_file_error"`

      - `"operational_error"`

      - `"internal_service_error"`

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const mailingList of client.printMail.mailingLists.list()) {
  console.log(mailingList.id);
}
```

#### Response

```json
{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "mailing_list_123",
      "live": false,
      "description": "Test Mailing List",
      "metadata": {
        "campaign": "launch"
      },
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z",
      "status": "completed",
      "errors": []
    }
  ]
}
```

## Get Mailing List

`client.printMail.mailingLists.retrieve(stringid, RequestOptionsoptions?): MailingList`

**get** `/print-mail/v1/mailing_lists/{id}`

Retrieve a specific mailing list by its ID.

### Parameters

- `id: string`

### Returns

- `MailingList`

  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" | "removing_contacts" | "counting_recipient_country_codes" | "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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    A list of processing errors encountered, if any.

    - `message: string`

      A human-readable message describing the error.

    - `type: "mailing_list_imports_not_found_error" | "download_file_error" | "operational_error" | "internal_service_error"`

      Type of error encountered during mailing list processing.

      - `"mailing_list_imports_not_found_error"`

      - `"download_file_error"`

      - `"operational_error"`

      - `"internal_service_error"`

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const mailingList = await client.printMail.mailingLists.retrieve('id');

console.log(mailingList.id);
```

#### Response

```json
{
  "id": "mailing_list_123",
  "live": false,
  "description": "Test Mailing List",
  "metadata": {
    "campaign": "launch"
  },
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z",
  "status": "completed",
  "errors": []
}
```

## Update Mailing List

`client.printMail.mailingLists.update(stringid, MailingListUpdateParamsbody, RequestOptionsoptions?): MailingListUpdate`

**post** `/print-mail/v1/mailing_lists/{id}`

Update an existing mailing list.

### Parameters

- `id: string`

- `body: MailingListUpdateParams`

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Returns

- `MailingListUpdate`

  Parameters for updating an existing mailing list.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const mailingListUpdate = await client.printMail.mailingLists.update('id', {
  description: 'Updated Mailing List Description',
});

console.log(mailingListUpdate.description);
```

#### Response

```json
{
  "description": "Test Mailing List",
  "metadata": {
    "campaign": "launch"
  }
}
```

## Delete Mailing List

`client.printMail.mailingLists.delete(stringid, RequestOptionsoptions?): MailingListDeleteResponse`

**delete** `/print-mail/v1/mailing_lists/{id}`

Delete a mailing list.

This permanently deletes the mailing list and its associations.
This operation cannot be undone.

### Parameters

- `id: string`

### Returns

- `MailingListDeleteResponse`

  - `id: string`

    A unique ID prefixed with mailing_list_

  - `deleted: true`

    - `true`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const mailingList = await client.printMail.mailingLists.delete('id');

console.log(mailingList.id);
```

#### Response

```json
{
  "id": "mailing_list_sqF12lZ1VlBb",
  "deleted": true
}
```

## Submit a Mailing List Job

`client.printMail.mailingLists.jobs(stringid, MailingListJobsParamsbody, RequestOptionsoptions?): MailingList`

**post** `/print-mail/v1/mailing_lists/{id}/jobs`

Runs a mailing list job. Mailing list jobs allow you to add or remove contacts
to your mailing list from mailing list imports or directly with contact IDs.
Only one job can be ran at a time and jobs are only able to be ran while the
mailing list has a `status` of  "completed".

Once a job as successfully been kicked off, the mailing list will have a `status`
of either `creating_contacts` or `removing_contacts` depending on which job
was ran. After the job has finished, the mailing list will go back into the
`completed` state where more jobs can be ran. If there are any errors while
running a job, the `errors` field on the mailing list will contain a list of
error objects which describe the errors.

### Parameters

- `id: string`

- `body: MailingListJobsParams`

  - `addContacts?: Array<string>`

    List of contact IDs to add to the mailing list. Cannot be used with other operations.

  - `addMailingListImports?: Array<string>`

    List of mailing list import IDs to add to the mailing list. Cannot be used with other operations.

  - `removeContacts?: Array<string>`

    List of contact IDs to remove from the mailing list. Cannot be used with other operations.

  - `removeMailingListImports?: Array<string>`

    List of mailing list import IDs to remove from the mailing list. Cannot be used with other operations.

### Returns

- `MailingList`

  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" | "removing_contacts" | "counting_recipient_country_codes" | "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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    A list of processing errors encountered, if any.

    - `message: string`

      A human-readable message describing the error.

    - `type: "mailing_list_imports_not_found_error" | "download_file_error" | "operational_error" | "internal_service_error"`

      Type of error encountered during mailing list processing.

      - `"mailing_list_imports_not_found_error"`

      - `"download_file_error"`

      - `"operational_error"`

      - `"internal_service_error"`

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const mailingList = await client.printMail.mailingLists.jobs('id', {
  removeMailingListImports: ['mailing_list_import_123', 'mailing_list_import_456'],
});

console.log(mailingList.id);
```

#### Response

```json
{
  "id": "mailing_list_123",
  "live": false,
  "description": "Test Mailing List",
  "metadata": {
    "campaign": "launch"
  },
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z",
  "status": "completed",
  "errors": []
}
```

## Domain Types

### Mailing List

- `MailingList`

  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" | "removing_contacts" | "counting_recipient_country_codes" | "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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    A list of processing errors encountered, if any.

    - `message: string`

      A human-readable message describing the error.

    - `type: "mailing_list_imports_not_found_error" | "download_file_error" | "operational_error" | "internal_service_error"`

      Type of error encountered during mailing list processing.

      - `"mailing_list_imports_not_found_error"`

      - `"download_file_error"`

      - `"operational_error"`

      - `"internal_service_error"`

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Mailing List Update

- `MailingListUpdate`

  Parameters for updating an existing mailing list.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Mailing List Delete Response

- `MailingListDeleteResponse`

  - `id: string`

    A unique ID prefixed with mailing_list_

  - `deleted: true`

    - `true`

# Reports

## Create Saved Report

`client.printMail.reports.create(ReportCreateParamsbody, RequestOptionsoptions?): Report`

**post** `/print-mail/v1/reports`

Create a new saved report definition. Saved reports are SQL queries that can be executed later to generate
full exports or samples.

If you just want to do ad-hoc queries, you should use the `/reports/samples` endpoint.

### Parameters

- `body: ReportCreateParams`

  - `sqlQuery: string`

    The SQL query defining the report.

  - `description?: string`

    An optional user-friendly description for the report.

  - `metadata?: Record<string, string>`

    Optional key-value metadata associated with the report.

### Returns

- `Report`

  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?: string`

    An optional user-friendly description for the report.

  - `metadata?: Record<string, string>`

    Optional key-value metadata associated with the report.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const report = await client.printMail.reports.create({
  sqlQuery: 'SELECT id, status FROM orders WHERE created_at > ?',
  description: 'Recent Orders',
  metadata: { team: 'Sales' },
});

console.log(report.id);
```

#### Response

```json
{
  "id": "report_123",
  "object": "report",
  "live": false,
  "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
  "description": "Recent Orders",
  "metadata": {
    "team": "Sales"
  },
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z"
}
```

## Run Ad-hoc Query

`client.printMail.reports.sample(ReportSampleParamsbody, RequestOptionsoptions?): ReportSample`

**post** `/print-mail/v1/reports/samples`

Run an ad-hoc SQL query against your data lake and get a sample of the results.
This is useful for quickly testing queries without saving them as a report.
The query execution time and result size are limited.

### Parameters

- `body: ReportSampleParams`

  - `sqlQuery: string`

    The SQL query to execute for the sample.

  - `limit?: number`

    Maximum number of rows to return in the sample.

  - `params?: Array<string>`

    Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).

### Returns

- `ReportSample`

  Represents the result of a report sample query.

  - `id: string`

    Unique identifier for the sample query result.

  - `records: Array<Record<string, unknown>>`

    The actual data records returned by the sample query.

  - `report: string | null`

    The ID of the report this sample was generated from, or null for ad-hoc samples.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const reportSample = await client.printMail.reports.sample({
  sqlQuery: 'SELECT id FROM contacts LIMIT 5',
  limit: 5,
  params: [],
});

console.log(reportSample.id);
```

#### Response

```json
{
  "id": "sample_abc",
  "report": "report_123",
  "records": [
    {
      "id": "order_1"
    },
    {
      "id": "order_2"
    }
  ]
}
```

## Update Report

`client.printMail.reports.update(stringid, ReportUpdateParamsbody, RequestOptionsoptions?): Report`

**post** `/print-mail/v1/reports/{id}`

Update an existing saved report definition. You can change the query, description, or metadata.

### Parameters

- `id: string`

- `body: ReportUpdateParams`

  - `description?: string | null`

    An optional user-friendly description for the report. Set to null to remove.

  - `metadata?: Record<string, string> | null`

    Optional key-value metadata associated with the report. Set to null to remove.

  - `sqlQuery?: string`

    The SQL query defining the report.

### Returns

- `Report`

  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?: string`

    An optional user-friendly description for the report.

  - `metadata?: Record<string, string>`

    Optional key-value metadata associated with the report.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const report = await client.printMail.reports.update('id', {
  description: 'Recent Orders (Updated)',
});

console.log(report.id);
```

#### Response

```json
{
  "id": "report_123",
  "object": "report",
  "live": false,
  "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
  "description": "Recent Orders",
  "metadata": {
    "team": "Sales"
  },
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z"
}
```

## List Saved Reports

`client.printMail.reports.list(ReportListParamsquery?, RequestOptionsoptions?): SkipLimit<Report>`

**get** `/print-mail/v1/reports`

Retrieve a list of saved reports for your organization.

### Parameters

- `query: ReportListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `Report`

  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?: string`

    An optional user-friendly description for the report.

  - `metadata?: Record<string, string>`

    Optional key-value metadata associated with the report.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const report of client.printMail.reports.list()) {
  console.log(report.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "report_123",
      "object": "report",
      "live": false,
      "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
      "description": "Recent Orders",
      "metadata": {
        "team": "Sales"
      },
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```

## Retrieve Saved Report

`client.printMail.reports.retrieve(stringid, RequestOptionsoptions?): Report`

**get** `/print-mail/v1/reports/{id}`

Retrieve the details of a specific saved report by its ID.

### Parameters

- `id: string`

### Returns

- `Report`

  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?: string`

    An optional user-friendly description for the report.

  - `metadata?: Record<string, string>`

    Optional key-value metadata associated with the report.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const report = await client.printMail.reports.retrieve('id');

console.log(report.id);
```

#### Response

```json
{
  "id": "report_123",
  "object": "report",
  "live": false,
  "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
  "description": "Recent Orders",
  "metadata": {
    "team": "Sales"
  },
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z"
}
```

## Delete Saved Report

`client.printMail.reports.delete(stringid, RequestOptionsoptions?): DeletedResponse`

**delete** `/print-mail/v1/reports/{id}`

Delete a saved report definition. This action cannot be undone.
Associated exports are not automatically deleted.

### Parameters

- `id: string`

### Returns

- `DeletedResponse`

  Generic response for delete operations.

  - `id: string`

    The ID of the deleted resource.

  - `deleted: true`

    Indicates the resource was successfully deleted.

    - `true`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const deletedResponse = await client.printMail.reports.delete('id');

console.log(deletedResponse.id);
```

#### Response

```json
{
  "id": "report_123",
  "deleted": true
}
```

## Domain Types

### Deleted Response

- `DeletedResponse`

  Generic response for delete operations.

  - `id: string`

    The ID of the deleted resource.

  - `deleted: true`

    Indicates the resource was successfully deleted.

    - `true`

### Report

- `Report`

  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?: string`

    An optional user-friendly description for the report.

  - `metadata?: Record<string, string>`

    Optional key-value metadata associated with the report.

# Samples

## Sample a Saved Report

`client.printMail.reports.samples.create(stringid, SampleCreateParamsbody, RequestOptionsoptions?): ReportSample`

**post** `/print-mail/v1/reports/{id}/samples`

Run the query associated with a saved report and get a sample of the results.
This allows getting up to 1000 rows of resutls but the runtime of the query is limited to 30 seconds.
If you need more rows or longer runtime, you should create an export from this report.

### Parameters

- `id: string`

- `body: SampleCreateParams`

  - `limit?: number`

    Maximum number of rows to return in the sample.

  - `params?: Array<string>`

    Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).

### Returns

- `ReportSample`

  Represents the result of a report sample query.

  - `id: string`

    Unique identifier for the sample query result.

  - `records: Array<Record<string, unknown>>`

    The actual data records returned by the sample query.

  - `report: string | null`

    The ID of the report this sample was generated from, or null for ad-hoc samples.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const reportSample = await client.printMail.reports.samples.create('id', {
  limit: 10,
  params: ['2023-10-01T00:00:00Z'],
});

console.log(reportSample.id);
```

#### Response

```json
{
  "id": "sample_abc",
  "report": "report_123",
  "records": [
    {
      "id": "order_1"
    },
    {
      "id": "order_2"
    }
  ]
}
```

## Domain Types

### Report Sample

- `ReportSample`

  Represents the result of a report sample query.

  - `id: string`

    Unique identifier for the sample query result.

  - `records: Array<Record<string, unknown>>`

    The actual data records returned by the sample query.

  - `report: string | null`

    The ID of the report this sample was generated from, or null for ad-hoc samples.

### Report Sample Create Base

- `ReportSampleCreateBase`

  Base properties for creating a report sample.

  - `limit?: number`

    Maximum number of rows to return in the sample.

  - `params?: Array<string>`

    Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).

# Exports

## Create a Report Export

`client.printMail.reports.exports.create(stringreportID, ExportCreateParamsbody, RequestOptionsoptions?): ReportExport`

**post** `/print-mail/v1/reports/{reportID}/exports`

Create a new export job for a saved report. This runs the report's query
asynchronously and generates a downloadable CSV file with the full results.
Your queries can run for up to 13 minutes the resulting file can be up to 100mb large.

### Parameters

- `reportID: string`

- `body: ExportCreateParams`

  - `description?: string`

    An optional user-friendly description for the export.

  - `metadata?: Record<string, string>`

    Optional key-value metadata associated with the export.

  - `params?: Array<string>`

    Optional parameters to bind to the SQL query of the associated report.

### Returns

- `ReportExport`

  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: Report`

    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?: string`

    An optional user-friendly description for the export.

  - `failureMessage?: string`

    If export generation failed, this contains the error message.

  - `metadata?: Record<string, string>`

    Optional key-value metadata associated with the export.

  - `outputURL?: string`

    A signed URL to download the exported data (CSV format). Available when generation is complete and successful.

  - `params?: Array<string>`

    Optional parameters to bind to the SQL query of the associated report.

  - `rowCount?: number`

    The number of rows in the exported data.

  - `sizeInBytes?: number`

    The size of the generated export file in bytes.

  - `truncatedToBytes?: number`

    If the output was truncated, indicates the byte limit reached.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const reportExport = await client.printMail.reports.exports.create('reportID', {
  description: 'October Orders Export',
  params: ['2023-10-01T00:00:00Z'],
});

console.log(reportExport.id);
```

#### Response

```json
{
  "id": "report_export_123",
  "object": "report_export",
  "live": false,
  "report": {
    "id": "report_123",
    "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?"
  },
  "params": [
    "2023-10-01T00:00:00Z"
  ],
  "description": "October Orders Export",
  "outputURL": "https://s3.amazonaws.com/...",
  "sizeInBytes": 1024,
  "rowCount": 50,
  "createdAt": "2023-10-27T11:00:00Z",
  "updatedAt": "2023-10-27T11:05:00Z"
}
```

## Get Report Export

`client.printMail.reports.exports.retrieve(stringexportID, ExportRetrieveParamsparams, RequestOptionsoptions?): ReportExport`

**get** `/print-mail/v1/reports/{reportID}/exports/{exportID}`

Retrieve the status and details of a specific report export job.
Check the `outputURL` property for the download link once generation is complete.

### Parameters

- `exportID: string`

- `params: ExportRetrieveParams`

  - `reportID: string`

    The ID of the report the export belongs to.

### Returns

- `ReportExport`

  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: Report`

    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?: string`

    An optional user-friendly description for the export.

  - `failureMessage?: string`

    If export generation failed, this contains the error message.

  - `metadata?: Record<string, string>`

    Optional key-value metadata associated with the export.

  - `outputURL?: string`

    A signed URL to download the exported data (CSV format). Available when generation is complete and successful.

  - `params?: Array<string>`

    Optional parameters to bind to the SQL query of the associated report.

  - `rowCount?: number`

    The number of rows in the exported data.

  - `sizeInBytes?: number`

    The size of the generated export file in bytes.

  - `truncatedToBytes?: number`

    If the output was truncated, indicates the byte limit reached.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const reportExport = await client.printMail.reports.exports.retrieve('exportID', {
  reportID: 'reportID',
});

console.log(reportExport.id);
```

#### Response

```json
{
  "id": "report_export_123",
  "object": "report_export",
  "live": false,
  "report": {
    "id": "report_123",
    "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?"
  },
  "params": [
    "2023-10-01T00:00:00Z"
  ],
  "description": "October Orders Export",
  "outputURL": "https://s3.amazonaws.com/...",
  "sizeInBytes": 1024,
  "rowCount": 50,
  "createdAt": "2023-10-27T11:00:00Z",
  "updatedAt": "2023-10-27T11:05:00Z"
}
```

## Delete Report Export

`client.printMail.reports.exports.delete(stringexportID, ExportDeleteParamsparams, RequestOptionsoptions?): DeletedResponse`

**delete** `/print-mail/v1/reports/{reportID}/exports/{exportID}`

Delete a completed or failed report export job and its associated output file (if any).
This action cannot be undone. You cannot delete an export that is still generating.

### Parameters

- `exportID: string`

- `params: ExportDeleteParams`

  - `reportID: string`

    The ID of the report the export belongs to.

### Returns

- `DeletedResponse`

  Generic response for delete operations.

  - `id: string`

    The ID of the deleted resource.

  - `deleted: true`

    Indicates the resource was successfully deleted.

    - `true`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const deletedResponse = await client.printMail.reports.exports.delete('exportID', {
  reportID: 'reportID',
});

console.log(deletedResponse.id);
```

#### Response

```json
{
  "id": "report_export_123",
  "deleted": true
}
```

## Domain Types

### Report Export

- `ReportExport`

  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: Report`

    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?: string`

    An optional user-friendly description for the export.

  - `failureMessage?: string`

    If export generation failed, this contains the error message.

  - `metadata?: Record<string, string>`

    Optional key-value metadata associated with the export.

  - `outputURL?: string`

    A signed URL to download the exported data (CSV format). Available when generation is complete and successful.

  - `params?: Array<string>`

    Optional parameters to bind to the SQL query of the associated report.

  - `rowCount?: number`

    The number of rows in the exported data.

  - `sizeInBytes?: number`

    The size of the generated export file in bytes.

  - `truncatedToBytes?: number`

    If the output was truncated, indicates the byte limit reached.

# Sub Organizations

## Create a sub-organization.

`client.printMail.subOrganizations.create(SubOrganizationCreateParamsbody, RequestOptionsoptions?): SubOrganizationCreateResponse`

**post** `/print-mail/v1/sub_organizations`

When creating a user through the API, the verifiedEmail field will automatically be
set to true. However, if public signups are used, the email will need to be verified
by the user.

### Parameters

- `body: SubOrganizationCreateParams`

  - `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?: string`

    The phone number of the user to be created alongside the
    sub-organization.

### Returns

- `SubOrganizationCreateResponse`

  - `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: User`

    The user object.

    - `id: string`

      A unique ID prefixed with `user_`.

    - `apiKeys: Array<APIKey>`

      The user's API keys. Contains live and test mode API keys.

      - `value: string`

        The value of the API key.

      - `activeUntil?: 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<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?: EmailPreferences`

      A set of preferences for how a user should receive emails.

      - `orderPreviewSendPreference?: "do_not_send" | "send_live_only" | "send_live_and_test"`

        The list of preferences for receiving order preview emails.

        - `"do_not_send"`

        - `"send_live_only"`

        - `"send_live_and_test"`

    - `lastLoginTime?: string`

      The date and time at which the user last logged in.

    - `phoneNumber?: string`

      The phone number of the user.

    - `previousEmails?: Array<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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const subOrganization = await client.printMail.subOrganizations.create({
  countryCode: 'CA',
  email: 'suborg@postgrid.com',
  name: 'Calvin',
  organizationName: 'PostGrid',
  password: 'very-strong-password',
  phoneNumber: '9059059059',
});

console.log(subOrganization.subOrganization);
```

#### 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.

`client.printMail.subOrganizations.list(SubOrganizationListParamsquery?, RequestOptionsoptions?): SkipLimit<SubOrganization>`

**get** `/print-mail/v1/sub_organizations`

List sub-organizations.

### Parameters

- `query: SubOrganizationListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `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.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const subOrganization of client.printMail.subOrganizations.list()) {
  console.log(subOrganization.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "usage": 0,
      "limit": 500,
      "spend": 0,
      "name": "PostGrid",
      "countryCode": "CA",
      "id": "sub_org_abc123def456ghi6789",
      "object": "sub_org",
      "createdAt": "2020-11-12T23:23:47.974Z",
      "updatedAt": "2020-11-12T23:23:47.974Z"
    }
  ]
}
```

## Get a sub-organization.

`client.printMail.subOrganizations.retrieve(stringid, RequestOptionsoptions?): SubOrganization`

**get** `/print-mail/v1/sub_organizations/{id}`

Get a sub-organization.

### Parameters

- `id: string`

### Returns

- `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.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const subOrganization = await client.printMail.subOrganizations.retrieve('id');

console.log(subOrganization.id);
```

#### Response

```json
{
  "usage": 0,
  "limit": 500,
  "spend": 0,
  "name": "PostGrid",
  "countryCode": "CA",
  "id": "sub_org_abc123def456ghi6789",
  "object": "sub_org",
  "createdAt": "2020-11-12T23:23:47.974Z",
  "updatedAt": "2020-11-12T23:23:47.974Z"
}
```

## List users for a sub-organization.

`client.printMail.subOrganizations.retrieveUsers(stringid, SubOrganizationRetrieveUsersParamsquery?, RequestOptionsoptions?): SubOrganizationRetrieveUsersResponse`

**get** `/print-mail/v1/sub_organizations/{id}/users`

List users for a sub-organization.

### Parameters

- `id: string`

- `query: SubOrganizationRetrieveUsersParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `SubOrganizationRetrieveUsersResponse = Array<SubOrganizationRetrieveUsersResponseItem>`

  - `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<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?: EmailPreferences`

    A set of preferences for how a user should receive emails.

    - `orderPreviewSendPreference?: "do_not_send" | "send_live_only" | "send_live_and_test"`

      The list of preferences for receiving order preview emails.

      - `"do_not_send"`

      - `"send_live_only"`

      - `"send_live_and_test"`

  - `lastLoginTime?: string`

    The date and time at which the user last logged in.

  - `phoneNumber?: string`

    The phone number of the user.

  - `previousEmails?: Array<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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const response = await client.printMail.subOrganizations.retrieveUsers('id');

console.log(response);
```

#### Response

```json
[
  {
    "id": "user_abc123def456ghi6789",
    "pendingInvite": false,
    "organization": "org_abc123def456ghi6789",
    "email": "user@postgrid.com",
    "name": "Calvin",
    "verifiedEmail": true,
    "roles": [
      "role_abc123def456ghi6789"
    ]
  }
]
```

## Domain Types

### Email Preferences

- `EmailPreferences`

  A set of preferences for how a user should receive emails.

  - `orderPreviewSendPreference?: "do_not_send" | "send_live_only" | "send_live_and_test"`

    The list of preferences for receiving order preview emails.

    - `"do_not_send"`

    - `"send_live_only"`

    - `"send_live_and_test"`

### Sub Organization

- `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.

### Sub Organization Create Response

- `SubOrganizationCreateResponse`

  - `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: User`

    The user object.

    - `id: string`

      A unique ID prefixed with `user_`.

    - `apiKeys: Array<APIKey>`

      The user's API keys. Contains live and test mode API keys.

      - `value: string`

        The value of the API key.

      - `activeUntil?: 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<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?: EmailPreferences`

      A set of preferences for how a user should receive emails.

      - `orderPreviewSendPreference?: "do_not_send" | "send_live_only" | "send_live_and_test"`

        The list of preferences for receiving order preview emails.

        - `"do_not_send"`

        - `"send_live_only"`

        - `"send_live_and_test"`

    - `lastLoginTime?: string`

      The date and time at which the user last logged in.

    - `phoneNumber?: string`

      The phone number of the user.

    - `previousEmails?: Array<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<SubOrganizationRetrieveUsersResponseItem>`

  - `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<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?: EmailPreferences`

    A set of preferences for how a user should receive emails.

    - `orderPreviewSendPreference?: "do_not_send" | "send_live_only" | "send_live_and_test"`

      The list of preferences for receiving order preview emails.

      - `"do_not_send"`

      - `"send_live_only"`

      - `"send_live_and_test"`

  - `lastLoginTime?: string`

    The date and time at which the user last logged in.

  - `phoneNumber?: string`

    The phone number of the user.

  - `previousEmails?: Array<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

`client.printMail.boxes.create(BoxCreateParamsbody, RequestOptionsoptions?): BoxCreateResponse`

**post** `/print-mail/v1/boxes`

This endpoint allows you to create a box containing up to 100 cheques.
A Box is mailed to a single destination.

To create a box. You must specify:

- `to`: The recipient (contact or contact ID)
- `from`: The sender (contact or contact ID)
- `cheques`: An array of cheques to go in the box

For each cheque You must specify:

- `to`: The recipient (contact or contact ID)
- `from`: The sender (contact or contact ID)
- `bankAccount`: The bank account ID
- `amount`: The amount to be sent
- `number`: The cheque number

### Parameters

- `body: BoxCreateParams`

  - `cheques: Array<Cheque>`

    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 | ContactCreateWithCompanyName | string`

      - `ContactCreateWithFirstName`

        - `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?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `ContactCreateWithCompanyName`

        - `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?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `string`

    - `number: number`

      The cheque number.

    - `to: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

      - `ContactCreateWithFirstName`

      - `ContactCreateWithCompanyName`

      - `string`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: string`

      An optional message template to be printed on or with the cheque.

  - `from: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

    The 'from' (sender) of the entire box. Accepts inline ContactCreate or a contactID.

    - `ContactCreateWithFirstName`

    - `ContactCreateWithCompanyName`

    - `string`

  - `to: ContactCreateWithFirstName | ContactCreateWithCompanyName | 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`

    - `ContactCreateWithCompanyName`

    - `string`

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

    The mailing class of this order. If not provided, automatically set to `first_class`.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `mergeVariables?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `sendDate?: 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

- `BoxCreateResponse`

  - `id: string`

    A unique ID prefixed with box_

  - `cheques: Array<Cheque>`

    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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: boolean`

        If `true`, PostGrid will skip running this contact's address through our address verification system.

    - `number: number`

      The cheque number.

    - `to: Contact`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const box = await client.printMail.boxes.create({
  cheques: [
    {
      from: 'contact_456',
      to: 'contact_123',
      bankAccount: 'bank_abc',
      amount: 5000,
      number: 1042,
    },
  ],
  from: 'contact_456',
  to: 'contact_123',
});

console.log(box.id);
```

#### Response

```json
{
  "id": "box_123456",
  "object": "box",
  "description": "A sample box of cheques",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "cheques": [
    {
      "from": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "bankAccount": "bank_123",
      "amount": 12345,
      "memo": "Test Memo",
      "logoURL": "https://example.com/logo.png",
      "messageTemplate": "Thank you!",
      "number": 1001,
      "mergeVariables": {
        "customKey": "customValue"
      }
    }
  ],
  "mailingClass": "first_class",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2025-01-01T12:00:00Z",
  "updatedAt": "2025-01-02T12:00:00Z"
}
```

## List Boxes

`client.printMail.boxes.list(BoxListParamsquery?, RequestOptionsoptions?): SkipLimit<BoxListResponse>`

**get** `/print-mail/v1/boxes`

List all boxes.

### Parameters

- `query: BoxListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `BoxListResponse`

  - `id: string`

    A unique ID prefixed with box_

  - `cheques: Array<Cheque>`

    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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: boolean`

        If `true`, PostGrid will skip running this contact's address through our address verification system.

    - `number: number`

      The cheque number.

    - `to: Contact`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const boxListResponse of client.printMail.boxes.list()) {
  console.log(boxListResponse.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "box_123456",
      "object": "box",
      "description": "A sample box of cheques",
      "status": "ready",
      "live": false,
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "from": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "cheques": [
        {
          "from": {
            "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
            "object": "contact",
            "live": false,
            "companyName": "PostGrid",
            "addressLine1": "90 CANAL ST STE 600",
            "city": "BOSTON",
            "provinceOrState": "MA",
            "postalOrZip": "90210-1234",
            "countryCode": "US",
            "skipVerification": false,
            "forceVerifiedStatus": false,
            "addressStatus": "verified",
            "createdAt": "2022-02-16T15:08:41.052Z",
            "updatedAt": "2022-02-16T15:08:41.052Z"
          },
          "to": {
            "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
            "object": "contact",
            "live": false,
            "companyName": "PostGrid",
            "addressLine1": "90 CANAL ST STE 600",
            "city": "BOSTON",
            "provinceOrState": "MA",
            "postalOrZip": "90210-1234",
            "countryCode": "US",
            "skipVerification": false,
            "forceVerifiedStatus": false,
            "addressStatus": "verified",
            "createdAt": "2022-02-16T15:08:41.052Z",
            "updatedAt": "2022-02-16T15:08:41.052Z"
          },
          "bankAccount": "bank_123",
          "amount": 12345,
          "memo": "Test Memo",
          "logoURL": "https://example.com/logo.png",
          "messageTemplate": "Thank you!",
          "number": 1001,
          "mergeVariables": {
            "customKey": "customValue"
          }
        }
      ],
      "mailingClass": "first_class",
      "sendDate": "2020-11-12T23:23:47.974Z",
      "createdAt": "2025-01-01T12:00:00Z",
      "updatedAt": "2025-01-02T12:00:00Z"
    }
  ]
}
```

## Get Box

`client.printMail.boxes.retrieve(stringid, RequestOptionsoptions?): BoxRetrieveResponse`

**get** `/print-mail/v1/boxes/{id}`

Retrieve a box by ID.

### Parameters

- `id: string`

### Returns

- `BoxRetrieveResponse`

  - `id: string`

    A unique ID prefixed with box_

  - `cheques: Array<Cheque>`

    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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: boolean`

        If `true`, PostGrid will skip running this contact's address through our address verification system.

    - `number: number`

      The cheque number.

    - `to: Contact`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const box = await client.printMail.boxes.retrieve('id');

console.log(box.id);
```

#### Response

```json
{
  "id": "box_123456",
  "object": "box",
  "description": "A sample box of cheques",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "cheques": [
    {
      "from": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "bankAccount": "bank_123",
      "amount": 12345,
      "memo": "Test Memo",
      "logoURL": "https://example.com/logo.png",
      "messageTemplate": "Thank you!",
      "number": 1001,
      "mergeVariables": {
        "customKey": "customValue"
      }
    }
  ],
  "mailingClass": "first_class",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2025-01-01T12:00:00Z",
  "updatedAt": "2025-01-02T12:00:00Z"
}
```

## Cancel Box

`client.printMail.boxes.delete(stringid, RequestOptionsoptions?): BoxDeleteResponse`

**delete** `/print-mail/v1/boxes/{id}`

Cancel a box by ID (cannot be undone).

### Parameters

- `id: string`

### Returns

- `BoxDeleteResponse`

  - `id: string`

    A unique ID prefixed with box_

  - `cheques: Array<Cheque>`

    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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: boolean`

        If `true`, PostGrid will skip running this contact's address through our address verification system.

    - `number: number`

      The cheque number.

    - `to: Contact`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const box = await client.printMail.boxes.delete('id');

console.log(box.id);
```

#### Response

```json
{
  "id": "box_123456",
  "object": "box",
  "description": "A sample box of cheques",
  "status": "cancelled",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "cheques": [
    {
      "from": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "bankAccount": "bank_123",
      "amount": 12345,
      "memo": "Test Memo",
      "logoURL": "https://example.com/logo.png",
      "messageTemplate": "Thank you!",
      "number": 1001,
      "mergeVariables": {
        "customKey": "customValue"
      }
    }
  ],
  "mailingClass": "first_class",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2025-01-01T12:00:00Z",
  "updatedAt": "2025-01-02T12:00:00Z"
}
```

## Progress Status

`client.printMail.boxes.progressions(stringid, RequestOptionsoptions?): BoxProgressionsResponse`

**post** `/print-mail/v1/boxes/{id}/progressions`

Progresses a box's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.

Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.

### Parameters

- `id: string`

### Returns

- `BoxProgressionsResponse`

  - `id: string`

    A unique ID prefixed with box_

  - `cheques: Array<Cheque>`

    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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: boolean`

        If `true`, PostGrid will skip running this contact's address through our address verification system.

    - `number: number`

      The cheque number.

    - `to: Contact`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const response = await client.printMail.boxes.progressions('id');

console.log(response.id);
```

#### Response

```json
{
  "id": "box_123456",
  "object": "box",
  "description": "A sample box of cheques",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "cheques": [
    {
      "from": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "bankAccount": "bank_123",
      "amount": 12345,
      "memo": "Test Memo",
      "logoURL": "https://example.com/logo.png",
      "messageTemplate": "Thank you!",
      "number": 1001,
      "mergeVariables": {
        "customKey": "customValue"
      }
    }
  ],
  "mailingClass": "first_class",
  "sendDate": "2020-11-12T23:23:47.974Z",
  "createdAt": "2025-01-01T12:00:00Z",
  "updatedAt": "2025-01-02T12:00:00Z"
}
```

## Domain Types

### Box Create Response

- `BoxCreateResponse`

  - `id: string`

    A unique ID prefixed with box_

  - `cheques: Array<Cheque>`

    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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: boolean`

        If `true`, PostGrid will skip running this contact's address through our address verification system.

    - `number: number`

      The cheque number.

    - `to: Contact`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `url?: 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`

  - `id: string`

    A unique ID prefixed with box_

  - `cheques: Array<Cheque>`

    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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: boolean`

        If `true`, PostGrid will skip running this contact's address through our address verification system.

    - `number: number`

      The cheque number.

    - `to: Contact`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `url?: 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`

  - `id: string`

    A unique ID prefixed with box_

  - `cheques: Array<Cheque>`

    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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: boolean`

        If `true`, PostGrid will skip running this contact's address through our address verification system.

    - `number: number`

      The cheque number.

    - `to: Contact`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `url?: 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`

  - `id: string`

    A unique ID prefixed with box_

  - `cheques: Array<Cheque>`

    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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: boolean`

        If `true`, PostGrid will skip running this contact's address through our address verification system.

    - `number: number`

      The cheque number.

    - `to: Contact`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `url?: 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`

  - `id: string`

    A unique ID prefixed with box_

  - `cheques: Array<Cheque>`

    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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: boolean`

        If `true`, PostGrid will skip running this contact's address through our address verification system.

    - `number: number`

      The cheque number.

    - `to: Contact`

    - `logoURL?: string`

      A URL to a logo for the cheque (optional).

    - `memo?: string`

      The memo text on the cheque (optional).

    - `mergeVariables?: Record<string, unknown>`

      A set of dynamic merge variables for customizing the cheque or accompanying documents (optional).

    - `messageTemplate?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `url?: 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 Create Snap Pack

`client.printMail.snapPacks.create(SnapPackCreateParamsparams, RequestOptionsoptions?): SnapPackCreateResponse`

**post** `/print-mail/v1/snap_packs`

Create a snap pack. You can supply one of the following:

- HTML content for the inside and outside of the snap pack
- Template IDs for the inside and outside of the snap pack
- A URL for a two-page PDF that matches the snap pack layout Create a snap pack via a multipart/form-data request. Accepts the same
  fields as the JSON create body (nested objects are bracket-encoded form
  fields, e.g. `to[firstName]`); use this content type to upload the PDF
  file directly.

### Parameters

- `SnapPackCreateParams = SnapPackCreateWithHTML | SnapPackCreateWithTemplate | SnapPackCreateWithPdf`

  - `SnapPackCreateParamsBase`

    - `from: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

      Body param: The contact information of the sender. You can pass contact information inline here just like you can for the `to` contact.

      - `ContactCreateWithFirstName`

        - `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?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `ContactCreateWithCompanyName`

        - `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?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `string`

    - `insideHTML: string`

      Body param: The HTML content for the inside of the snap pack. You can supply _either_ this or `insideTemplate` but not both.

    - `outsideHTML: string`

      Body param: 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"`

      Body param: Enum representing the supported snap pack sizes.

      - `"8.5x11_bifold_v"`

    - `to: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

      Body param: 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`

      - `ContactCreateWithCompanyName`

      - `string`

    - `description?: string`

      Body param: An optional string describing this resource. Will be visible in the API and the dashboard.

    - `mailingClass?: "first_class" | "standard_class" | "express" | 23 more`

      Body param: 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?: Record<string, unknown>`

      Body param: 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?: Record<string, unknown>`

      Body param: See the section on Metadata.

    - `sendDate?: string`

      Body param: 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.

    - `idempotencyKey?: string`

      Header param

  - `SnapPackCreateWithHTML extends SnapPackCreateParamsBase`

  - `SnapPackCreateWithTemplate extends SnapPackCreateParamsBase`

  - `SnapPackCreateWithPdf extends SnapPackCreateParamsBase`

### Returns

- `SnapPackCreateResponse = SnapPack | SnapPack`

  - `SnapPack`

    - `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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

      The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

      See `OrderStatus` for more details on the status of this order.

      - `"ready"`

      - `"printing"`

      - `"processed_for_delivery"`

      - `"completed"`

      - `"cancelled"`

    - `to: Contact`

      The recipient of this order. This will be provided even if you delete the underlying contact.

    - `updatedAt: string`

      The UTC time at which this resource was last updated.

    - `cancellation?: Cancellation`

      The cancellation details of this order. Populated if the order has been cancelled.

      - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

        The reason for the cancellation.

        - `"user_initiated"`

        - `"invalid_content"`

        - `"invalid_order_mailing_class"`

      - `cancelledByUser?: string`

        The user ID who cancelled the order.

      - `note?: string`

        An optional note provided by the user who cancelled the order.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `imbDate?: string`

      The last date that the IMB status was updated. See `imbStatus` for more details.

    - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

      The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

      - `"entered_mail_stream"`

      - `"out_for_delivery"`

      - `"returned_to_sender"`

    - `imbZIPCode?: 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?: string`

      The HTML content for the inside of the snap pack, when provided instead of a template or PDF.

    - `insideTemplate?: string`

      The template ID for the inside of the snap pack, when provided instead of HTML or PDF.

    - `mergeVariables?: Record<string, 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?: Record<string, unknown>`

      See the section on Metadata.

    - `outsideHTML?: string`

      The HTML content for the outside of the snap pack, when provided instead of a template or PDF.

    - `outsideTemplate?: string`

      The template ID for the outside of the snap pack, when provided instead of HTML or PDF.

    - `trackingNumber?: string`

      The tracking number of this order. Populated after an express/certified order has been processed for delivery.

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.

    - `url?: 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.

  - `SnapPack`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const snapPack = await client.printMail.snapPacks.create({
  from: 'contact_123',
  insideHTML: '<html>Inside</html>',
  outsideHTML: '<html>Outside</html>',
  size: '8.5x11_bifold_v',
  to: 'contact_456',
});

console.log(snapPack);
```

#### Response

```json
{
  "id": "snap_pack_sqF12lZ1VlBb",
  "createdAt": "2019-12-27T18:11:19.117Z",
  "from": {
    "id": "contact_sqF12lZ1VlBb",
    "addressLine1": "addressLine1",
    "addressStatus": "verified",
    "countryCode": "countryCode",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "live": true,
    "object": "contact",
    "updatedAt": "2019-12-27T18:11:19.117Z",
    "addressErrors": "addressErrors",
    "addressLine2": "addressLine2",
    "city": "city",
    "companyName": "companyName",
    "description": "description",
    "email": "email",
    "firstName": "firstName",
    "forceVerifiedStatus": true,
    "jobTitle": "jobTitle",
    "lastName": "lastName",
    "metadata": {
      "foo": "bar"
    },
    "phoneNumber": "phoneNumber",
    "postalOrZip": "postalOrZip",
    "provinceOrState": "provinceOrState",
    "secret": true,
    "skipVerification": true
  },
  "live": true,
  "mailingClass": "first_class",
  "object": "snap_pack",
  "sendDate": "2019-12-27T18:11:19.117Z",
  "size": "8.5x11_bifold_v",
  "status": "ready",
  "to": {
    "id": "contact_sqF12lZ1VlBb",
    "addressLine1": "addressLine1",
    "addressStatus": "verified",
    "countryCode": "countryCode",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "live": true,
    "object": "contact",
    "updatedAt": "2019-12-27T18:11:19.117Z",
    "addressErrors": "addressErrors",
    "addressLine2": "addressLine2",
    "city": "city",
    "companyName": "companyName",
    "description": "description",
    "email": "email",
    "firstName": "firstName",
    "forceVerifiedStatus": true,
    "jobTitle": "jobTitle",
    "lastName": "lastName",
    "metadata": {
      "foo": "bar"
    },
    "phoneNumber": "phoneNumber",
    "postalOrZip": "postalOrZip",
    "provinceOrState": "provinceOrState",
    "secret": true,
    "skipVerification": true
  },
  "updatedAt": "2019-12-27T18:11:19.117Z",
  "cancellation": {
    "reason": "user_initiated",
    "cancelledByUser": "cancelledByUser",
    "note": "note"
  },
  "description": "description",
  "imbDate": "2019-12-27T18:11:19.117Z",
  "imbStatus": "entered_mail_stream",
  "imbZIPCode": "imbZIPCode",
  "insideHTML": "insideHTML",
  "insideTemplate": "insideTemplate",
  "mergeVariables": {
    "foo": "bar"
  },
  "metadata": {
    "foo": "bar"
  },
  "outsideHTML": "outsideHTML",
  "outsideTemplate": "outsideTemplate",
  "trackingNumber": "trackingNumber",
  "uploadedPDF": "https://example.com",
  "url": "https://example.com"
}
```

## List Snap Packs

`client.printMail.snapPacks.list(SnapPackListParamsquery?, RequestOptionsoptions?): SkipLimit<SnapPack>`

**get** `/print-mail/v1/snap_packs`

Get a list of snap packs.

### Parameters

- `query: SnapPackListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `SnapPack`

  - `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" | "corrected" | "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?: string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2?: string`

      Second line of the contact's address, if applicable.

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: string`

    The HTML content for the inside of the snap pack, when provided instead of a template or PDF.

  - `insideTemplate?: string`

    The template ID for the inside of the snap pack, when provided instead of HTML or PDF.

  - `mergeVariables?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `outsideHTML?: string`

    The HTML content for the outside of the snap pack, when provided instead of a template or PDF.

  - `outsideTemplate?: string`

    The template ID for the outside of the snap pack, when provided instead of HTML or PDF.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `uploadedPDF?: string`

    A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const snapPack of client.printMail.snapPacks.list()) {
  console.log(snapPack.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "snap_pack_123456",
      "object": "snap_pack",
      "status": "ready",
      "live": false,
      "to": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "from": {
        "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
        "object": "contact",
        "live": false,
        "companyName": "PostGrid",
        "addressLine1": "90 CANAL ST STE 600",
        "city": "BOSTON",
        "provinceOrState": "MA",
        "postalOrZip": "90210-1234",
        "countryCode": "US",
        "skipVerification": false,
        "forceVerifiedStatus": false,
        "addressStatus": "verified",
        "createdAt": "2022-02-16T15:08:41.052Z",
        "updatedAt": "2022-02-16T15:08:41.052Z"
      },
      "size": "8.5x11_bifold_v",
      "insideHTML": "<html>Inside</html>",
      "outsideHTML": "<html>Outside</html>",
      "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

`client.printMail.snapPacks.retrieveCapabilities(SnapPackRetrieveCapabilitiesParamsquery, RequestOptionsoptions?): SnapPackRetrieveCapabilitiesResponse`

**get** `/print-mail/v1/snap_packs/capabilities`

Provides sizes and mailing classes available for the destination.

### Parameters

- `query: SnapPackRetrieveCapabilitiesParams`

  - `returnCountryCode: string`

    The country code where mail may be returned to.

  - `destinationCountryCode?: 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?: string`

    Sources destination countries from the provided mailing list.
    One of `mailingList` or `destinationCountryCode` must be supplied but
    not both.

### Returns

- `SnapPackRetrieveCapabilitiesResponse`

  - `mailingClasses: Array<"first_class" | "standard_class" | "express" | 23 more>`

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `sizes: Array<"8.5x11_bifold_v">`

    - `"8.5x11_bifold_v"`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const response = await client.printMail.snapPacks.retrieveCapabilities({
  returnCountryCode: 'returnCountryCode',
});

console.log(response.mailingClasses);
```

#### Response

```json
{
  "sizes": [
    "8.5x11_bifold_v"
  ],
  "mailingClasses": [
    "express",
    "usps_express_2_day"
  ]
}
```

## Get Snap Pack

`client.printMail.snapPacks.retrieve(stringid, RequestOptionsoptions?): SnapPack`

**get** `/print-mail/v1/snap_packs/{id}`

Retrieve a snap pack by ID.

### Parameters

- `id: string`

### Returns

- `SnapPack`

  - `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" | "corrected" | "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?: string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2?: string`

      Second line of the contact's address, if applicable.

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: string`

    The HTML content for the inside of the snap pack, when provided instead of a template or PDF.

  - `insideTemplate?: string`

    The template ID for the inside of the snap pack, when provided instead of HTML or PDF.

  - `mergeVariables?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `outsideHTML?: string`

    The HTML content for the outside of the snap pack, when provided instead of a template or PDF.

  - `outsideTemplate?: string`

    The template ID for the outside of the snap pack, when provided instead of HTML or PDF.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `uploadedPDF?: string`

    A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const snapPack = await client.printMail.snapPacks.retrieve('id');

console.log(snapPack.id);
```

#### Response

```json
{
  "id": "snap_pack_123456",
  "object": "snap_pack",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "8.5x11_bifold_v",
  "insideHTML": "<html>Inside</html>",
  "outsideHTML": "<html>Outside</html>",
  "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

`client.printMail.snapPacks.delete(stringid, RequestOptionsoptions?): SnapPack`

**delete** `/print-mail/v1/snap_packs/{id}`

Cancel a snap pack by ID. Note that this operation cannot be undone and
that only snap packs with a status of `ready` can be cancelled.

### Parameters

- `id: string`

### Returns

- `SnapPack`

  - `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" | "corrected" | "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?: string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2?: string`

      Second line of the contact's address, if applicable.

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: string`

    The HTML content for the inside of the snap pack, when provided instead of a template or PDF.

  - `insideTemplate?: string`

    The template ID for the inside of the snap pack, when provided instead of HTML or PDF.

  - `mergeVariables?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `outsideHTML?: string`

    The HTML content for the outside of the snap pack, when provided instead of a template or PDF.

  - `outsideTemplate?: string`

    The template ID for the outside of the snap pack, when provided instead of HTML or PDF.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `uploadedPDF?: string`

    A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const snapPack = await client.printMail.snapPacks.delete('id');

console.log(snapPack.id);
```

#### Response

```json
{
  "id": "snap_pack_123456",
  "object": "snap_pack",
  "status": "cancelled",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "8.5x11_bifold_v",
  "insideHTML": "<html>Inside</html>",
  "outsideHTML": "<html>Outside</html>",
  "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

`client.printMail.snapPacks.progressions(stringid, RequestOptionsoptions?): SnapPack`

**post** `/print-mail/v1/snap_packs/{id}/progressions`

Progresses a snap pack's `status` to the next stage. This is only
available in test mode and can be used to simulate how a live order would
progress through the different statuses.

Note: this will fail with an `invalid_progression_error` if the status
is one of `completed` or `cancelled`.

### Parameters

- `id: string`

### Returns

- `SnapPack`

  - `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" | "corrected" | "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?: string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2?: string`

      Second line of the contact's address, if applicable.

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: string`

    The HTML content for the inside of the snap pack, when provided instead of a template or PDF.

  - `insideTemplate?: string`

    The template ID for the inside of the snap pack, when provided instead of HTML or PDF.

  - `mergeVariables?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `outsideHTML?: string`

    The HTML content for the outside of the snap pack, when provided instead of a template or PDF.

  - `outsideTemplate?: string`

    The template ID for the outside of the snap pack, when provided instead of HTML or PDF.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `uploadedPDF?: string`

    A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.

  - `url?: 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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const snapPack = await client.printMail.snapPacks.progressions('id');

console.log(snapPack.id);
```

#### Response

```json
{
  "id": "snap_pack_123456",
  "object": "snap_pack",
  "status": "ready",
  "live": false,
  "to": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "from": {
    "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
    "object": "contact",
    "live": false,
    "companyName": "PostGrid",
    "addressLine1": "90 CANAL ST STE 600",
    "city": "BOSTON",
    "provinceOrState": "MA",
    "postalOrZip": "90210-1234",
    "countryCode": "US",
    "skipVerification": false,
    "forceVerifiedStatus": false,
    "addressStatus": "verified",
    "createdAt": "2022-02-16T15:08:41.052Z",
    "updatedAt": "2022-02-16T15:08:41.052Z"
  },
  "size": "8.5x11_bifold_v",
  "insideHTML": "<html>Inside</html>",
  "outsideHTML": "<html>Outside</html>",
  "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

- `SnapPack`

  - `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" | "corrected" | "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?: string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2?: string`

      Second line of the contact's address, if applicable.

    - `city?: string`

      The city of the contact's address.

    - `companyName?: string`

      Company name of the contact.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email?: string`

      Email of the contact.

    - `firstName?: string`

      First name of the contact.

    - `forceVerifiedStatus?: boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle?: string`

      Job title of the contact.

    - `lastName?: string`

      Last name of the contact.

    - `metadata?: Record<string, unknown>`

      See the section on Metadata.

    - `phoneNumber?: string`

      Phone number of the contact.

    - `postalOrZip?: string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState?: string`

      Province or state of the contact's address.

    - `secret?: boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

    The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

    See `OrderStatus` for more details on the status of this order.

    - `"ready"`

    - `"printing"`

    - `"processed_for_delivery"`

    - `"completed"`

    - `"cancelled"`

  - `to: Contact`

    The recipient of this order. This will be provided even if you delete the underlying contact.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `cancellation?: Cancellation`

    The cancellation details of this order. Populated if the order has been cancelled.

    - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

      The reason for the cancellation.

      - `"user_initiated"`

      - `"invalid_content"`

      - `"invalid_order_mailing_class"`

    - `cancelledByUser?: string`

      The user ID who cancelled the order.

    - `note?: string`

      An optional note provided by the user who cancelled the order.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `imbDate?: string`

    The last date that the IMB status was updated. See `imbStatus` for more details.

  - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

    The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

    - `"entered_mail_stream"`

    - `"out_for_delivery"`

    - `"returned_to_sender"`

  - `imbZIPCode?: 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?: string`

    The HTML content for the inside of the snap pack, when provided instead of a template or PDF.

  - `insideTemplate?: string`

    The template ID for the inside of the snap pack, when provided instead of HTML or PDF.

  - `mergeVariables?: Record<string, 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?: Record<string, unknown>`

    See the section on Metadata.

  - `outsideHTML?: string`

    The HTML content for the outside of the snap pack, when provided instead of a template or PDF.

  - `outsideTemplate?: string`

    The template ID for the outside of the snap pack, when provided instead of HTML or PDF.

  - `trackingNumber?: string`

    The tracking number of this order. Populated after an express/certified order has been processed for delivery.

  - `uploadedPDF?: string`

    A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.

  - `url?: 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 Create Response

- `SnapPackCreateResponse = SnapPack | SnapPack`

  - `SnapPack`

    - `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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: 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" | "standard_class" | "express" | 23 more`

      The mailing class of this order. This determines the speed and cost of delivery. See `OrderMailingClass` for more details.

      - `"first_class"`

      - `"standard_class"`

      - `"express"`

      - `"certified"`

      - `"certified_return_receipt"`

      - `"registered"`

      - `"usps_first_class"`

      - `"usps_standard_class"`

      - `"usps_eddm"`

      - `"usps_express_2_day"`

      - `"usps_express_3_day"`

      - `"usps_first_class_certified"`

      - `"usps_first_class_certified_return_receipt"`

      - `"usps_first_class_registered"`

      - `"usps_express_3_day_signature_confirmation"`

      - `"usps_express_3_day_certified"`

      - `"usps_express_3_day_certified_return_receipt"`

      - `"ca_post_lettermail"`

      - `"ca_post_personalized"`

      - `"ca_post_neighbourhood_mail"`

      - `"ups_express_overnight"`

      - `"ups_express_2_day"`

      - `"ups_express_3_day"`

      - `"royal_mail_first_class"`

      - `"royal_mail_second_class"`

      - `"au_post_second_class"`

    - `object: "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" | "printing" | "processed_for_delivery" | 2 more`

      See `OrderStatus` for more details on the status of this order.

      - `"ready"`

      - `"printing"`

      - `"processed_for_delivery"`

      - `"completed"`

      - `"cancelled"`

    - `to: Contact`

      The recipient of this order. This will be provided even if you delete the underlying contact.

    - `updatedAt: string`

      The UTC time at which this resource was last updated.

    - `cancellation?: Cancellation`

      The cancellation details of this order. Populated if the order has been cancelled.

      - `reason: "user_initiated" | "invalid_content" | "invalid_order_mailing_class"`

        The reason for the cancellation.

        - `"user_initiated"`

        - `"invalid_content"`

        - `"invalid_order_mailing_class"`

      - `cancelledByUser?: string`

        The user ID who cancelled the order.

      - `note?: string`

        An optional note provided by the user who cancelled the order.

    - `description?: string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `imbDate?: string`

      The last date that the IMB status was updated. See `imbStatus` for more details.

    - `imbStatus?: "entered_mail_stream" | "out_for_delivery" | "returned_to_sender"`

      The Intelligent Mail Barcode (IMB) status of this order. Only populated for US-printed and US-destined orders. This is the most detailed way to track non-express/certified orders.

      - `"entered_mail_stream"`

      - `"out_for_delivery"`

      - `"returned_to_sender"`

    - `imbZIPCode?: 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?: string`

      The HTML content for the inside of the snap pack, when provided instead of a template or PDF.

    - `insideTemplate?: string`

      The template ID for the inside of the snap pack, when provided instead of HTML or PDF.

    - `mergeVariables?: Record<string, 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?: Record<string, unknown>`

      See the section on Metadata.

    - `outsideHTML?: string`

      The HTML content for the outside of the snap pack, when provided instead of a template or PDF.

    - `outsideTemplate?: string`

      The template ID for the outside of the snap pack, when provided instead of HTML or PDF.

    - `trackingNumber?: string`

      The tracking number of this order. Populated after an express/certified order has been processed for delivery.

    - `uploadedPDF?: string`

      A signed URL to the uploaded PDF provided at creation time, if a PDF was supplied.

    - `url?: 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.

  - `SnapPack`

### Snap Pack Retrieve Capabilities Response

- `SnapPackRetrieveCapabilitiesResponse`

  - `mailingClasses: Array<"first_class" | "standard_class" | "express" | 23 more>`

    - `"first_class"`

    - `"standard_class"`

    - `"express"`

    - `"certified"`

    - `"certified_return_receipt"`

    - `"registered"`

    - `"usps_first_class"`

    - `"usps_standard_class"`

    - `"usps_eddm"`

    - `"usps_express_2_day"`

    - `"usps_express_3_day"`

    - `"usps_first_class_certified"`

    - `"usps_first_class_certified_return_receipt"`

    - `"usps_first_class_registered"`

    - `"usps_express_3_day_signature_confirmation"`

    - `"usps_express_3_day_certified"`

    - `"usps_express_3_day_certified_return_receipt"`

    - `"ca_post_lettermail"`

    - `"ca_post_personalized"`

    - `"ca_post_neighbourhood_mail"`

    - `"ups_express_overnight"`

    - `"ups_express_2_day"`

    - `"ups_express_3_day"`

    - `"royal_mail_first_class"`

    - `"royal_mail_second_class"`

    - `"au_post_second_class"`

  - `sizes: Array<"8.5x11_bifold_v">`

    - `"8.5x11_bifold_v"`

# Targeted List Builds

## Create Targeted List Build

`client.printMail.targetedListBuilds.create(TargetedListBuildCreateParamsparams, RequestOptionsoptions?): TargetedListBuildCreateResponse`

**post** `/print-mail/v1/targeted_list_builds`

Create a new targeted list build. A quote will be generated
asynchronously based on the provided filters.

### Parameters

- `params: TargetedListBuildCreateParams`

  - `description?: string`

    Body param: An optional string describing this resource. Will be visible in the API and the dashboard.

  - `limit?: number`

    Body param: Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `metadata?: Record<string, unknown>`

    Body param: See the section on Metadata.

  - `usCompanies?: UsCompanies`

    Body param: Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Body param: 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?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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.

  - `idempotencyKey?: string`

    Header param

### Returns

- `TargetedListBuildCreateResponse`

  A targeted list build represents a request to build a new mailing list by
  targeting US consumers or companies matching the provided filters. Once
  created, a quote is generated asynchronously. After reviewing the quote
  and preview records, you may confirm the build, which kicks off the
  creation of the underlying mailing list.

  - `id: 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" | "quote_ready" | "creating_list" | 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?: number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt?: string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt?: string`

    The UTC time at which the build was confirmed, if any.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "insufficient_credits" | "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList?: string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `previewRecords?: Array<PreviewRecord>`

    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?: Quote`

    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?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const targetedListBuild = await client.printMail.targetedListBuilds.create({
  description: 'Q1 prospecting list',
  limit: 1000,
  metadata: { campaign: 'q1_prospecting' },
  usCompanies: {
    postalCodes: ['10001', '10002'],
    industries: ['software'],
    employeeCount: [10, 500],
  },
});

console.log(targetedListBuild.id);
```

#### Response

```json
{
  "id": "targeted_list_build_123",
  "live": false,
  "description": "Q1 prospecting list",
  "metadata": {
    "campaign": "q1_prospecting"
  },
  "createdAt": "2026-01-05T10:00:00Z",
  "updatedAt": "2026-01-05T10:01:30Z",
  "organization": "organization_123",
  "status": "quote_ready",
  "usCompanies": {
    "postalCodes": [
      "10001",
      "10002"
    ],
    "industries": [
      "software"
    ],
    "employeeCount": [
      10,
      500
    ]
  },
  "limit": 1000,
  "quote": {
    "generatedAt": "2026-01-05T10:01:30Z",
    "count": 1000,
    "pricePerContactCents": 11.98
  },
  "previewRecords": [
    {
      "name": "Acm***",
      "formattedAddress": "12** Main St, New York, NY, 100**"
    }
  ],
  "errors": []
}
```

## List Targeted List Builds

`client.printMail.targetedListBuilds.list(TargetedListBuildListParamsquery?, RequestOptionsoptions?): SkipLimit<TargetedListBuildListResponse>`

**get** `/print-mail/v1/targeted_list_builds`

Retrieve a paginated list of targeted list builds for the authenticated
organization, ordered from most recently updated to least recently
updated.

### Parameters

- `query: TargetedListBuildListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `TargetedListBuildListResponse`

  A targeted list build represents a request to build a new mailing list by
  targeting US consumers or companies matching the provided filters. Once
  created, a quote is generated asynchronously. After reviewing the quote
  and preview records, you may confirm the build, which kicks off the
  creation of the underlying mailing list.

  - `id: 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" | "quote_ready" | "creating_list" | 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?: number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt?: string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt?: string`

    The UTC time at which the build was confirmed, if any.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "insufficient_credits" | "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList?: string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `previewRecords?: Array<PreviewRecord>`

    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?: Quote`

    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?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const targetedListBuildListResponse of client.printMail.targetedListBuilds.list()) {
  console.log(targetedListBuildListResponse.id);
}
```

#### Response

```json
{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "targeted_list_build_123",
      "live": false,
      "description": "Q1 prospecting list",
      "metadata": {
        "campaign": "q1_prospecting"
      },
      "createdAt": "2026-01-05T10:00:00Z",
      "updatedAt": "2026-01-05T10:01:30Z",
      "organization": "organization_123",
      "status": "quote_ready",
      "usCompanies": {
        "postalCodes": [
          "10001",
          "10002"
        ],
        "industries": [
          "software"
        ],
        "employeeCount": [
          10,
          500
        ]
      },
      "limit": 1000,
      "quote": {
        "generatedAt": "2026-01-05T10:01:30Z",
        "count": 1000,
        "pricePerContactCents": 11.98
      },
      "previewRecords": [
        {
          "name": "Acm***",
          "formattedAddress": "12** Main St, New York, NY, 100**"
        }
      ],
      "errors": []
    }
  ]
}
```

## Get Targeted List Build

`client.printMail.targetedListBuilds.retrieve(stringid, RequestOptionsoptions?): TargetedListBuildRetrieveResponse`

**get** `/print-mail/v1/targeted_list_builds/{id}`

Retrieve a specific targeted list build by its ID.

### Parameters

- `id: string`

### Returns

- `TargetedListBuildRetrieveResponse`

  A targeted list build represents a request to build a new mailing list by
  targeting US consumers or companies matching the provided filters. Once
  created, a quote is generated asynchronously. After reviewing the quote
  and preview records, you may confirm the build, which kicks off the
  creation of the underlying mailing list.

  - `id: 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" | "quote_ready" | "creating_list" | 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?: number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt?: string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt?: string`

    The UTC time at which the build was confirmed, if any.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "insufficient_credits" | "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList?: string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `previewRecords?: Array<PreviewRecord>`

    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?: Quote`

    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?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const targetedListBuild = await client.printMail.targetedListBuilds.retrieve('id');

console.log(targetedListBuild.id);
```

#### Response

```json
{
  "id": "targeted_list_build_123",
  "live": false,
  "description": "Q1 prospecting list",
  "metadata": {
    "campaign": "q1_prospecting"
  },
  "createdAt": "2026-01-05T10:00:00Z",
  "updatedAt": "2026-01-05T10:01:30Z",
  "organization": "organization_123",
  "status": "quote_ready",
  "usCompanies": {
    "postalCodes": [
      "10001",
      "10002"
    ],
    "industries": [
      "software"
    ],
    "employeeCount": [
      10,
      500
    ]
  },
  "limit": 1000,
  "quote": {
    "generatedAt": "2026-01-05T10:01:30Z",
    "count": 1000,
    "pricePerContactCents": 11.98
  },
  "previewRecords": [
    {
      "name": "Acm***",
      "formattedAddress": "12** Main St, New York, NY, 100**"
    }
  ],
  "errors": []
}
```

## Update Targeted List Build

`client.printMail.targetedListBuilds.update(stringid, TargetedListBuildUpdateParamsbody, RequestOptionsoptions?): TargetedListBuildUpdateResponse`

**post** `/print-mail/v1/targeted_list_builds/{id}`

Update an existing targeted list build. Only builds that have not yet
been confirmed may be updated. Updating the filters or `limit` will
reset the build's status back to `generating_quote` and a new quote
will be generated.

### Parameters

- `id: string`

- `body: TargetedListBuildUpdateParams`

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `usCompanies?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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

- `TargetedListBuildUpdateResponse`

  A targeted list build represents a request to build a new mailing list by
  targeting US consumers or companies matching the provided filters. Once
  created, a quote is generated asynchronously. After reviewing the quote
  and preview records, you may confirm the build, which kicks off the
  creation of the underlying mailing list.

  - `id: 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" | "quote_ready" | "creating_list" | 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?: number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt?: string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt?: string`

    The UTC time at which the build was confirmed, if any.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "insufficient_credits" | "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList?: string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `previewRecords?: Array<PreviewRecord>`

    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?: Quote`

    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?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const targetedListBuild = await client.printMail.targetedListBuilds.update('id', {
  limit: 2000,
  usCompanies: {
    postalCodes: ['10001', '10002', '10003'],
    industries: ['software', 'fintech'],
    employeeCount: [50, 1000],
  },
});

console.log(targetedListBuild.id);
```

#### Response

```json
{
  "id": "targeted_list_build_123",
  "live": false,
  "description": "Q1 prospecting list",
  "metadata": {
    "campaign": "q1_prospecting"
  },
  "createdAt": "2026-01-05T10:00:00Z",
  "updatedAt": "2026-01-05T10:01:30Z",
  "organization": "organization_123",
  "status": "quote_ready",
  "usCompanies": {
    "postalCodes": [
      "10001",
      "10002"
    ],
    "industries": [
      "software"
    ],
    "employeeCount": [
      10,
      500
    ]
  },
  "limit": 1000,
  "quote": {
    "generatedAt": "2026-01-05T10:01:30Z",
    "count": 1000,
    "pricePerContactCents": 11.98
  },
  "previewRecords": [
    {
      "name": "Acm***",
      "formattedAddress": "12** Main St, New York, NY, 100**"
    }
  ],
  "errors": []
}
```

## Delete Targeted List Build

`client.printMail.targetedListBuilds.delete(stringid, RequestOptionsoptions?): TargetedListBuildDeleteResponse`

**delete** `/print-mail/v1/targeted_list_builds/{id}`

Delete a targeted list build. List builds can only be deleted before
they have been confirmed — once a build has transitioned to
`creating_list` or `completed` it cannot be deleted.

### Parameters

- `id: string`

### Returns

- `TargetedListBuildDeleteResponse`

  - `id: string`

    A unique ID prefixed with targeted_list_build_

  - `deleted: true`

    - `true`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const targetedListBuild = await client.printMail.targetedListBuilds.delete('id');

console.log(targetedListBuild.id);
```

#### Response

```json
{
  "id": "targeted_list_build_123",
  "deleted": true
}
```

## Confirm Targeted List Build

`client.printMail.targetedListBuilds.confirm(stringid, RequestOptionsoptions?): TargetedListBuildConfirmResponse`

**post** `/print-mail/v1/targeted_list_builds/{id}/confirm`

Confirm a targeted list build whose quote is ready. This deducts the
appropriate amount of list build credits from the organization (in
live mode) and kicks off the asynchronous creation of the underlying
mailing list.

### Parameters

- `id: string`

### Returns

- `TargetedListBuildConfirmResponse`

  A targeted list build represents a request to build a new mailing list by
  targeting US consumers or companies matching the provided filters. Once
  created, a quote is generated asynchronously. After reviewing the quote
  and preview records, you may confirm the build, which kicks off the
  creation of the underlying mailing list.

  - `id: 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" | "quote_ready" | "creating_list" | 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?: number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt?: string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt?: string`

    The UTC time at which the build was confirmed, if any.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "insufficient_credits" | "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList?: string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `previewRecords?: Array<PreviewRecord>`

    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?: Quote`

    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?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const response = await client.printMail.targetedListBuilds.confirm('id');

console.log(response.id);
```

#### Response

```json
{
  "id": "targeted_list_build_123",
  "live": false,
  "description": "Q1 prospecting list",
  "metadata": {
    "campaign": "q1_prospecting"
  },
  "createdAt": "2026-01-05T10:00:00Z",
  "updatedAt": "2026-01-05T10:05:00Z",
  "organization": "organization_123",
  "status": "creating_list",
  "usCompanies": {
    "postalCodes": [
      "10001",
      "10002"
    ],
    "industries": [
      "software"
    ],
    "employeeCount": [
      10,
      500
    ]
  },
  "limit": 1000,
  "quote": {
    "generatedAt": "2026-01-05T10:01:30Z",
    "count": 1000,
    "pricePerContactCents": 11.98
  },
  "confirmedAt": "2026-01-05T10:05:00Z",
  "buildProgressPercent": 0,
  "errors": []
}
```

## Domain Types

### Targeted List Build Create Response

- `TargetedListBuildCreateResponse`

  A targeted list build represents a request to build a new mailing list by
  targeting US consumers or companies matching the provided filters. Once
  created, a quote is generated asynchronously. After reviewing the quote
  and preview records, you may confirm the build, which kicks off the
  creation of the underlying mailing list.

  - `id: 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" | "quote_ready" | "creating_list" | 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?: number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt?: string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt?: string`

    The UTC time at which the build was confirmed, if any.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "insufficient_credits" | "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList?: string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `previewRecords?: Array<PreviewRecord>`

    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?: Quote`

    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?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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`

  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" | "quote_ready" | "creating_list" | 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?: number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt?: string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt?: string`

    The UTC time at which the build was confirmed, if any.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "insufficient_credits" | "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList?: string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `previewRecords?: Array<PreviewRecord>`

    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?: Quote`

    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?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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`

  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" | "quote_ready" | "creating_list" | 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?: number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt?: string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt?: string`

    The UTC time at which the build was confirmed, if any.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "insufficient_credits" | "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList?: string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `previewRecords?: Array<PreviewRecord>`

    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?: Quote`

    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?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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`

  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" | "quote_ready" | "creating_list" | 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?: number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt?: string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt?: string`

    The UTC time at which the build was confirmed, if any.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "insufficient_credits" | "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList?: string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `previewRecords?: Array<PreviewRecord>`

    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?: Quote`

    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?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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`

  - `id: string`

    A unique ID prefixed with targeted_list_build_

  - `deleted: true`

    - `true`

### Targeted List Build Confirm Response

- `TargetedListBuildConfirmResponse`

  A targeted list build represents a request to build a new mailing list by
  targeting US consumers or companies matching the provided filters. Once
  created, a quote is generated asynchronously. After reviewing the quote
  and preview records, you may confirm the build, which kicks off the
  creation of the underlying mailing list.

  - `id: 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" | "quote_ready" | "creating_list" | 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?: number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt?: string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt?: string`

    The UTC time at which the build was confirmed, if any.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors?: Array<Error>`

    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" | "insufficient_credits" | "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit?: number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList?: string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

  - `previewRecords?: Array<PreviewRecord>`

    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?: Quote`

    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?: UsCompanies`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: Array<string>`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes?: Array<"public" | "private" | "educational" | 3 more>`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount?: Array<number>`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear?: Array<number>`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries?: Array<string>`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes?: Array<string>`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags?: Array<string>`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers?: UsConsumers`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange?: Array<number>`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates?: Array<string>`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels?: Array<"high_school" | "college" | "grad_school" | "vocational_training">`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender?: "male" | "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange?: Array<number>`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange?: Array<number>`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange?: Array<number>`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations?: Array<"professional_technical" | "administration_management" | "sales_service" | 23 more>`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes?: Array<string>`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround?: ZipCodesAround`

      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

`client.printMail.targetedListBuilds.filters.autocomplete(FilterAutocompleteParamsbody, RequestOptionsoptions?): FilterAutocompleteResponse`

**post** `/print-mail/v1/targeted_list_builds/filters/autocomplete`

Return a list of autocomplete suggestions for a given filter field
(currently only `industry` is supported). Useful when building a UI
around the `industries` company filter.

### Parameters

- `body: FilterAutocompleteParams`

  - `field: "industry"`

    A field that can be autocompleted when configuring list build filters.

    - `"industry"`

  - `size?: number`

    Maximum number of suggestions to return. Between 1 and 100.
    Defaults to 25 if omitted.

  - `text?: string`

    Optional text prefix to narrow the autocomplete suggestions.

### Returns

- `FilterAutocompleteResponse`

  The list of suggestions returned by an autocomplete query.

  - `data: Array<Data>`

    - `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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const response = await client.printMail.targetedListBuilds.filters.autocomplete({
  field: 'industry',
  size: 5,
  text: 'soft',
});

console.log(response.data);
```

#### Response

```json
{
  "object": "list",
  "data": [
    {
      "value": "software",
      "type": "industry"
    },
    {
      "value": "software development",
      "type": "industry"
    }
  ]
}
```

## Domain Types

### Filter Autocomplete Response

- `FilterAutocompleteResponse`

  The list of suggestions returned by an autocomplete query.

  - `data: Array<Data>`

    - `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

`client.printMail.templateEditorSessions.create(TemplateEditorSessionCreateParamsbody, RequestOptionsoptions?): TemplateEditorSessionCreateResponse`

**post** `/print-mail/v1/template_editor_sessions`

Create a Template Editor Session.

Note that if no `backURL` is supplied, PostGrid removes the Back button
from the editor page. This is ideal for when you `iframe` the editor.

### Parameters

- `body: TemplateEditorSessionCreateParams`

  - `template: string`

    ID of the underlying template that this edits.

  - `backURL?: string`

    The URL supplied when this editor session was created.

  - `styles?: Styles`

    Style overrides for the template editor session.

    - `canvas?: Canvas`

      Style overrides for the template editor canvas.

      - `backgroundColor?: string`

        The canvas background color.

    - `panelText?: PanelText`

      Style overrides for template editor panel text.

      - `color?: string`

        The panel text color.

    - `saveButton?: SaveButton`

      Style overrides for the template editor save button.

      - `backgroundColor?: string`

        The save button background color.

      - `textColor?: string`

        The save button text color.

  - `title?: string`

    The title supplied when this editor session was created.

  - `trackers?: "all" | "none" | Array<string>`

    Controls which Trackers are displayed in the template editor session.

    - `"all" | "none"`

      - `"all"`

      - `"none"`

    - `Array<string>`

### Returns

- `TemplateEditorSessionCreateResponse`

  - `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?: string`

    The URL supplied when this editor session was created.

  - `styles?: Styles`

    Style overrides for the template editor session.

    - `canvas?: Canvas`

      Style overrides for the template editor canvas.

      - `backgroundColor?: string`

        The canvas background color.

    - `panelText?: PanelText`

      Style overrides for template editor panel text.

      - `color?: string`

        The panel text color.

    - `saveButton?: SaveButton`

      Style overrides for the template editor save button.

      - `backgroundColor?: string`

        The save button background color.

      - `textColor?: string`

        The save button text color.

  - `title?: string`

    The title supplied when this editor session was created.

  - `trackers?: "all" | "none" | Array<string>`

    Controls which Trackers are displayed in the template editor session.

    - `"all" | "none"`

      - `"all"`

      - `"none"`

    - `Array<string>`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const templateEditorSession = await client.printMail.templateEditorSessions.create({
  template: 'template_eYxcbMKPZEZPk71ZJPA6Yz',
  backURL: 'https://postgrid.com',
  title: 'My Editor Session',
  trackers: ['tracker_123456789abcdefghijklmnopqrstuvwxyz'],
});

console.log(templateEditorSession.id);
```

#### Response

```json
{
  "id": "template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c",
  "object": "template_editor_session",
  "live": false,
  "template": "template_eYxcbMKPZEZPk71ZJPA6Yz",
  "backURL": "https://postgrid.com",
  "title": "My Editor Session",
  "trackers": [
    "tracker_123456789abcdefghijklmnopqrstuvwxyz"
  ],
  "url": "https://dashboard.postgrid.com/embed/template_editor_sessions/template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c",
  "createdAt": "2023-07-05T19:36:01.369Z"
}
```

## List Sessions

`client.printMail.templateEditorSessions.list(TemplateEditorSessionListParamsquery?, RequestOptionsoptions?): SkipLimit<TemplateEditorSessionListResponse>`

**get** `/print-mail/v1/template_editor_sessions`

Retrieve a paginated list of Template Editor Sessions.

### Parameters

- `query: TemplateEditorSessionListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `TemplateEditorSessionListResponse`

  - `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?: string`

    The URL supplied when this editor session was created.

  - `styles?: Styles`

    Style overrides for the template editor session.

    - `canvas?: Canvas`

      Style overrides for the template editor canvas.

      - `backgroundColor?: string`

        The canvas background color.

    - `panelText?: PanelText`

      Style overrides for template editor panel text.

      - `color?: string`

        The panel text color.

    - `saveButton?: SaveButton`

      Style overrides for the template editor save button.

      - `backgroundColor?: string`

        The save button background color.

      - `textColor?: string`

        The save button text color.

  - `title?: string`

    The title supplied when this editor session was created.

  - `trackers?: "all" | "none" | Array<string>`

    Controls which Trackers are displayed in the template editor session.

    - `"all" | "none"`

      - `"all"`

      - `"none"`

    - `Array<string>`

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const templateEditorSessionListResponse of client.printMail.templateEditorSessions.list()) {
  console.log(templateEditorSessionListResponse.id);
}
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c",
      "object": "template_editor_session",
      "live": false,
      "template": "template_eYxcbMKPZEZPk71ZJPA6Yz",
      "backURL": "https://postgrid.com",
      "title": "My Editor Session",
      "trackers": "none",
      "url": "https://dashboard.postgrid.com/embed/template_editor_sessions/template_editor_session_bBYRQ5DKu3LJ5yNemoAQ7E3or6E7Yzd7FGNWJSXBRrAfcdoNXNGLvfZxAm2dJYiv9c",
      "createdAt": "2023-07-05T19:36:01.369Z"
    }
  ]
}
```

## Delete Session

`client.printMail.templateEditorSessions.delete(stringid, RequestOptionsoptions?): TemplateEditorSessionDeleteResponse`

**delete** `/print-mail/v1/template_editor_sessions/{id}`

Delete a Template Editor Session by ID.

### Parameters

- `id: string`

### Returns

- `TemplateEditorSessionDeleteResponse`

  - `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

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const templateEditorSession = await client.printMail.templateEditorSessions.delete('id');

console.log(templateEditorSession.id);
```

#### Response

```json
{
  "id": "template_editor_session_vmb3aXRJFzHb4oNRP2XMUZiTTBDtC91CSgQeqUrQfhSqq5P9wAGpmX5UkftueTubMN",
  "object": "template_editor_session",
  "deleted": true
}
```

## Domain Types

### Template Editor Session Create Response

- `TemplateEditorSessionCreateResponse`

  - `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?: string`

    The URL supplied when this editor session was created.

  - `styles?: Styles`

    Style overrides for the template editor session.

    - `canvas?: Canvas`

      Style overrides for the template editor canvas.

      - `backgroundColor?: string`

        The canvas background color.

    - `panelText?: PanelText`

      Style overrides for template editor panel text.

      - `color?: string`

        The panel text color.

    - `saveButton?: SaveButton`

      Style overrides for the template editor save button.

      - `backgroundColor?: string`

        The save button background color.

      - `textColor?: string`

        The save button text color.

  - `title?: string`

    The title supplied when this editor session was created.

  - `trackers?: "all" | "none" | Array<string>`

    Controls which Trackers are displayed in the template editor session.

    - `"all" | "none"`

      - `"all"`

      - `"none"`

    - `Array<string>`

### Template Editor Session List Response

- `TemplateEditorSessionListResponse`

  - `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?: string`

    The URL supplied when this editor session was created.

  - `styles?: Styles`

    Style overrides for the template editor session.

    - `canvas?: Canvas`

      Style overrides for the template editor canvas.

      - `backgroundColor?: string`

        The canvas background color.

    - `panelText?: PanelText`

      Style overrides for template editor panel text.

      - `color?: string`

        The panel text color.

    - `saveButton?: SaveButton`

      Style overrides for the template editor save button.

      - `backgroundColor?: string`

        The save button background color.

      - `textColor?: string`

        The save button text color.

  - `title?: string`

    The title supplied when this editor session was created.

  - `trackers?: "all" | "none" | Array<string>`

    Controls which Trackers are displayed in the template editor session.

    - `"all" | "none"`

      - `"all"`

      - `"none"`

    - `Array<string>`

### Template Editor Session Delete Response

- `TemplateEditorSessionDeleteResponse`

  - `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

`client.printMail.virtualMailboxes.create(VirtualMailboxCreateParamsbody, RequestOptionsoptions?): VirtualMailboxCreateResponse`

**post** `/print-mail/v1/virtual_mailboxes`

Creates a new virtual mailbox.
In live mode, the virtual mailbox will be pending assignment and cannot
be used until it has been assigned and activated by our team. You will be
notified via email once the virtual mailbox has been activated.
In test mode, the virtual mailbox will be activated immediately upon
creation.

### Parameters

- `body: VirtualMailboxCreateParams`

  - `countryCode: "US"`

    All of the supported countries for virtual mailboxes.

    - `"US"`

  - `capabilities?: Capabilities`

    The capabilities the virtual mailbox should support.

    - `envelopeScans: boolean`

      If the virtual mailbox should support envelope scans or not.

    - `forwardMailTo?: ContactCreateWithFirstName | ContactCreateWithCompanyName | string`

      A contact ID or contact object.

      - `ContactCreateWithFirstName`

        - `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?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `companyName?: string`

          Company name of the contact.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `ContactCreateWithCompanyName`

        - `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?: string`

          Second line of the contact's address, if applicable.

        - `city?: string`

          The city of the contact's address.

        - `description?: string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email?: string`

          Email of the contact.

        - `firstName?: string`

          First name of the contact.

        - `forceVerifiedStatus?: boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle?: string`

          Job title of the contact.

        - `lastName?: string`

          Last name of the contact.

        - `metadata?: Record<string, unknown>`

          See the section on Metadata.

        - `phoneNumber?: string`

          Phone number of the contact.

        - `postalOrZip?: string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState?: string`

          Province or state of the contact's address.

        - `secret?: boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification?: boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `string`

### Returns

- `VirtualMailboxCreateResponse`

  The virtual mailbox object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_

  - `capabilities: Capabilities`

    All of the capabilities a virtual mailbox may have.

    - `envelopeScans: boolean`

      Indicates if the virtual mailbox can produce scans of envelopes.

    - `forwardMailTo?: 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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: 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" | "pending_assignment"`

    The possible statuses of virtual mailboxes.

    - `"active"`

    - `"pending_assignment"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const virtualMailbox = await client.printMail.virtualMailboxes.create({
  countryCode: 'US',
  capabilities: { envelopeScans: true, forwardMailTo: 'contact_pxd7wnnD1xY6H6etKNvjb4' },
});

console.log(virtualMailbox.id);
```

#### Response

```json
{
  "id": "virtual_mailbox_abcdefg123456890",
  "object": "virtual_mailbox",
  "live": true,
  "status": "pending_assignment",
  "capabilities": {
    "forwardMailTo": {
      "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
      "object": "contact",
      "live": false,
      "companyName": "PostGrid",
      "addressLine1": "90 CANAL ST STE 600",
      "city": "BOSTON",
      "provinceOrState": "MA",
      "postalOrZip": "90210-1234",
      "countryCode": "US",
      "skipVerification": false,
      "forceVerifiedStatus": false,
      "addressStatus": "verified",
      "createdAt": "2022-02-16T15:08:41.052Z",
      "updatedAt": "2022-02-16T15:08:41.052Z"
    },
    "envelopeScans": true
  },
  "countryCode": "US",
  "createdAt": "2025-11-01T15:08:41.052Z",
  "updatedAt": "2025-11-01T15:08:41.052Z"
}
```

## List Virtual Mailboxes

`client.printMail.virtualMailboxes.list(VirtualMailboxListParamsquery?, RequestOptionsoptions?): SkipLimit<VirtualMailboxListResponse>`

**get** `/print-mail/v1/virtual_mailboxes`

Lists virtual mailboxes. You can use the `skip`, `limit`, and `search`
query parameters to refine the list.

### Parameters

- `query: VirtualMailboxListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `VirtualMailboxListResponse`

  The virtual mailbox object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_

  - `capabilities: Capabilities`

    All of the capabilities a virtual mailbox may have.

    - `envelopeScans: boolean`

      Indicates if the virtual mailbox can produce scans of envelopes.

    - `forwardMailTo?: 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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: 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" | "pending_assignment"`

    The possible statuses of virtual mailboxes.

    - `"active"`

    - `"pending_assignment"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const virtualMailboxListResponse of client.printMail.virtualMailboxes.list()) {
  console.log(virtualMailboxListResponse.id);
}
```

#### Response

```json
{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "virtual_mailbox_abcdefg123456890",
      "object": "virtual_mailbox",
      "live": true,
      "status": "pending_assignment",
      "capabilities": {
        "forwardMailTo": {
          "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
          "object": "contact",
          "live": false,
          "companyName": "PostGrid",
          "addressLine1": "90 CANAL ST STE 600",
          "city": "BOSTON",
          "provinceOrState": "MA",
          "postalOrZip": "90210-1234",
          "countryCode": "US",
          "skipVerification": false,
          "forceVerifiedStatus": false,
          "addressStatus": "verified",
          "createdAt": "2022-02-16T15:08:41.052Z",
          "updatedAt": "2022-02-16T15:08:41.052Z"
        },
        "envelopeScans": true
      },
      "countryCode": "US",
      "createdAt": "2025-11-01T15:08:41.052Z",
      "updatedAt": "2025-11-01T15:08:41.052Z"
    }
  ]
}
```

## Retrieve Virtual Mailbox

`client.printMail.virtualMailboxes.retrieve(stringid, RequestOptionsoptions?): VirtualMailboxRetrieveResponse`

**get** `/print-mail/v1/virtual_mailboxes/{id}`

Retrieve Virtual Mailbox

### Parameters

- `id: string`

### Returns

- `VirtualMailboxRetrieveResponse`

  The virtual mailbox object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_

  - `capabilities: Capabilities`

    All of the capabilities a virtual mailbox may have.

    - `envelopeScans: boolean`

      Indicates if the virtual mailbox can produce scans of envelopes.

    - `forwardMailTo?: 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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: 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" | "pending_assignment"`

    The possible statuses of virtual mailboxes.

    - `"active"`

    - `"pending_assignment"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const virtualMailbox = await client.printMail.virtualMailboxes.retrieve('id');

console.log(virtualMailbox.id);
```

#### Response

```json
{
  "id": "virtual_mailbox_abcdefg123456890",
  "object": "virtual_mailbox",
  "live": true,
  "status": "pending_assignment",
  "capabilities": {
    "forwardMailTo": {
      "id": "contact_pxd7wnnD1xY6H6etKNvjb4",
      "object": "contact",
      "live": false,
      "companyName": "PostGrid",
      "addressLine1": "90 CANAL ST STE 600",
      "city": "BOSTON",
      "provinceOrState": "MA",
      "postalOrZip": "90210-1234",
      "countryCode": "US",
      "skipVerification": false,
      "forceVerifiedStatus": false,
      "addressStatus": "verified",
      "createdAt": "2022-02-16T15:08:41.052Z",
      "updatedAt": "2022-02-16T15:08:41.052Z"
    },
    "envelopeScans": true
  },
  "countryCode": "US",
  "createdAt": "2025-11-01T15:08:41.052Z",
  "updatedAt": "2025-11-01T15:08:41.052Z"
}
```

## Retrieve Physical Address

`client.printMail.virtualMailboxes.retrieveAddress(stringid, RequestOptionsoptions?): VirtualMailboxRetrieveAddressResponse`

**get** `/print-mail/v1/virtual_mailboxes/{id}/address`

Retrieves the physical address of the virtual mailbox.

### Parameters

- `id: string`

### Returns

- `VirtualMailboxRetrieveAddressResponse`

  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?: string`

    The address line 2 of the mailbox.

  - `city?: string`

    The city of the mailbox.

  - `postalOrZip?: string`

    The postal or ZIP code of the mailbox.

  - `provinceOrState?: string`

    The province or state of the mailbox.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const response = await client.printMail.virtualMailboxes.retrieveAddress('id');

console.log(response.addressLine1);
```

#### Response

```json
{
  "addressLine1": "145 Mulberry st",
  "city": "New York",
  "provinceOrState": "NY",
  "postalOrZip": "10013",
  "countryCode": "US"
}
```

## Domain Types

### Virtual Mailbox Create Response

- `VirtualMailboxCreateResponse`

  The virtual mailbox object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_

  - `capabilities: Capabilities`

    All of the capabilities a virtual mailbox may have.

    - `envelopeScans: boolean`

      Indicates if the virtual mailbox can produce scans of envelopes.

    - `forwardMailTo?: 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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: 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" | "pending_assignment"`

    The possible statuses of virtual mailboxes.

    - `"active"`

    - `"pending_assignment"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Virtual Mailbox List Response

- `VirtualMailboxListResponse`

  The virtual mailbox object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_

  - `capabilities: Capabilities`

    All of the capabilities a virtual mailbox may have.

    - `envelopeScans: boolean`

      Indicates if the virtual mailbox can produce scans of envelopes.

    - `forwardMailTo?: 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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: 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" | "pending_assignment"`

    The possible statuses of virtual mailboxes.

    - `"active"`

    - `"pending_assignment"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Virtual Mailbox Retrieve Response

- `VirtualMailboxRetrieveResponse`

  The virtual mailbox object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_

  - `capabilities: Capabilities`

    All of the capabilities a virtual mailbox may have.

    - `envelopeScans: boolean`

      Indicates if the virtual mailbox can produce scans of envelopes.

    - `forwardMailTo?: 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" | "corrected" | "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?: string`

        A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

      - `addressLine2?: string`

        Second line of the contact's address, if applicable.

      - `city?: string`

        The city of the contact's address.

      - `companyName?: string`

        Company name of the contact.

      - `description?: string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `email?: string`

        Email of the contact.

      - `firstName?: string`

        First name of the contact.

      - `forceVerifiedStatus?: boolean`

        If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

      - `jobTitle?: string`

        Job title of the contact.

      - `lastName?: string`

        Last name of the contact.

      - `metadata?: Record<string, unknown>`

        See the section on Metadata.

      - `phoneNumber?: string`

        Phone number of the contact.

      - `postalOrZip?: string`

        The postal or ZIP code of the contact's address.

      - `provinceOrState?: string`

        Province or state of the contact's address.

      - `secret?: boolean`

        If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

      - `skipVerification?: 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" | "pending_assignment"`

    The possible statuses of virtual mailboxes.

    - `"active"`

    - `"pending_assignment"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Virtual Mailbox Retrieve Address Response

- `VirtualMailboxRetrieveAddressResponse`

  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?: string`

    The address line 2 of the mailbox.

  - `city?: string`

    The city of the mailbox.

  - `postalOrZip?: string`

    The postal or ZIP code of the mailbox.

  - `provinceOrState?: string`

    The province or state of the mailbox.

# Items

## List Virtual Mailbox Items

`client.printMail.virtualMailboxes.items.list(stringid, ItemListParamsquery?, RequestOptionsoptions?): SkipLimit<ItemListResponse>`

**get** `/print-mail/v1/virtual_mailboxes/{id}/items`

Lists items for a virtual mailbox.

### Parameters

- `id: string`

- `query: ItemListParams`

  - `limit?: number`

  - `search?: 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?: number`

### Returns

- `ItemListResponse`

  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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `fileURL?: string`

    A URL of the envelope scan PDF.

  - `matchedLetter?: string`

    The ID of the letter this item was matched to.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const itemListResponse of client.printMail.virtualMailboxes.items.list('id')) {
  console.log(itemListResponse.id);
}
```

#### Response

```json
{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "virtual_mailbox_item_abcdefg123456890",
      "object": "virtual_mailbox_item",
      "live": true,
      "virtualMailbox": "virtual_mailbox_abcdefg123456890",
      "fileURL": "https://postgrid.com",
      "matchedLetter": "letter_abcdef1234567890",
      "createdAt": "2025-11-01T15:08:41.052Z",
      "updatedAt": "2025-11-01T15:08:41.052Z"
    }
  ]
}
```

## Create Test Virtual Mailbox Item

`client.printMail.virtualMailboxes.items.create(stringid, ItemCreateParamsbody, RequestOptionsoptions?): ItemCreateResponse`

**post** `/print-mail/v1/virtual_mailboxes/{id}/items`

Create a test item for a virtual mailbox. This is only available in test
mode, an error will be returned if you attempt this call in live mode.

### Parameters

- `id: string`

- `body: ItemCreateParams`

  - `description?: string`

    The description of the item.

  - `matchedLetter?: string`

    The ID of a letter to match this test item to.

  - `metadata?: Record<string, unknown>`

    The metadata of the item.

### Returns

- `ItemCreateResponse`

  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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `fileURL?: string`

    A URL of the envelope scan PDF.

  - `matchedLetter?: string`

    The ID of the letter this item was matched to.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const item = await client.printMail.virtualMailboxes.items.create('id', {
  matchedLetter: 'letter_abcdef1234567890',
});

console.log(item.id);
```

#### Response

```json
{
  "id": "virtual_mailbox_item_abcdefg123456890",
  "object": "virtual_mailbox_item",
  "live": false,
  "virtualMailbox": "virtual_mailbox_abcdefg123456890",
  "fileURL": "https://postgrid.com",
  "matchedLetter": "letter_abcdef1234567890",
  "createdAt": "2025-11-01T15:08:41.052Z",
  "updatedAt": "2025-11-01T15:08:41.052Z"
}
```

## Retrieve Virtual Mailbox Item

`client.printMail.virtualMailboxes.items.retrieve(stringitemID, ItemRetrieveParamsparams, RequestOptionsoptions?): ItemRetrieveResponse`

**get** `/print-mail/v1/virtual_mailboxes/{id}/items/{itemID}`

Retrieves a single item for a virtual mailbox.

### Parameters

- `itemID: string`

- `params: ItemRetrieveParams`

  - `id: string`

### Returns

- `ItemRetrieveResponse`

  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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `fileURL?: string`

    A URL of the envelope scan PDF.

  - `matchedLetter?: string`

    The ID of the letter this item was matched to.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Example

```typescript
import PostGrid from 'postgrid-node';

const client = new PostGrid({
  printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted
});

const item = await client.printMail.virtualMailboxes.items.retrieve('itemID', { id: 'id' });

console.log(item.id);
```

#### Response

```json
{
  "id": "virtual_mailbox_item_abcdefg123456890",
  "object": "virtual_mailbox_item",
  "live": true,
  "virtualMailbox": "virtual_mailbox_abcdefg123456890",
  "fileURL": "https://postgrid.com",
  "matchedLetter": "letter_abcdef1234567890",
  "createdAt": "2025-11-01T15:08:41.052Z",
  "updatedAt": "2025-11-01T15:08:41.052Z"
}
```

## Domain Types

### Item List Response

- `ItemListResponse`

  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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `fileURL?: string`

    A URL of the envelope scan PDF.

  - `matchedLetter?: string`

    The ID of the letter this item was matched to.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Item Create Response

- `ItemCreateResponse`

  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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `fileURL?: string`

    A URL of the envelope scan PDF.

  - `matchedLetter?: string`

    The ID of the letter this item was matched to.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.

### Item Retrieve Response

- `ItemRetrieveResponse`

  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?: string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `fileURL?: string`

    A URL of the envelope scan PDF.

  - `matchedLetter?: string`

    The ID of the letter this item was matched to.

  - `metadata?: Record<string, unknown>`

    See the section on Metadata.