## 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 Parameters - `countryCode: "US"` All of the supported countries for virtual mailboxes. - `"US"` - `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 or ContactCreateWithCompanyName or string` A contact ID or contact object. - `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 13 more }` - `addressLine1: string` The first line of the contact's address. - `countryCode: string` The ISO 3611-1 country code 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. - `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. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 13 more }` - `addressLine1: string` The first line of the contact's address. - `companyName: string` - `countryCode: string` The ISO 3611-1 country code of the contact's address. - `addressLine2: optional string` Second line of the contact's address, if applicable. - `city: optional string` The city of the contact's address. - `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. - `skipVerification: optional boolean` If `true`, PostGrid will skip running this contact's address through our address verification system. - `string` ### Returns - `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` 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`. - `"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. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "contact"` Always `contact`. - `"contact"` - `updatedAt: string` The UTC time at which this resource was last updated. - `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. - `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. - `"US"` - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "virtual_mailbox"` Always "virtual_mailbox". - `"virtual_mailbox"` - `status: "active" or "pending_assignment"` The possible statuses of virtual mailboxes. - `"active"` - `"pending_assignment"` - `updatedAt: string` The UTC time at which this resource was last updated. - `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. ### Example ```http 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" }' ``` #### Response ```json { "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" } ```