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 [email protected]

Create Virtual Mailbox

client.printMail.virtualMailboxes.create(VirtualMailboxCreateParams { countryCode, capabilities } body, RequestOptionsoptions?): VirtualMailboxCreateResponse { id, capabilities, countryCode, 7 more }

POST/print-mail/v1/virtual_mailboxes

List Virtual Mailboxes

client.printMail.virtualMailboxes.list(VirtualMailboxListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<VirtualMailboxListResponse { id, capabilities, countryCode, 7 more } >

GET/print-mail/v1/virtual_mailboxes

Retrieve Virtual Mailbox

client.printMail.virtualMailboxes.retrieve(stringid, RequestOptionsoptions?): VirtualMailboxRetrieveResponse { id, capabilities, countryCode, 7 more }

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

Retrieve Physical Address

client.printMail.virtualMailboxes.retrieveAddress(stringid, RequestOptionsoptions?): VirtualMailboxRetrieveAddressResponse { addressLine1, countryCode, addressLine2, 3 more }

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

ModelsExpand Collapse

VirtualMailboxCreateResponse { id, capabilities, countryCode, 7 more }

The virtual mailbox object.

id: string

A unique ID prefixed with virtual_mailbox_

capabilities: Capabilities { envelopeScans, forwardMailTo }

All of the capabilities a virtual mailbox may have.

envelopeScans: boolean

Indicates if the virtual mailbox can produce scans of envelopes.

forwardMailTo?: Contact { id, addressLine1, addressStatus, 21 more }

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" | "corrected" | "failed"

One of verified, corrected, or failed.

One of the following:

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

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors?: string

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

addressLine2?: string

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

city?: string

The city of the contact’s address.

companyName?: string

Company name of the contact.

description?: string

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

email?: string

Email of the contact.

firstName?: string

First name of the contact.

forceVerifiedStatus?: boolean

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

jobTitle?: string

Job title of the contact.

lastName?: string

Last name of the contact.

metadata?: Record<string, unknown>

See the section on Metadata.

phoneNumber?: string

Phone number of the contact.

postalOrZip?: string

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

provinceOrState?: string

Province or state of the contact’s address.

secret?: boolean

If true, the contact’s details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

skipVerification?: 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.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "virtual_mailbox"

Always “virtual_mailbox”.

status: "active" | "pending_assignment"

The possible statuses of virtual mailboxes.

One of the following:

"active"

"pending_assignment"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

description?: string

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

metadata?: Record<string, unknown>

See the section on Metadata.

VirtualMailboxListResponse { id, capabilities, countryCode, 7 more }

The virtual mailbox object.

id: string

A unique ID prefixed with virtual_mailbox_

capabilities: Capabilities { envelopeScans, forwardMailTo }

All of the capabilities a virtual mailbox may have.

envelopeScans: boolean

Indicates if the virtual mailbox can produce scans of envelopes.

forwardMailTo?: Contact { id, addressLine1, addressStatus, 21 more }

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" | "corrected" | "failed"

One of verified, corrected, or failed.

One of the following:

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

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors?: string

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

addressLine2?: string

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

city?: string

The city of the contact’s address.

companyName?: string

Company name of the contact.

description?: string

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

email?: string

Email of the contact.

firstName?: string

First name of the contact.

forceVerifiedStatus?: boolean

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

jobTitle?: string

Job title of the contact.

lastName?: string

Last name of the contact.

metadata?: Record<string, unknown>

See the section on Metadata.

phoneNumber?: string

Phone number of the contact.

postalOrZip?: string

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

provinceOrState?: string

Province or state of the contact’s address.

secret?: boolean

If true, the contact’s details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

skipVerification?: 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.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "virtual_mailbox"

Always “virtual_mailbox”.

status: "active" | "pending_assignment"

The possible statuses of virtual mailboxes.

One of the following:

"active"

"pending_assignment"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

description?: string

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

metadata?: Record<string, unknown>

See the section on Metadata.

VirtualMailboxRetrieveResponse { id, capabilities, countryCode, 7 more }

The virtual mailbox object.

id: string

A unique ID prefixed with virtual_mailbox_

capabilities: Capabilities { envelopeScans, forwardMailTo }

All of the capabilities a virtual mailbox may have.

envelopeScans: boolean

Indicates if the virtual mailbox can produce scans of envelopes.

forwardMailTo?: Contact { id, addressLine1, addressStatus, 21 more }

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" | "corrected" | "failed"

One of verified, corrected, or failed.

One of the following:

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

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "contact"

Always contact.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

addressErrors?: string

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

addressLine2?: string

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

city?: string

The city of the contact’s address.

companyName?: string

Company name of the contact.

description?: string

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

email?: string

Email of the contact.

firstName?: string

First name of the contact.

forceVerifiedStatus?: boolean

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

jobTitle?: string

Job title of the contact.

lastName?: string

Last name of the contact.

metadata?: Record<string, unknown>

See the section on Metadata.

phoneNumber?: string

Phone number of the contact.

postalOrZip?: string

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

provinceOrState?: string

Province or state of the contact’s address.

secret?: boolean

If true, the contact’s details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

skipVerification?: 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.

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "virtual_mailbox"

Always “virtual_mailbox”.

status: "active" | "pending_assignment"

The possible statuses of virtual mailboxes.

One of the following:

"active"

"pending_assignment"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

description?: string

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

metadata?: Record<string, unknown>

See the section on Metadata.

VirtualMailboxRetrieveAddressResponse { 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.

addressLine2?: string

The address line 2 of the mailbox.

city?: string

The city of the mailbox.

postalOrZip?: string

The postal or ZIP code of the mailbox.

provinceOrState?: string

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 [email protected]

List Virtual Mailbox Items

client.printMail.virtualMailboxes.items.list(stringid, ItemListParams { limit, search, skip } query?, RequestOptionsoptions?): SkipLimit<ItemListResponse { id, createdAt, live, 7 more } >

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

Create Test Virtual Mailbox Item

client.printMail.virtualMailboxes.items.create(stringid, ItemCreateParams { description, matchedLetter, metadata } body, RequestOptionsoptions?): ItemCreateResponse { id, createdAt, live, 7 more }

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

Retrieve Virtual Mailbox Item

client.printMail.virtualMailboxes.items.retrieve(stringitemID, ItemRetrieveParams { id } params, RequestOptionsoptions?): ItemRetrieveResponse { id, createdAt, live, 7 more }

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

ModelsExpand Collapse

ItemListResponse { 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.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "virtual_mailbox_item"

Always “virtual_mailbox_item”.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

virtualMailbox: string

The ID of the virtual mailbox associated with this item.

description?: string

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

fileURL?: string

A URL of the envelope scan PDF.

matchedLetter?: string

The ID of the letter this item was matched to.

metadata?: Record<string, unknown>

See the section on Metadata.

ItemCreateResponse { 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.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "virtual_mailbox_item"

Always “virtual_mailbox_item”.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

virtualMailbox: string

The ID of the virtual mailbox associated with this item.

description?: string

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

fileURL?: string

A URL of the envelope scan PDF.

matchedLetter?: string

The ID of the letter this item was matched to.

metadata?: Record<string, unknown>

See the section on Metadata.

ItemRetrieveResponse { 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.

formatdate-time

live: boolean

true if this is a live mode resource else false.

object: "virtual_mailbox_item"

Always “virtual_mailbox_item”.

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

virtualMailbox: string

The ID of the virtual mailbox associated with this item.

description?: string

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

fileURL?: string

A URL of the envelope scan PDF.

matchedLetter?: string

The ID of the letter this item was matched to.

metadata?: Record<string, unknown>

See the section on Metadata.