## 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"
    }
  ]
}
```