# Virtual Mailboxes

## Create Virtual Mailbox

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

Creates a new virtual mailbox.
In live mode, the virtual mailbox will be pending assignment and cannot
be used until it has been assigned and activated by our team. You will be
notified via email once the virtual mailbox has been activated.
In test mode, the virtual mailbox will be activated immediately upon
creation.

### Body Parameters

- `countryCode: "US"`

  All of the supported countries for virtual mailboxes.

  - `"US"`

- `capabilities: optional object { envelopeScans, forwardMailTo }`

  The capabilities the virtual mailbox should support.

  - `envelopeScans: boolean`

    If the virtual mailbox should support envelope scans or not.

  - `forwardMailTo: optional ContactCreateWithFirstName or ContactCreateWithCompanyName or string`

    A contact ID or contact object.

    - `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }`

      - `addressLine1: string`

        The first line of the contact's address.

      - `countryCode: string`

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

      - `firstName: string`

      - `addressLine2: optional string`

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

      - `city: optional string`

        The city of the contact's address.

      - `companyName: optional string`

        Company name of the contact.

      - `description: optional string`

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

      - `email: optional string`

        Email of the contact.

      - `forceVerifiedStatus: optional boolean`

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

      - `jobTitle: optional string`

        Job title of the contact.

      - `lastName: optional string`

        Last name of the contact.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

      - `phoneNumber: optional string`

        Phone number of the contact.

      - `postalOrZip: optional string`

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

      - `provinceOrState: optional string`

        Province or state of the contact's address.

      - `skipVerification: optional boolean`

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

    - `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }`

      - `addressLine1: string`

        The first line of the contact's address.

      - `companyName: string`

      - `countryCode: string`

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

      - `addressLine2: optional string`

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

      - `city: optional string`

        The city of the contact's address.

      - `description: optional string`

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

      - `email: optional string`

        Email of the contact.

      - `firstName: optional string`

        First name of the contact.

      - `forceVerifiedStatus: optional boolean`

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

      - `jobTitle: optional string`

        Job title of the contact.

      - `lastName: optional string`

        Last name of the contact.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

      - `phoneNumber: optional string`

        Phone number of the contact.

      - `postalOrZip: optional string`

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

      - `provinceOrState: optional string`

        Province or state of the contact's address.

      - `skipVerification: optional boolean`

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

    - `string`

### Returns

- `id: string`

  A unique ID prefixed with virtual_mailbox_

- `capabilities: object { envelopeScans, forwardMailTo }`

  All of the capabilities a virtual mailbox may have.

  - `envelopeScans: boolean`

    Indicates if the virtual mailbox can produce scans of envelopes.

  - `forwardMailTo: optional Contact`

    A contact to forward any returned mail to.

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" or "corrected" or "failed"`

      One of `verified`, `corrected`, or `failed`.

      - `"verified"`

      - `"corrected"`

      - `"failed"`

    - `countryCode: string`

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

    - `createdAt: string`

      The UTC time at which this resource was created.

    - `live: boolean`

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

    - `object: "contact"`

      Always `contact`.

      - `"contact"`

    - `updatedAt: string`

      The UTC time at which this resource was last updated.

    - `addressErrors: optional string`

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

    - `addressLine2: optional string`

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

    - `city: optional string`

      The city of the contact's address.

    - `companyName: optional string`

      Company name of the contact.

    - `description: optional string`

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

    - `email: optional string`

      Email of the contact.

    - `firstName: optional string`

      First name of the contact.

    - `forceVerifiedStatus: optional boolean`

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

    - `jobTitle: optional string`

      Job title of the contact.

    - `lastName: optional string`

      Last name of the contact.

    - `metadata: optional map[unknown]`

      See the section on Metadata.

    - `phoneNumber: optional string`

      Phone number of the contact.

    - `postalOrZip: optional string`

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

    - `provinceOrState: optional string`

      Province or state of the contact's address.

    - `skipVerification: optional boolean`

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

- `countryCode: "US"`

  All of the supported countries for virtual mailboxes.

  - `"US"`

- `createdAt: string`

  The UTC time at which this resource was created.

- `live: boolean`

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

- `object: "virtual_mailbox"`

  Always "virtual_mailbox".

  - `"virtual_mailbox"`

- `status: "active" or "pending_assignment"`

  The possible statuses of virtual mailboxes.

  - `"active"`

  - `"pending_assignment"`

- `updatedAt: string`

  The UTC time at which this resource was last updated.

- `description: optional string`

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

- `metadata: optional map[unknown]`

  See the section on Metadata.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
    -d '{
          "countryCode": "US"
        }'
```

#### Response

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

## List Virtual Mailboxes

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

Lists virtual mailboxes. You can use the `skip`, `limit`, and `search`
query parameters to refine the list.

### Query Parameters

- `limit: optional number`

- `search: optional string`

  You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.

- `skip: optional number`

### Returns

- `data: array of object { id, capabilities, countryCode, 7 more }`

  - `id: string`

    A unique ID prefixed with virtual_mailbox_

  - `capabilities: object { envelopeScans, forwardMailTo }`

    All of the capabilities a virtual mailbox may have.

    - `envelopeScans: boolean`

      Indicates if the virtual mailbox can produce scans of envelopes.

    - `forwardMailTo: optional Contact`

      A contact to forward any returned mail to.

      - `id: string`

        A unique ID prefixed with contact_

      - `addressLine1: string`

        The first line of the contact's address.

      - `addressStatus: "verified" or "corrected" or "failed"`

        One of `verified`, `corrected`, or `failed`.

        - `"verified"`

        - `"corrected"`

        - `"failed"`

      - `countryCode: string`

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

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

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

      - `object: "contact"`

        Always `contact`.

        - `"contact"`

      - `updatedAt: string`

        The UTC time at which this resource was last updated.

      - `addressErrors: optional string`

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

      - `addressLine2: optional string`

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

      - `city: optional string`

        The city of the contact's address.

      - `companyName: optional string`

        Company name of the contact.

      - `description: optional string`

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

      - `email: optional string`

        Email of the contact.

      - `firstName: optional string`

        First name of the contact.

      - `forceVerifiedStatus: optional boolean`

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

      - `jobTitle: optional string`

        Job title of the contact.

      - `lastName: optional string`

        Last name of the contact.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

      - `phoneNumber: optional string`

        Phone number of the contact.

      - `postalOrZip: optional string`

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

      - `provinceOrState: optional string`

        Province or state of the contact's address.

      - `skipVerification: optional boolean`

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

  - `countryCode: "US"`

    All of the supported countries for virtual mailboxes.

    - `"US"`

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

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

  - `object: "virtual_mailbox"`

    Always "virtual_mailbox".

    - `"virtual_mailbox"`

  - `status: "active" or "pending_assignment"`

    The possible statuses of virtual mailboxes.

    - `"active"`

    - `"pending_assignment"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

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

  - `metadata: optional map[unknown]`

    See the section on Metadata.

- `limit: number`

- `object: "list"`

  - `"list"`

- `skip: number`

- `totalCount: number`

### Example

```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

#### Response

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

## Retrieve Virtual Mailbox

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

Retrieve Virtual Mailbox

### Path Parameters

- `id: string`

### Returns

- `id: string`

  A unique ID prefixed with virtual_mailbox_

- `capabilities: object { envelopeScans, forwardMailTo }`

  All of the capabilities a virtual mailbox may have.

  - `envelopeScans: boolean`

    Indicates if the virtual mailbox can produce scans of envelopes.

  - `forwardMailTo: optional Contact`

    A contact to forward any returned mail to.

    - `id: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" or "corrected" or "failed"`

      One of `verified`, `corrected`, or `failed`.

      - `"verified"`

      - `"corrected"`

      - `"failed"`

    - `countryCode: string`

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

    - `createdAt: string`

      The UTC time at which this resource was created.

    - `live: boolean`

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

    - `object: "contact"`

      Always `contact`.

      - `"contact"`

    - `updatedAt: string`

      The UTC time at which this resource was last updated.

    - `addressErrors: optional string`

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

    - `addressLine2: optional string`

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

    - `city: optional string`

      The city of the contact's address.

    - `companyName: optional string`

      Company name of the contact.

    - `description: optional string`

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

    - `email: optional string`

      Email of the contact.

    - `firstName: optional string`

      First name of the contact.

    - `forceVerifiedStatus: optional boolean`

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

    - `jobTitle: optional string`

      Job title of the contact.

    - `lastName: optional string`

      Last name of the contact.

    - `metadata: optional map[unknown]`

      See the section on Metadata.

    - `phoneNumber: optional string`

      Phone number of the contact.

    - `postalOrZip: optional string`

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

    - `provinceOrState: optional string`

      Province or state of the contact's address.

    - `skipVerification: optional boolean`

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

- `countryCode: "US"`

  All of the supported countries for virtual mailboxes.

  - `"US"`

- `createdAt: string`

  The UTC time at which this resource was created.

- `live: boolean`

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

- `object: "virtual_mailbox"`

  Always "virtual_mailbox".

  - `"virtual_mailbox"`

- `status: "active" or "pending_assignment"`

  The possible statuses of virtual mailboxes.

  - `"active"`

  - `"pending_assignment"`

- `updatedAt: string`

  The UTC time at which this resource was last updated.

- `description: optional string`

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

- `metadata: optional map[unknown]`

  See the section on Metadata.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes/$ID \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

#### Response

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

## Retrieve Physical Address

**get** `/print-mail/v1/virtual_mailboxes/{id}/address`

Retrieves the physical address of the virtual mailbox.

### Path Parameters

- `id: string`

### Returns

- `addressLine1: string`

  The address line 1 of the mailbox.

- `countryCode: "US"`

  All of the supported countries for virtual mailboxes.

  - `"US"`

- `addressLine2: optional string`

  The address line 2 of the mailbox.

- `city: optional string`

  The city of the mailbox.

- `postalOrZip: optional string`

  The postal or ZIP code of the mailbox.

- `provinceOrState: optional string`

  The province or state of the mailbox.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes/$ID/address \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

#### Response

```json
{
  "addressLine1": "145 Mulberry st",
  "city": "New York",
  "provinceOrState": "NY",
  "postalOrZip": "10013",
  "countryCode": "US"
}
```

## Domain Types

### Virtual Mailbox Create Response

- `VirtualMailboxCreateResponse object { id, capabilities, countryCode, 7 more }`

  The virtual mailbox object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_

  - `capabilities: object { envelopeScans, forwardMailTo }`

    All of the capabilities a virtual mailbox may have.

    - `envelopeScans: boolean`

      Indicates if the virtual mailbox can produce scans of envelopes.

    - `forwardMailTo: optional Contact`

      A contact to forward any returned mail to.

      - `id: string`

        A unique ID prefixed with contact_

      - `addressLine1: string`

        The first line of the contact's address.

      - `addressStatus: "verified" or "corrected" or "failed"`

        One of `verified`, `corrected`, or `failed`.

        - `"verified"`

        - `"corrected"`

        - `"failed"`

      - `countryCode: string`

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

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

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

      - `object: "contact"`

        Always `contact`.

        - `"contact"`

      - `updatedAt: string`

        The UTC time at which this resource was last updated.

      - `addressErrors: optional string`

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

      - `addressLine2: optional string`

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

      - `city: optional string`

        The city of the contact's address.

      - `companyName: optional string`

        Company name of the contact.

      - `description: optional string`

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

      - `email: optional string`

        Email of the contact.

      - `firstName: optional string`

        First name of the contact.

      - `forceVerifiedStatus: optional boolean`

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

      - `jobTitle: optional string`

        Job title of the contact.

      - `lastName: optional string`

        Last name of the contact.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

      - `phoneNumber: optional string`

        Phone number of the contact.

      - `postalOrZip: optional string`

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

      - `provinceOrState: optional string`

        Province or state of the contact's address.

      - `skipVerification: optional boolean`

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

  - `countryCode: "US"`

    All of the supported countries for virtual mailboxes.

    - `"US"`

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

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

  - `object: "virtual_mailbox"`

    Always "virtual_mailbox".

    - `"virtual_mailbox"`

  - `status: "active" or "pending_assignment"`

    The possible statuses of virtual mailboxes.

    - `"active"`

    - `"pending_assignment"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

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

  - `metadata: optional map[unknown]`

    See the section on Metadata.

### Virtual Mailbox List Response

- `VirtualMailboxListResponse object { id, capabilities, countryCode, 7 more }`

  The virtual mailbox object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_

  - `capabilities: object { envelopeScans, forwardMailTo }`

    All of the capabilities a virtual mailbox may have.

    - `envelopeScans: boolean`

      Indicates if the virtual mailbox can produce scans of envelopes.

    - `forwardMailTo: optional Contact`

      A contact to forward any returned mail to.

      - `id: string`

        A unique ID prefixed with contact_

      - `addressLine1: string`

        The first line of the contact's address.

      - `addressStatus: "verified" or "corrected" or "failed"`

        One of `verified`, `corrected`, or `failed`.

        - `"verified"`

        - `"corrected"`

        - `"failed"`

      - `countryCode: string`

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

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

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

      - `object: "contact"`

        Always `contact`.

        - `"contact"`

      - `updatedAt: string`

        The UTC time at which this resource was last updated.

      - `addressErrors: optional string`

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

      - `addressLine2: optional string`

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

      - `city: optional string`

        The city of the contact's address.

      - `companyName: optional string`

        Company name of the contact.

      - `description: optional string`

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

      - `email: optional string`

        Email of the contact.

      - `firstName: optional string`

        First name of the contact.

      - `forceVerifiedStatus: optional boolean`

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

      - `jobTitle: optional string`

        Job title of the contact.

      - `lastName: optional string`

        Last name of the contact.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

      - `phoneNumber: optional string`

        Phone number of the contact.

      - `postalOrZip: optional string`

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

      - `provinceOrState: optional string`

        Province or state of the contact's address.

      - `skipVerification: optional boolean`

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

  - `countryCode: "US"`

    All of the supported countries for virtual mailboxes.

    - `"US"`

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

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

  - `object: "virtual_mailbox"`

    Always "virtual_mailbox".

    - `"virtual_mailbox"`

  - `status: "active" or "pending_assignment"`

    The possible statuses of virtual mailboxes.

    - `"active"`

    - `"pending_assignment"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

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

  - `metadata: optional map[unknown]`

    See the section on Metadata.

### Virtual Mailbox Retrieve Response

- `VirtualMailboxRetrieveResponse object { id, capabilities, countryCode, 7 more }`

  The virtual mailbox object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_

  - `capabilities: object { envelopeScans, forwardMailTo }`

    All of the capabilities a virtual mailbox may have.

    - `envelopeScans: boolean`

      Indicates if the virtual mailbox can produce scans of envelopes.

    - `forwardMailTo: optional Contact`

      A contact to forward any returned mail to.

      - `id: string`

        A unique ID prefixed with contact_

      - `addressLine1: string`

        The first line of the contact's address.

      - `addressStatus: "verified" or "corrected" or "failed"`

        One of `verified`, `corrected`, or `failed`.

        - `"verified"`

        - `"corrected"`

        - `"failed"`

      - `countryCode: string`

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

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

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

      - `object: "contact"`

        Always `contact`.

        - `"contact"`

      - `updatedAt: string`

        The UTC time at which this resource was last updated.

      - `addressErrors: optional string`

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

      - `addressLine2: optional string`

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

      - `city: optional string`

        The city of the contact's address.

      - `companyName: optional string`

        Company name of the contact.

      - `description: optional string`

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

      - `email: optional string`

        Email of the contact.

      - `firstName: optional string`

        First name of the contact.

      - `forceVerifiedStatus: optional boolean`

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

      - `jobTitle: optional string`

        Job title of the contact.

      - `lastName: optional string`

        Last name of the contact.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

      - `phoneNumber: optional string`

        Phone number of the contact.

      - `postalOrZip: optional string`

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

      - `provinceOrState: optional string`

        Province or state of the contact's address.

      - `skipVerification: optional boolean`

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

  - `countryCode: "US"`

    All of the supported countries for virtual mailboxes.

    - `"US"`

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

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

  - `object: "virtual_mailbox"`

    Always "virtual_mailbox".

    - `"virtual_mailbox"`

  - `status: "active" or "pending_assignment"`

    The possible statuses of virtual mailboxes.

    - `"active"`

    - `"pending_assignment"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

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

  - `metadata: optional map[unknown]`

    See the section on Metadata.

### Virtual Mailbox Retrieve Address Response

- `VirtualMailboxRetrieveAddressResponse object { addressLine1, countryCode, addressLine2, 3 more }`

  The address information for a mailbox.

  - `addressLine1: string`

    The address line 1 of the mailbox.

  - `countryCode: "US"`

    All of the supported countries for virtual mailboxes.

    - `"US"`

  - `addressLine2: optional string`

    The address line 2 of the mailbox.

  - `city: optional string`

    The city of the mailbox.

  - `postalOrZip: optional string`

    The postal or ZIP code of the mailbox.

  - `provinceOrState: optional string`

    The province or state of the mailbox.

# Items

## List Virtual Mailbox Items

**get** `/print-mail/v1/virtual_mailboxes/{id}/items`

Lists items for a virtual mailbox.

### Path Parameters

- `id: string`

### Query Parameters

- `limit: optional number`

- `search: optional string`

  You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.

- `skip: optional number`

### Returns

- `data: array of object { id, createdAt, live, 7 more }`

  - `id: string`

    A unique ID prefixed with virtual_mailbox_item_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

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

  - `object: "virtual_mailbox_item"`

    Always "virtual_mailbox_item".

    - `"virtual_mailbox_item"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `virtualMailbox: string`

    The ID of the virtual mailbox associated with this item.

  - `description: optional string`

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

  - `fileURL: optional string`

    A URL of the envelope scan PDF.

  - `matchedLetter: optional string`

    The ID of the letter this item was matched to.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

- `limit: number`

- `object: "list"`

  - `"list"`

- `skip: number`

- `totalCount: number`

### Example

```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes/$ID/items \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

#### Response

```json
{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "virtual_mailbox_item_abcdefg123456890",
      "object": "virtual_mailbox_item",
      "live": true,
      "virtualMailbox": "virtual_mailbox_abcdefg123456890",
      "fileURL": "https://postgrid.com",
      "matchedLetter": "letter_abcdef1234567890",
      "createdAt": "2025-11-01T15:08:41.052Z",
      "updatedAt": "2025-11-01T15:08:41.052Z"
    }
  ]
}
```

## Create Test Virtual Mailbox Item

**post** `/print-mail/v1/virtual_mailboxes/{id}/items`

Create a test item for a virtual mailbox. This is only available in test
mode, an error will be returned if you attempt this call in live mode.

### Path Parameters

- `id: string`

### Body Parameters

- `description: optional string`

  The description of the item.

- `matchedLetter: optional string`

  The ID of a letter to match this test item to.

- `metadata: optional map[unknown]`

  The metadata of the item.

### Returns

- `id: string`

  A unique ID prefixed with virtual_mailbox_item_

- `createdAt: string`

  The UTC time at which this resource was created.

- `live: boolean`

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

- `object: "virtual_mailbox_item"`

  Always "virtual_mailbox_item".

  - `"virtual_mailbox_item"`

- `updatedAt: string`

  The UTC time at which this resource was last updated.

- `virtualMailbox: string`

  The ID of the virtual mailbox associated with this item.

- `description: optional string`

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

- `fileURL: optional string`

  A URL of the envelope scan PDF.

- `matchedLetter: optional string`

  The ID of the letter this item was matched to.

- `metadata: optional map[unknown]`

  See the section on Metadata.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes/$ID/items \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
    -d '{}'
```

#### Response

```json
{
  "id": "virtual_mailbox_item_abcdefg123456890",
  "object": "virtual_mailbox_item",
  "live": false,
  "virtualMailbox": "virtual_mailbox_abcdefg123456890",
  "fileURL": "https://postgrid.com",
  "matchedLetter": "letter_abcdef1234567890",
  "createdAt": "2025-11-01T15:08:41.052Z",
  "updatedAt": "2025-11-01T15:08:41.052Z"
}
```

## Retrieve Virtual Mailbox Item

**get** `/print-mail/v1/virtual_mailboxes/{id}/items/{itemID}`

Retrieves a single item for a virtual mailbox.

### Path Parameters

- `id: string`

- `itemID: string`

### Returns

- `id: string`

  A unique ID prefixed with virtual_mailbox_item_

- `createdAt: string`

  The UTC time at which this resource was created.

- `live: boolean`

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

- `object: "virtual_mailbox_item"`

  Always "virtual_mailbox_item".

  - `"virtual_mailbox_item"`

- `updatedAt: string`

  The UTC time at which this resource was last updated.

- `virtualMailbox: string`

  The ID of the virtual mailbox associated with this item.

- `description: optional string`

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

- `fileURL: optional string`

  A URL of the envelope scan PDF.

- `matchedLetter: optional string`

  The ID of the letter this item was matched to.

- `metadata: optional map[unknown]`

  See the section on Metadata.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes/$ID/items/$ITEM_ID \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

#### Response

```json
{
  "id": "virtual_mailbox_item_abcdefg123456890",
  "object": "virtual_mailbox_item",
  "live": true,
  "virtualMailbox": "virtual_mailbox_abcdefg123456890",
  "fileURL": "https://postgrid.com",
  "matchedLetter": "letter_abcdef1234567890",
  "createdAt": "2025-11-01T15:08:41.052Z",
  "updatedAt": "2025-11-01T15:08:41.052Z"
}
```

## Domain Types

### Item List Response

- `ItemListResponse object { id, createdAt, live, 7 more }`

  The virtual mailbox item object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_item_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

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

  - `object: "virtual_mailbox_item"`

    Always "virtual_mailbox_item".

    - `"virtual_mailbox_item"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `virtualMailbox: string`

    The ID of the virtual mailbox associated with this item.

  - `description: optional string`

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

  - `fileURL: optional string`

    A URL of the envelope scan PDF.

  - `matchedLetter: optional string`

    The ID of the letter this item was matched to.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

### Item Create Response

- `ItemCreateResponse object { id, createdAt, live, 7 more }`

  The virtual mailbox item object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_item_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

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

  - `object: "virtual_mailbox_item"`

    Always "virtual_mailbox_item".

    - `"virtual_mailbox_item"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `virtualMailbox: string`

    The ID of the virtual mailbox associated with this item.

  - `description: optional string`

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

  - `fileURL: optional string`

    A URL of the envelope scan PDF.

  - `matchedLetter: optional string`

    The ID of the letter this item was matched to.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

### Item Retrieve Response

- `ItemRetrieveResponse object { id, createdAt, live, 7 more }`

  The virtual mailbox item object.

  - `id: string`

    A unique ID prefixed with virtual_mailbox_item_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

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

  - `object: "virtual_mailbox_item"`

    Always "virtual_mailbox_item".

    - `"virtual_mailbox_item"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `virtualMailbox: string`

    The ID of the virtual mailbox associated with this item.

  - `description: optional string`

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

  - `fileURL: optional string`

    A URL of the envelope scan PDF.

  - `matchedLetter: optional string`

    The ID of the letter this item was matched to.

  - `metadata: optional map[unknown]`

    See the section on Metadata.