API Reference

Print Mail

Virtual Mailboxes

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create Virtual Mailbox

POST/print-mail/v1/virtual_mailboxes

Creates a new virtual mailbox. In live mode, the virtual mailbox will be pending assignment and cannot be used until it has been assigned and activated by our team. You will be notified via email once the virtual mailbox has been activated. In test mode, the virtual mailbox will be activated immediately upon creation.

Body ParametersJSONExpand Collapse

countryCode: "US"

All of the supported countries for virtual mailboxes.

attention: optional string

An optional attention line printed above the name for returned mail, such as a department. Cannot be combined with careOf.

capabilities: optional object { envelopeScans, forwardMailTo }

The capabilities the virtual mailbox should support.

envelopeScans: boolean

If the virtual mailbox should support envelope scans or not.

forwardMailTo: optional ContactCreateWithFirstName { addressLine1, firstName, addressLine2, 14 more } or ContactCreateWithCompanyName { addressLine1, companyName, addressLine2, 14 more } or string

A contact provided in one of two ways:

• an inline contact body with the same fields you would use to create a contact (there is no need to create the contact first), or
• the ID of an existing contact (e.g. contact_123).

You never send the full stored contact object (with id, object, addressStatus, createdAt, etc.) here — that shape is only ever returned in responses.

One of the following:

ContactCreateWithFirstName object { addressLine1, firstName, addressLine2, 14 more }

addressLine1: string

The first line of the contact’s address.

firstName: string

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.

countryCode: optional string

The ISO 3611-1 country code of the contact’s address. If omitted, your organization’s default country code is used.

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.

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.

secret: optional 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: optional boolean

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

ContactCreateWithCompanyName object { addressLine1, companyName, addressLine2, 14 more }

addressLine1: string

The first line of the contact’s address.

companyName: string

addressLine2: optional string

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

city: optional string

The city of the contact’s address.

countryCode: optional string

The ISO 3611-1 country code of the contact’s address. If omitted, your organization’s default country code is used.

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.

secret: optional 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: optional boolean

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

string

careOf: optional string

An optional care-of line printed above the name for returned mail. Cannot be combined with attention.

ReturnsExpand Collapse

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 { 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" or "corrected" or "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: 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.

secret: optional 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: 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.

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

attention: optional string

An optional attention line printed above the name for returned mail, such as a department. Cannot be combined with careOf.

careOf: optional string

An optional care-of line printed above the name for returned mail. Cannot be combined with attention.

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.

Create Virtual Mailbox

HTTP

HTTP

TypeScript

Python

curl https://api.postgrid.com/print-mail/v1/virtual_mailboxes \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
    -d '{
          "countryCode": "US"
        }'

201 example

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

201 example

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