Retrieve Virtual Mailbox

print_mail.virtual_mailboxes.retrieve() -> VirtualMailboxRetrieveResponse

GET/print-mail/v1/virtual_mailboxes/{id}

ParametersExpand Collapse

id: str

ReturnsExpand Collapse

class VirtualMailboxRetrieveResponse: …

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.

Retrieve Virtual Mailbox

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
)
virtual_mailbox = client.print_mail.virtual_mailboxes.retrieve(
    "id",
)
print(virtual_mailbox.id)

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

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