# Virtual Mailboxes ## 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" } ``` ## List Virtual Mailboxes `print_mail.virtual_mailboxes.list(VirtualMailboxListParams**kwargs) -> SyncSkipLimit[VirtualMailboxListResponse]` **get** `/print-mail/v1/virtual_mailboxes` Lists virtual mailboxes. You can use the `skip`, `limit`, and `search` query parameters to refine the list. ### Parameters - `limit: Optional[int]` - `search: Optional[str]` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: Optional[int]` ### Returns - `class VirtualMailboxListResponse: …` 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 ) page = client.print_mail.virtual_mailboxes.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "totalCount": 1, "skip": 0, "limit": 10, "data": [ { "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" } ] } ``` ## Retrieve Virtual Mailbox `print_mail.virtual_mailboxes.retrieve(strid) -> VirtualMailboxRetrieveResponse` **get** `/print-mail/v1/virtual_mailboxes/{id}` Retrieve Virtual Mailbox ### Parameters - `id: str` ### Returns - `class VirtualMailboxRetrieveResponse: …` 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.retrieve( "id", ) 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" } ``` ## Retrieve Physical Address `print_mail.virtual_mailboxes.retrieve_address(strid) -> VirtualMailboxRetrieveAddressResponse` **get** `/print-mail/v1/virtual_mailboxes/{id}/address` Retrieves the physical address of the virtual mailbox. ### Parameters - `id: str` ### Returns - `class VirtualMailboxRetrieveAddressResponse: …` The address information for a mailbox. - `address_line1: str` The address line 1 of the mailbox. - `country_code: Literal["US"]` All of the supported countries for virtual mailboxes. - `"US"` - `address_line2: Optional[str]` The address line 2 of the mailbox. - `city: Optional[str]` The city of the mailbox. - `postal_or_zip: Optional[str]` The postal or ZIP code of the mailbox. - `province_or_state: Optional[str]` The province or state of the mailbox. ### 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 ) response = client.print_mail.virtual_mailboxes.retrieve_address( "id", ) print(response.address_line1) ``` #### Response ```json { "addressLine1": "145 Mulberry st", "city": "New York", "provinceOrState": "NY", "postalOrZip": "10013", "countryCode": "US" } ``` ## Domain Types ### Virtual Mailbox Create Response - `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. ### Virtual Mailbox List Response - `class VirtualMailboxListResponse: …` 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. ### Virtual Mailbox Retrieve Response - `class VirtualMailboxRetrieveResponse: …` 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. ### Virtual Mailbox Retrieve Address Response - `class VirtualMailboxRetrieveAddressResponse: …` The address information for a mailbox. - `address_line1: str` The address line 1 of the mailbox. - `country_code: Literal["US"]` All of the supported countries for virtual mailboxes. - `"US"` - `address_line2: Optional[str]` The address line 2 of the mailbox. - `city: Optional[str]` The city of the mailbox. - `postal_or_zip: Optional[str]` The postal or ZIP code of the mailbox. - `province_or_state: Optional[str]` The province or state of the mailbox. # Items ## List Virtual Mailbox Items `print_mail.virtual_mailboxes.items.list(strid, ItemListParams**kwargs) -> SyncSkipLimit[ItemListResponse]` **get** `/print-mail/v1/virtual_mailboxes/{id}/items` Lists items for a virtual mailbox. ### Parameters - `id: str` - `limit: Optional[int]` - `search: Optional[str]` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: Optional[int]` ### Returns - `class ItemListResponse: …` The virtual mailbox item object. - `id: str` A unique ID prefixed with virtual_mailbox_item_ - `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_item"]` Always "virtual_mailbox_item". - `"virtual_mailbox_item"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `virtual_mailbox: str` The ID of the virtual mailbox associated with this item. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `file_url: Optional[str]` A URL of the envelope scan PDF. - `matched_letter: Optional[str]` The ID of the letter this item was matched to. - `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 ) page = client.print_mail.virtual_mailboxes.items.list( id="id", ) page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "totalCount": 1, "skip": 0, "limit": 10, "data": [ { "id": "virtual_mailbox_item_abcdefg123456890", "object": "virtual_mailbox_item", "live": true, "virtualMailbox": "virtual_mailbox_abcdefg123456890", "fileURL": "https://postgrid.com", "matchedLetter": "letter_abcdef1234567890", "createdAt": "2025-11-01T15:08:41.052Z", "updatedAt": "2025-11-01T15:08:41.052Z" } ] } ``` ## Create Test Virtual Mailbox Item `print_mail.virtual_mailboxes.items.create(strid, ItemCreateParams**kwargs) -> ItemCreateResponse` **post** `/print-mail/v1/virtual_mailboxes/{id}/items` Create a test item for a virtual mailbox. This is only available in test mode, an error will be returned if you attempt this call in live mode. ### Parameters - `id: str` - `description: Optional[str]` The description of the item. - `matched_letter: Optional[str]` The ID of a letter to match this test item to. - `metadata: Optional[Dict[str, object]]` The metadata of the item. ### Returns - `class ItemCreateResponse: …` The virtual mailbox item object. - `id: str` A unique ID prefixed with virtual_mailbox_item_ - `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_item"]` Always "virtual_mailbox_item". - `"virtual_mailbox_item"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `virtual_mailbox: str` The ID of the virtual mailbox associated with this item. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `file_url: Optional[str]` A URL of the envelope scan PDF. - `matched_letter: Optional[str]` The ID of the letter this item was matched to. - `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 ) item = client.print_mail.virtual_mailboxes.items.create( id="id", matched_letter="letter_abcdef1234567890", ) print(item.id) ``` #### Response ```json { "id": "virtual_mailbox_item_abcdefg123456890", "object": "virtual_mailbox_item", "live": false, "virtualMailbox": "virtual_mailbox_abcdefg123456890", "fileURL": "https://postgrid.com", "matchedLetter": "letter_abcdef1234567890", "createdAt": "2025-11-01T15:08:41.052Z", "updatedAt": "2025-11-01T15:08:41.052Z" } ``` ## Retrieve Virtual Mailbox Item `print_mail.virtual_mailboxes.items.retrieve(stritem_id, ItemRetrieveParams**kwargs) -> ItemRetrieveResponse` **get** `/print-mail/v1/virtual_mailboxes/{id}/items/{itemID}` Retrieves a single item for a virtual mailbox. ### Parameters - `id: str` - `item_id: str` ### Returns - `class ItemRetrieveResponse: …` The virtual mailbox item object. - `id: str` A unique ID prefixed with virtual_mailbox_item_ - `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_item"]` Always "virtual_mailbox_item". - `"virtual_mailbox_item"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `virtual_mailbox: str` The ID of the virtual mailbox associated with this item. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `file_url: Optional[str]` A URL of the envelope scan PDF. - `matched_letter: Optional[str]` The ID of the letter this item was matched to. - `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 ) item = client.print_mail.virtual_mailboxes.items.retrieve( item_id="itemID", id="id", ) print(item.id) ``` #### Response ```json { "id": "virtual_mailbox_item_abcdefg123456890", "object": "virtual_mailbox_item", "live": true, "virtualMailbox": "virtual_mailbox_abcdefg123456890", "fileURL": "https://postgrid.com", "matchedLetter": "letter_abcdef1234567890", "createdAt": "2025-11-01T15:08:41.052Z", "updatedAt": "2025-11-01T15:08:41.052Z" } ``` ## Domain Types ### Item List Response - `class ItemListResponse: …` The virtual mailbox item object. - `id: str` A unique ID prefixed with virtual_mailbox_item_ - `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_item"]` Always "virtual_mailbox_item". - `"virtual_mailbox_item"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `virtual_mailbox: str` The ID of the virtual mailbox associated with this item. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `file_url: Optional[str]` A URL of the envelope scan PDF. - `matched_letter: Optional[str]` The ID of the letter this item was matched to. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Item Create Response - `class ItemCreateResponse: …` The virtual mailbox item object. - `id: str` A unique ID prefixed with virtual_mailbox_item_ - `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_item"]` Always "virtual_mailbox_item". - `"virtual_mailbox_item"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `virtual_mailbox: str` The ID of the virtual mailbox associated with this item. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `file_url: Optional[str]` A URL of the envelope scan PDF. - `matched_letter: Optional[str]` The ID of the letter this item was matched to. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Item Retrieve Response - `class ItemRetrieveResponse: …` The virtual mailbox item object. - `id: str` A unique ID prefixed with virtual_mailbox_item_ - `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_item"]` Always "virtual_mailbox_item". - `"virtual_mailbox_item"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `virtual_mailbox: str` The ID of the virtual mailbox associated with this item. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `file_url: Optional[str]` A URL of the envelope scan PDF. - `matched_letter: Optional[str]` The ID of the letter this item was matched to. - `metadata: Optional[Dict[str, object]]` See the section on Metadata.