## Create Virtual Mailbox `print_mail.virtual_mailboxes.create(VirtualMailboxCreateParams**kwargs) -> VirtualMailboxCreateResponse` **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. ### Parameters - `country_code: Literal["US"]` All of the supported countries for virtual mailboxes. - `"US"` - `capabilities: Optional[Capabilities]` The capabilities the virtual mailbox should support. - `envelope_scans: bool` If the virtual mailbox should support envelope scans or not. - `forward_mail_to: Optional[CapabilitiesForwardMailTo]` A contact ID or contact object. - `class ContactCreateWithFirstName: …` - `address_line1: str` The first line of the contact's address. - `country_code: str` The ISO 3611-1 country code of the contact's address. - `first_name: str` - `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. - `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. - `class ContactCreateWithCompanyName: …` - `address_line1: str` The first line of the contact's address. - `company_name: str` - `country_code: str` The ISO 3611-1 country code of the contact's address. - `address_line2: Optional[str]` Second line of the contact's address, if applicable. - `city: Optional[str]` The city of the contact's address. - `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. - `str` ### Returns - `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`. - `"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. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["contact"]` Always `contact`. - `"contact"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `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. - `"US"` - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["virtual_mailbox"]` Always "virtual_mailbox". - `"virtual_mailbox"` - `status: Literal["active", "pending_assignment"]` The possible statuses of virtual mailboxes. - `"active"` - `"pending_assignment"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `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. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) virtual_mailbox = client.print_mail.virtual_mailboxes.create( country_code="US", capabilities={ "envelope_scans": True, "forward_mail_to": "contact_pxd7wnnD1xY6H6etKNvjb4", }, ) print(virtual_mailbox.id) ``` #### 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" } ```