API Reference

Print Mail

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Virtual Mailboxes

Virtual mailboxes let you receive, scan, and forward your physical mail without needing a traditional physical mailbox. Each mailbox is fully digital, giving you a unique ID, status, and a set of capabilities such as forwarding mail to another address or viewing envelope scans. This allows you to manage physical correspondence entirely online.

You can request access to this feature by reaching out to support@postgrid.com

Create Virtual Mailbox

print_mail.virtual_mailboxes.create(VirtualMailboxCreateParams**kwargs) -> VirtualMailboxCreateResponse

POST/print-mail/v1/virtual_mailboxes

List Virtual Mailboxes

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

GET/print-mail/v1/virtual_mailboxes

Retrieve Virtual Mailbox

print_mail.virtual_mailboxes.retrieve(strid) -> VirtualMailboxRetrieveResponse

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

Retrieve Physical Address

print_mail.virtual_mailboxes.retrieve_address(strid) -> VirtualMailboxRetrieveAddressResponse

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

ModelsExpand Collapse

class VirtualMailboxCreateResponse: …

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.

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.

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.

class VirtualMailboxRetrieveAddressResponse: …

The address information for a mailbox.

address_line1: str

The address line 1 of the mailbox.

country_code: Literal["US"]

All of the supported countries for virtual mailboxes.

address_line2: Optional[str]

The address line 2 of the mailbox.

city: Optional[str]

The city of the mailbox.

postal_or_zip: Optional[str]

The postal or ZIP code of the mailbox.

province_or_state: Optional[str]

The province or state of the mailbox.

Virtual MailboxesItems

Virtual mailboxes let you receive, scan, and forward your physical mail without needing a traditional physical mailbox. Each mailbox is fully digital, giving you a unique ID, status, and a set of capabilities such as forwarding mail to another address or viewing envelope scans. This allows you to manage physical correspondence entirely online.

You can request access to this feature by reaching out to support@postgrid.com

List Virtual Mailbox Items

print_mail.virtual_mailboxes.items.list(strid, ItemListParams**kwargs) -> SyncSkipLimit[ItemListResponse]

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

Create Test Virtual Mailbox Item

print_mail.virtual_mailboxes.items.create(strid, ItemCreateParams**kwargs) -> ItemCreateResponse

POST/print-mail/v1/virtual_mailboxes/{id}/items

Retrieve Virtual Mailbox Item

print_mail.virtual_mailboxes.items.retrieve(stritem_id, ItemRetrieveParams**kwargs) -> ItemRetrieveResponse

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

ModelsExpand Collapse

class ItemListResponse: …

The virtual mailbox item object.

id: str

A unique ID prefixed with virtual_mailbox_item_

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_item"]

Always “virtual_mailbox_item”.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

virtual_mailbox: str

The ID of the virtual mailbox associated with this item.

description: Optional[str]

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

file_url: Optional[str]

A URL of the envelope scan PDF.

matched_letter: Optional[str]

The ID of the letter this item was matched to.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

class ItemCreateResponse: …

The virtual mailbox item object.

id: str

A unique ID prefixed with virtual_mailbox_item_

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_item"]

Always “virtual_mailbox_item”.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

virtual_mailbox: str

The ID of the virtual mailbox associated with this item.

description: Optional[str]

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

file_url: Optional[str]

A URL of the envelope scan PDF.

matched_letter: Optional[str]

The ID of the letter this item was matched to.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

class ItemRetrieveResponse: …

The virtual mailbox item object.

id: str

A unique ID prefixed with virtual_mailbox_item_

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_item"]

Always “virtual_mailbox_item”.

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

virtual_mailbox: str

The ID of the virtual mailbox associated with this item.

description: Optional[str]

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

file_url: Optional[str]

A URL of the envelope scan PDF.

matched_letter: Optional[str]

The ID of the letter this item was matched to.

metadata: Optional[Dict[str, object]]

See the section on Metadata.