# Return Envelopes ## Create Return Envelope `print_mail.return_envelopes.create(ReturnEnvelopeCreateParams**kwargs) -> ReturnEnvelope` **post** `/print-mail/v1/return_envelopes` Creates a new return envelope. Note that if there is already a return envelope for the destination contact, this will fail with a `return_envelope_already_exists_error`. ### Parameters - `to: To` A contact ID or a contact object containing the address that will be printed onto the return envelope. - `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. - `secret: Optional[bool]` 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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `str` - `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. - `idempotency_key: Optional[str]` ### Returns - `class ReturnEnvelope: …` - `id: str` A unique ID prefixed with return_envelope_ - `available: int` The number of return envelopes available to use in your orders immediately. This increases when a return envelope order is filled and decreases as you send orders which include this return envelope. - `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["return_envelope"]` Always `return_envelope`. - `"return_envelope"` - `to: To` The contact denormalized onto a return envelope when it is created. Unlike a full contact it is not a standalone resource, so it has no `object`, `live`, `createdAt`, or `updatedAt` fields. - `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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `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 ) return_envelope = client.print_mail.return_envelopes.create( to="contact_kFjQtFqJtRXgahx5vgc9mA", ) print(return_envelope.id) ``` #### Response ```json { "id": "return_envelope_7mhJUt25TnagyYzy1N81SJ", "object": "return_envelope", "live": false, "available": 0, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "addressStatus": "verified" }, "createdAt": "2021-12-16T03:06:17.419Z", "updatedAt": "2021-12-16T03:06:17.419Z" } ``` ## List Return Envelopes `print_mail.return_envelopes.list(ReturnEnvelopeListParams**kwargs) -> SyncSkipLimit[ReturnEnvelope]` **get** `/print-mail/v1/return_envelopes` Gets a list of return envelopes for the user. ### 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 ReturnEnvelope: …` - `id: str` A unique ID prefixed with return_envelope_ - `available: int` The number of return envelopes available to use in your orders immediately. This increases when a return envelope order is filled and decreases as you send orders which include this return envelope. - `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["return_envelope"]` Always `return_envelope`. - `"return_envelope"` - `to: To` The contact denormalized onto a return envelope when it is created. Unlike a full contact it is not a standalone resource, so it has no `object`, `live`, `createdAt`, or `updatedAt` fields. - `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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `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.return_envelopes.list() page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "return_envelope_7mhJUt25TnagyYzy1N81SJ", "object": "return_envelope", "live": false, "available": 0, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "addressStatus": "verified" }, "createdAt": "2021-12-16T03:06:17.419Z", "updatedAt": "2021-12-16T03:06:17.419Z" } ] } ``` ## Get Return Envelope `print_mail.return_envelopes.retrieve(strid) -> ReturnEnvelope` **get** `/print-mail/v1/return_envelopes/{id}` Gets the information for a return envelope by `id`. This should be a unique identifying string starting with `return_envelope_`. ### Parameters - `id: str` ### Returns - `class ReturnEnvelope: …` - `id: str` A unique ID prefixed with return_envelope_ - `available: int` The number of return envelopes available to use in your orders immediately. This increases when a return envelope order is filled and decreases as you send orders which include this return envelope. - `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["return_envelope"]` Always `return_envelope`. - `"return_envelope"` - `to: To` The contact denormalized onto a return envelope when it is created. Unlike a full contact it is not a standalone resource, so it has no `object`, `live`, `createdAt`, or `updatedAt` fields. - `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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `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 ) return_envelope = client.print_mail.return_envelopes.retrieve( "id", ) print(return_envelope.id) ``` #### Response ```json { "id": "return_envelope_7mhJUt25TnagyYzy1N81SJ", "object": "return_envelope", "live": false, "available": 0, "to": { "id": "contact_pxd7wnnD1xY6H6etKNvjb4", "companyName": "PostGrid", "addressLine1": "90 CANAL ST STE 600", "city": "BOSTON", "provinceOrState": "MA", "postalOrZip": "90210-1234", "countryCode": "US", "addressStatus": "verified" }, "createdAt": "2021-12-16T03:06:17.419Z", "updatedAt": "2021-12-16T03:06:17.419Z" } ``` ## Domain Types ### Return Envelope - `class ReturnEnvelope: …` - `id: str` A unique ID prefixed with return_envelope_ - `available: int` The number of return envelopes available to use in your orders immediately. This increases when a return envelope order is filled and decreases as you send orders which include this return envelope. - `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["return_envelope"]` Always `return_envelope`. - `"return_envelope"` - `to: To` The contact denormalized onto a return envelope when it is created. Unlike a full contact it is not a standalone resource, so it has no `object`, `live`, `createdAt`, or `updatedAt` fields. - `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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `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. # Orders ## Create Return Envelope Order `print_mail.return_envelopes.orders.create(strid, OrderCreateParams**kwargs) -> ReturnEnvelopeOrder` **post** `/print-mail/v1/return_envelopes/{id}/orders` Creates a batch order of return envelopes. The minimum order quantity is 5000. ### Parameters - `id: str` - `quantity_ordered: int` The quantity of return envelopes ordered. Minimum 5000. - `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. ### Returns - `class ReturnEnvelopeOrder: …` - `id: str` A unique ID prefixed with return_envelope_order_ - `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["return_envelope_order"]` Always `return_envelope_order`. - `"return_envelope_order"` - `quantity_ordered: int` The quantity of return envelopes ordered. Minimum 5000. - `return_envelope: ReturnEnvelope` The ID of the return envelope that this order replenishes. Expanded into the full return envelope object on the individual order retrieval and cancellation endpoints when `expand[]=returnEnvelope` is supplied. - `str` - `class ReturnEnvelope: …` - `id: str` A unique ID prefixed with return_envelope_ - `available: int` The number of return envelopes available to use in your orders immediately. This increases when a return envelope order is filled and decreases as you send orders which include this return envelope. - `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["return_envelope"]` Always `return_envelope`. - `"return_envelope"` - `to: To` The contact denormalized onto a return envelope when it is created. Unlike a full contact it is not a standalone resource, so it has no `object`, `live`, `createdAt`, or `updatedAt` fields. - `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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `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. - `status: Literal["placed", "filled", "cancelled"]` The status of a return envelope order. - `"placed"` - `"filled"` - `"cancelled"` - `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. - `quantity_filled: Optional[int]` The quantity of return envelopes that were filled for this order. Only returned once the order's status is `filled`. ### 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 ) return_envelope_order = client.print_mail.return_envelopes.orders.create( id="id", quantity_ordered=5000, description="A batch of 5000", ) print(return_envelope_order.id) ``` #### Response ```json { "id": "return_envelope_order_cJhFxQhs69MGhxu3L5NvyA", "object": "return_envelope_order", "live": false, "returnEnvelope": "return_envelope_7mhJUt25TnagyYzy1N81SJ", "quantityOrdered": 5000, "status": "placed", "createdAt": "2021-12-16T03:23:22.617Z", "updatedAt": "2021-12-16T03:23:22.617Z" } ``` ## List Return Envelope Orders `print_mail.return_envelopes.orders.list(strid, OrderListParams**kwargs) -> SyncSkipLimit[ReturnEnvelopeOrder]` **get** `/print-mail/v1/return_envelopes/{id}/orders` Gets a list of orders for the return envelope by `id`. ### 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 ReturnEnvelopeOrder: …` - `id: str` A unique ID prefixed with return_envelope_order_ - `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["return_envelope_order"]` Always `return_envelope_order`. - `"return_envelope_order"` - `quantity_ordered: int` The quantity of return envelopes ordered. Minimum 5000. - `return_envelope: ReturnEnvelope` The ID of the return envelope that this order replenishes. Expanded into the full return envelope object on the individual order retrieval and cancellation endpoints when `expand[]=returnEnvelope` is supplied. - `str` - `class ReturnEnvelope: …` - `id: str` A unique ID prefixed with return_envelope_ - `available: int` The number of return envelopes available to use in your orders immediately. This increases when a return envelope order is filled and decreases as you send orders which include this return envelope. - `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["return_envelope"]` Always `return_envelope`. - `"return_envelope"` - `to: To` The contact denormalized onto a return envelope when it is created. Unlike a full contact it is not a standalone resource, so it has no `object`, `live`, `createdAt`, or `updatedAt` fields. - `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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `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. - `status: Literal["placed", "filled", "cancelled"]` The status of a return envelope order. - `"placed"` - `"filled"` - `"cancelled"` - `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. - `quantity_filled: Optional[int]` The quantity of return envelopes that were filled for this order. Only returned once the order's status is `filled`. ### 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.return_envelopes.orders.list( id="id", ) page = page.data[0] print(page.id) ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "return_envelope_order_cJhFxQhs69MGhxu3L5NvyA", "object": "return_envelope_order", "live": false, "returnEnvelope": "return_envelope_7mhJUt25TnagyYzy1N81SJ", "quantityOrdered": 5000, "status": "placed", "createdAt": "2021-12-16T03:23:22.617Z", "updatedAt": "2021-12-16T03:23:22.617Z" } ] } ``` ## Get Return Envelope Order `print_mail.return_envelopes.orders.retrieve(strorder_id, OrderRetrieveParams**kwargs) -> ReturnEnvelopeOrder` **get** `/print-mail/v1/return_envelopes/{id}/orders/{orderID}` Gets a specific return envelope order by return envelope ID as `id` and return envelope order ID as `orderID`. ### Parameters - `id: str` - `order_id: str` - `expand: Optional[List[Literal["returnEnvelope"]]]` Pass `expand[]=returnEnvelope` to expand the order's `returnEnvelope` field into the full return envelope object. - `"returnEnvelope"` ### Returns - `class ReturnEnvelopeOrder: …` - `id: str` A unique ID prefixed with return_envelope_order_ - `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["return_envelope_order"]` Always `return_envelope_order`. - `"return_envelope_order"` - `quantity_ordered: int` The quantity of return envelopes ordered. Minimum 5000. - `return_envelope: ReturnEnvelope` The ID of the return envelope that this order replenishes. Expanded into the full return envelope object on the individual order retrieval and cancellation endpoints when `expand[]=returnEnvelope` is supplied. - `str` - `class ReturnEnvelope: …` - `id: str` A unique ID prefixed with return_envelope_ - `available: int` The number of return envelopes available to use in your orders immediately. This increases when a return envelope order is filled and decreases as you send orders which include this return envelope. - `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["return_envelope"]` Always `return_envelope`. - `"return_envelope"` - `to: To` The contact denormalized onto a return envelope when it is created. Unlike a full contact it is not a standalone resource, so it has no `object`, `live`, `createdAt`, or `updatedAt` fields. - `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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `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. - `status: Literal["placed", "filled", "cancelled"]` The status of a return envelope order. - `"placed"` - `"filled"` - `"cancelled"` - `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. - `quantity_filled: Optional[int]` The quantity of return envelopes that were filled for this order. Only returned once the order's status is `filled`. ### 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 ) return_envelope_order = client.print_mail.return_envelopes.orders.retrieve( order_id="orderID", id="id", ) print(return_envelope_order.id) ``` #### Response ```json { "id": "return_envelope_order_cJhFxQhs69MGhxu3L5NvyA", "object": "return_envelope_order", "live": false, "returnEnvelope": "return_envelope_7mhJUt25TnagyYzy1N81SJ", "quantityOrdered": 5000, "status": "placed", "createdAt": "2021-12-16T03:23:22.617Z", "updatedAt": "2021-12-16T03:23:22.617Z" } ``` ## Fill Test Return Envelope Order `print_mail.return_envelopes.orders.fill(strorder_id, OrderFillParams**kwargs) -> ReturnEnvelopeOrder` **post** `/print-mail/v1/return_envelopes/{id}/orders/{orderID}/fills` Fills the return envelope order by `orderID` for the return envelope by `id`. This is only available in test mode and can be used to simulate how a live order would be filled. Note: this will fail with a `return_envelope_order_cannot_fill_error` if the order's status is not `placed`. ### Parameters - `id: str` - `order_id: str` ### Returns - `class ReturnEnvelopeOrder: …` - `id: str` A unique ID prefixed with return_envelope_order_ - `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["return_envelope_order"]` Always `return_envelope_order`. - `"return_envelope_order"` - `quantity_ordered: int` The quantity of return envelopes ordered. Minimum 5000. - `return_envelope: ReturnEnvelope` The ID of the return envelope that this order replenishes. Expanded into the full return envelope object on the individual order retrieval and cancellation endpoints when `expand[]=returnEnvelope` is supplied. - `str` - `class ReturnEnvelope: …` - `id: str` A unique ID prefixed with return_envelope_ - `available: int` The number of return envelopes available to use in your orders immediately. This increases when a return envelope order is filled and decreases as you send orders which include this return envelope. - `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["return_envelope"]` Always `return_envelope`. - `"return_envelope"` - `to: To` The contact denormalized onto a return envelope when it is created. Unlike a full contact it is not a standalone resource, so it has no `object`, `live`, `createdAt`, or `updatedAt` fields. - `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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `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. - `status: Literal["placed", "filled", "cancelled"]` The status of a return envelope order. - `"placed"` - `"filled"` - `"cancelled"` - `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. - `quantity_filled: Optional[int]` The quantity of return envelopes that were filled for this order. Only returned once the order's status is `filled`. ### 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 ) return_envelope_order = client.print_mail.return_envelopes.orders.fill( order_id="orderID", id="id", ) print(return_envelope_order.id) ``` #### Response ```json { "id": "return_envelope_order_cJhFxQhs69MGhxu3L5NvyA", "object": "return_envelope_order", "live": false, "returnEnvelope": "return_envelope_7mhJUt25TnagyYzy1N81SJ", "quantityOrdered": 5000, "status": "filled", "createdAt": "2021-12-16T03:23:22.617Z", "updatedAt": "2021-12-16T03:23:22.617Z", "quantityFilled": 5000 } ``` ## Cancel Return Envelope Order `print_mail.return_envelopes.orders.cancel(strorder_id, OrderCancelParams**kwargs) -> ReturnEnvelopeOrder` **delete** `/print-mail/v1/return_envelopes/{id}/orders/{orderID}` Cancels the return envelope order by `orderID` for the return envelope by `id`. Note that this operation cannot be undone. ### Parameters - `id: str` - `order_id: str` - `expand: Optional[List[Literal["returnEnvelope"]]]` Pass `expand[]=returnEnvelope` to expand the order's `returnEnvelope` field into the full return envelope object. - `"returnEnvelope"` ### Returns - `class ReturnEnvelopeOrder: …` - `id: str` A unique ID prefixed with return_envelope_order_ - `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["return_envelope_order"]` Always `return_envelope_order`. - `"return_envelope_order"` - `quantity_ordered: int` The quantity of return envelopes ordered. Minimum 5000. - `return_envelope: ReturnEnvelope` The ID of the return envelope that this order replenishes. Expanded into the full return envelope object on the individual order retrieval and cancellation endpoints when `expand[]=returnEnvelope` is supplied. - `str` - `class ReturnEnvelope: …` - `id: str` A unique ID prefixed with return_envelope_ - `available: int` The number of return envelopes available to use in your orders immediately. This increases when a return envelope order is filled and decreases as you send orders which include this return envelope. - `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["return_envelope"]` Always `return_envelope`. - `"return_envelope"` - `to: To` The contact denormalized onto a return envelope when it is created. Unlike a full contact it is not a standalone resource, so it has no `object`, `live`, `createdAt`, or `updatedAt` fields. - `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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `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. - `status: Literal["placed", "filled", "cancelled"]` The status of a return envelope order. - `"placed"` - `"filled"` - `"cancelled"` - `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. - `quantity_filled: Optional[int]` The quantity of return envelopes that were filled for this order. Only returned once the order's status is `filled`. ### 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 ) return_envelope_order = client.print_mail.return_envelopes.orders.cancel( order_id="orderID", id="id", ) print(return_envelope_order.id) ``` #### Response ```json { "id": "return_envelope_order_cJhFxQhs69MGhxu3L5NvyA", "object": "return_envelope_order", "live": false, "returnEnvelope": "return_envelope_7mhJUt25TnagyYzy1N81SJ", "quantityOrdered": 5000, "status": "cancelled", "createdAt": "2021-12-16T03:23:22.617Z", "updatedAt": "2021-12-16T03:23:22.617Z" } ``` ## Domain Types ### Return Envelope Order - `class ReturnEnvelopeOrder: …` - `id: str` A unique ID prefixed with return_envelope_order_ - `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["return_envelope_order"]` Always `return_envelope_order`. - `"return_envelope_order"` - `quantity_ordered: int` The quantity of return envelopes ordered. Minimum 5000. - `return_envelope: ReturnEnvelope` The ID of the return envelope that this order replenishes. Expanded into the full return envelope object on the individual order retrieval and cancellation endpoints when `expand[]=returnEnvelope` is supplied. - `str` - `class ReturnEnvelope: …` - `id: str` A unique ID prefixed with return_envelope_ - `available: int` The number of return envelopes available to use in your orders immediately. This increases when a return envelope order is filled and decreases as you send orders which include this return envelope. - `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["return_envelope"]` Always `return_envelope`. - `"return_envelope"` - `to: To` The contact denormalized onto a return envelope when it is created. Unlike a full contact it is not a standalone resource, so it has no `object`, `live`, `createdAt`, or `updatedAt` fields. - `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. - `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. - `secret: Optional[bool]` 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. - `skip_verification: Optional[bool]` If `true`, PostGrid will skip running this contact's address through our address verification system. - `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. - `status: Literal["placed", "filled", "cancelled"]` The status of a return envelope order. - `"placed"` - `"filled"` - `"cancelled"` - `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. - `quantity_filled: Optional[int]` The quantity of return envelopes that were filled for this order. Only returned once the order's status is `filled`.