---
title: "Create Virtual Mailbox"
method: POST
path: "/print-mail/v1/virtual_mailboxes"
tags: ["Virtual Mailboxes"]
---

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

## Request body

- VirtualMailboxCreate
  - `capabilities` object — The capabilities the virtual mailbox should support.
    - `envelopeScans` boolean, required — If the virtual mailbox should support envelope scans or not.
    - `forwardMailTo` union — A contact ID or contact object.
      - union
        - ContactCreateWithFirstName
          - `addressLine1` string, required — The first line of the contact's address.
          - `addressLine2` string — Second line of the contact's address, if applicable.
          - `city` string — The city of the contact's address.
          - `provinceOrState` string — Province or state of the contact's address.
          - `postalOrZip` string — The postal or ZIP code of the contact's address.
          - `countryCode` string, required — The ISO 3611-1 country code of the contact's address.
          - `companyName` string — Company name of the contact.
          - `lastName` string — Last name of the contact.
          - `email` string — Email of the contact.
          - `phoneNumber` string — Phone number of the contact.
          - `jobTitle` string — Job title of the contact.
          - `skipVerification` boolean — If `true`, PostGrid will skip running this contact's address through our address verification system.
          - `forceVerifiedStatus` boolean — If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
          - `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.
          - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard.
          - `metadata` object — See the section on Metadata.
          - `firstName` string, required
        - ContactCreateWithCompanyName
          - `addressLine1` string, required — The first line of the contact's address.
          - `addressLine2` string — Second line of the contact's address, if applicable.
          - `city` string — The city of the contact's address.
          - `provinceOrState` string — Province or state of the contact's address.
          - `postalOrZip` string — The postal or ZIP code of the contact's address.
          - `countryCode` string, required — The ISO 3611-1 country code of the contact's address.
          - `firstName` string — First name of the contact.
          - `lastName` string — Last name of the contact.
          - `email` string — Email of the contact.
          - `phoneNumber` string — Phone number of the contact.
          - `jobTitle` string — Job title of the contact.
          - `skipVerification` boolean — If `true`, PostGrid will skip running this contact's address through our address verification system.
          - `forceVerifiedStatus` boolean — If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.
          - `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.
          - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard.
          - `metadata` object — See the section on Metadata.
          - `companyName` string, required
      - string
  - `countryCode` 'US', required — All of the supported countries for virtual mailboxes.

## Response `201`

The request has succeeded and a new resource has been created as a result.

- VirtualMailbox — The virtual mailbox object.
  - `id` string, required — A unique ID prefixed with virtual_mailbox_
  - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard.
  - `metadata` object — See the section on Metadata.
  - `live` boolean, required — `true` if this is a live mode resource else `false`.
  - `createdAt` string, date-time, required — The UTC time at which this resource was created.
  - `updatedAt` string, date-time, required — The UTC time at which this resource was last updated.
  - `object` 'virtual_mailbox', required — Always "virtual_mailbox".
  - `capabilities` VirtualMailboxCapabilities, required — All of the capabilities a virtual mailbox may have.
    - `envelopeScans` boolean, required — Indicates if the virtual mailbox can produce scans of envelopes.
    - `forwardMailTo` Contact
      - `id` string, required — A unique ID prefixed with contact_
      - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard.
      - `metadata` object — See the section on Metadata.
      - `live` boolean, required — `true` if this is a live mode resource else `false`.
      - `createdAt` string, date-time, required — The UTC time at which this resource was created.
      - `updatedAt` string, date-time, required — The UTC time at which this resource was last updated.
  - `status` 'active' | 'pending_assignment', required — The possible statuses of virtual mailboxes.
  - `countryCode` 'US', required — All of the supported countries for virtual mailboxes.

## Other responses

- `400` — The server could not understand the request due to invalid syntax.
- `401` — Access is unauthorized.
- `404` — The server cannot find the requested resource.
- `422` — Client error
- `429` — Client error
- `500` — Server error

---

[API](https://skmtc.net/postgrid/apis/postgrid-address-verification-api.md) · [All operations](https://skmtc.net/postgrid/apis/postgrid-address-verification-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/postgrid/postgrid-address-verification-api/versions/537d2bbc624a/schema)