API Reference

Print Mail

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Return Envelopes

You can use the return envelopes API to create and manage return envelopes. These are envelopes that are sent along with your mail (if specified) and allow your recipients to send mail to a particular address without having to purchase their own envelopes/stamps.

Note that you must order return envelopes and wait for the order to be filled before you can use them. You can manage these return envelope orders via the API as well as the dashboard.

Create Return Envelope

print_mail.return_envelopes.create(ReturnEnvelopeCreateParams**kwargs) -> ReturnEnvelope

POST/print-mail/v1/return_envelopes

List Return Envelopes

print_mail.return_envelopes.list(ReturnEnvelopeListParams**kwargs) -> SyncSkipLimit[ReturnEnvelope]

GET/print-mail/v1/return_envelopes

Get Return Envelope

print_mail.return_envelopes.retrieve(strid) -> ReturnEnvelope

GET/print-mail/v1/return_envelopes/{id}

ModelsExpand Collapse

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.

formatint32

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["return_envelope"]

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

One of the following:

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

formatdate-time

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.

Return EnvelopesOrders

You can use the return envelopes API to create and manage return envelopes. These are envelopes that are sent along with your mail (if specified) and allow your recipients to send mail to a particular address without having to purchase their own envelopes/stamps.

Note that you must order return envelopes and wait for the order to be filled before you can use them. You can manage these return envelope orders via the API as well as the dashboard.

Create Return Envelope Order

print_mail.return_envelopes.orders.create(strid, OrderCreateParams**kwargs) -> ReturnEnvelopeOrder

POST/print-mail/v1/return_envelopes/{id}/orders

List Return Envelope Orders

print_mail.return_envelopes.orders.list(strid, OrderListParams**kwargs) -> SyncSkipLimit[ReturnEnvelopeOrder]

GET/print-mail/v1/return_envelopes/{id}/orders

Get Return Envelope Order

print_mail.return_envelopes.orders.retrieve(strorder_id, OrderRetrieveParams**kwargs) -> ReturnEnvelopeOrder

GET/print-mail/v1/return_envelopes/{id}/orders/{orderID}

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

Cancel Return Envelope Order

print_mail.return_envelopes.orders.cancel(strorder_id, OrderCancelParams**kwargs) -> ReturnEnvelopeOrder

DELETE/print-mail/v1/return_envelopes/{id}/orders/{orderID}

ModelsExpand Collapse

class ReturnEnvelopeOrder: …

id: str

A unique ID prefixed with return_envelope_order_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["return_envelope_order"]

Always return_envelope_order.

quantity_ordered: int

The quantity of return envelopes ordered. Minimum 5000.

formatint32

minimum5000

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.

One of the following:

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.

formatint32

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

object: Literal["return_envelope"]

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

One of the following:

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

formatdate-time

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.

One of the following:

"placed"

"filled"

"cancelled"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

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.

formatint32