List Virtual Mailboxes

print_mail.virtual_mailboxes.list() -> SyncSkipLimit[VirtualMailboxListResponse]

GET/print-mail/v1/virtual_mailboxes

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

ParametersExpand Collapse

limit: Optional[int]

formatint32

search: Optional[str]

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

skip: Optional[int]

formatint32

ReturnsExpand Collapse

class VirtualMailboxListResponse: …

The virtual mailbox object.

id: str

A unique ID prefixed with virtual_mailbox_

capabilities: Capabilities

All of the capabilities a virtual mailbox may have.

envelope_scans: bool

Indicates if the virtual mailbox can produce scans of envelopes.

forward_mail_to: Optional[Contact]

A contact to forward any returned mail to.

id: str

A unique ID prefixed with contact_

address_line1: str

The first line of the contact’s address.

address_status: Literal["verified", "corrected", "failed"]

One of verified, corrected, or failed.

One of the following:

"verified"

"corrected"

"failed"

country_code: str

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

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["contact"]

Always contact.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

address_errors: Optional[str]

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

address_line2: Optional[str]

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

city: Optional[str]

The city of the contact’s address.

company_name: Optional[str]

Company name of the contact.

description: Optional[str]

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

email: Optional[str]

Email of the contact.

first_name: Optional[str]

First name of the contact.

force_verified_status: Optional[bool]

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

job_title: Optional[str]

Job title of the contact.

last_name: Optional[str]

Last name of the contact.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

phone_number: Optional[str]

Phone number of the contact.

postal_or_zip: Optional[str]

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

province_or_state: Optional[str]

Province or state of the contact’s address.

skip_verification: Optional[bool]

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

country_code: Literal["US"]

All of the supported countries for virtual mailboxes.

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["virtual_mailbox"]

Always “virtual_mailbox”.

status: Literal["active", "pending_assignment"]

The possible statuses of virtual mailboxes.

One of the following:

"active"

"pending_assignment"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

description: Optional[str]

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

metadata: Optional[Dict[str, object]]

See the section on Metadata.

List Virtual Mailboxes

import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
page = client.print_mail.virtual_mailboxes.list()
page = page.data[0]
print(page.id)

{
  "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"
    }
  ]
}

Returns Examples

{
  "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"
    }
  ]
}