# Return Envelopes

## Create Return Envelope

**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`.

### Header Parameters

- `"idempotency-key": optional string`

### Body Parameters

- `to: ContactCreateWithFirstName or ContactCreateWithCompanyName or string`

  A contact ID or a contact object containing the address that will be
  printed onto the return envelope.

  - `ContactCreateWithFirstName object { addressLine1, countryCode, firstName, 14 more }`

    - `addressLine1: string`

      The first line of the contact's address.

    - `countryCode: string`

      The ISO 3611-1 country code of the contact's address.

    - `firstName: string`

    - `addressLine2: optional string`

      Second line of the contact's address, if applicable.

    - `city: optional string`

      The city of the contact's address.

    - `companyName: optional string`

      Company name of the contact.

    - `description: optional string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email: optional string`

      Email of the contact.

    - `forceVerifiedStatus: optional boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle: optional string`

      Job title of the contact.

    - `lastName: optional string`

      Last name of the contact.

    - `metadata: optional map[unknown]`

      See the section on Metadata.

    - `phoneNumber: optional string`

      Phone number of the contact.

    - `postalOrZip: optional string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState: optional string`

      Province or state of the contact's address.

    - `secret: optional boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification: optional boolean`

      If `true`, PostGrid will skip running this contact's address through our address verification system.

  - `ContactCreateWithCompanyName object { addressLine1, companyName, countryCode, 14 more }`

    - `addressLine1: string`

      The first line of the contact's address.

    - `companyName: string`

    - `countryCode: string`

      The ISO 3611-1 country code of the contact's address.

    - `addressLine2: optional string`

      Second line of the contact's address, if applicable.

    - `city: optional string`

      The city of the contact's address.

    - `description: optional string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email: optional string`

      Email of the contact.

    - `firstName: optional string`

      First name of the contact.

    - `forceVerifiedStatus: optional boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle: optional string`

      Job title of the contact.

    - `lastName: optional string`

      Last name of the contact.

    - `metadata: optional map[unknown]`

      See the section on Metadata.

    - `phoneNumber: optional string`

      Phone number of the contact.

    - `postalOrZip: optional string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState: optional string`

      Province or state of the contact's address.

    - `secret: optional boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification: optional boolean`

      If `true`, PostGrid will skip running this contact's address through our address verification system.

  - `string`

- `description: optional string`

  An optional string describing this resource. Will be visible in the API and the dashboard.

- `metadata: optional map[unknown]`

  See the section on Metadata.

### Returns

- `ReturnEnvelope object { id, available, createdAt, 6 more }`

  - `id: string`

    A unique ID prefixed with return_envelope_

  - `available: number`

    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.

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope"`

    Always `return_envelope`.

    - `"return_envelope"`

  - `to: object { id, addressLine1, addressStatus, 17 more }`

    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: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" or "corrected" or "failed"`

      One of `verified`, `corrected`, or `failed`.

      - `"verified"`

      - `"corrected"`

      - `"failed"`

    - `countryCode: string`

      The ISO 3611-1 country code of the contact's address.

    - `addressErrors: optional string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2: optional string`

      Second line of the contact's address, if applicable.

    - `city: optional string`

      The city of the contact's address.

    - `companyName: optional string`

      Company name of the contact.

    - `description: optional string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email: optional string`

      Email of the contact.

    - `firstName: optional string`

      First name of the contact.

    - `forceVerifiedStatus: optional boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle: optional string`

      Job title of the contact.

    - `lastName: optional string`

      Last name of the contact.

    - `metadata: optional map[unknown]`

      See the section on Metadata.

    - `phoneNumber: optional string`

      Phone number of the contact.

    - `postalOrZip: optional string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState: optional string`

      Province or state of the contact's address.

    - `secret: optional boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification: optional boolean`

      If `true`, PostGrid will skip running this contact's address through our address verification system.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/return_envelopes \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
    -d '{
          "to": "contact_kFjQtFqJtRXgahx5vgc9mA"
        }'
```

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

**get** `/print-mail/v1/return_envelopes`

Gets a list of return envelopes for the user.

### Query Parameters

- `limit: optional number`

- `search: optional string`

  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 number`

### Returns

- `data: array of ReturnEnvelope`

  - `id: string`

    A unique ID prefixed with return_envelope_

  - `available: number`

    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.

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope"`

    Always `return_envelope`.

    - `"return_envelope"`

  - `to: object { id, addressLine1, addressStatus, 17 more }`

    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: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" or "corrected" or "failed"`

      One of `verified`, `corrected`, or `failed`.

      - `"verified"`

      - `"corrected"`

      - `"failed"`

    - `countryCode: string`

      The ISO 3611-1 country code of the contact's address.

    - `addressErrors: optional string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2: optional string`

      Second line of the contact's address, if applicable.

    - `city: optional string`

      The city of the contact's address.

    - `companyName: optional string`

      Company name of the contact.

    - `description: optional string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email: optional string`

      Email of the contact.

    - `firstName: optional string`

      First name of the contact.

    - `forceVerifiedStatus: optional boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle: optional string`

      Job title of the contact.

    - `lastName: optional string`

      Last name of the contact.

    - `metadata: optional map[unknown]`

      See the section on Metadata.

    - `phoneNumber: optional string`

      Phone number of the contact.

    - `postalOrZip: optional string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState: optional string`

      Province or state of the contact's address.

    - `secret: optional boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification: optional boolean`

      If `true`, PostGrid will skip running this contact's address through our address verification system.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

- `limit: number`

- `object: "list"`

  - `"list"`

- `skip: number`

- `totalCount: number`

### Example

```http
curl https://api.postgrid.com/print-mail/v1/return_envelopes \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

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

**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_`.

### Path Parameters

- `id: string`

### Returns

- `ReturnEnvelope object { id, available, createdAt, 6 more }`

  - `id: string`

    A unique ID prefixed with return_envelope_

  - `available: number`

    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.

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope"`

    Always `return_envelope`.

    - `"return_envelope"`

  - `to: object { id, addressLine1, addressStatus, 17 more }`

    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: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" or "corrected" or "failed"`

      One of `verified`, `corrected`, or `failed`.

      - `"verified"`

      - `"corrected"`

      - `"failed"`

    - `countryCode: string`

      The ISO 3611-1 country code of the contact's address.

    - `addressErrors: optional string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2: optional string`

      Second line of the contact's address, if applicable.

    - `city: optional string`

      The city of the contact's address.

    - `companyName: optional string`

      Company name of the contact.

    - `description: optional string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email: optional string`

      Email of the contact.

    - `firstName: optional string`

      First name of the contact.

    - `forceVerifiedStatus: optional boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle: optional string`

      Job title of the contact.

    - `lastName: optional string`

      Last name of the contact.

    - `metadata: optional map[unknown]`

      See the section on Metadata.

    - `phoneNumber: optional string`

      Phone number of the contact.

    - `postalOrZip: optional string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState: optional string`

      Province or state of the contact's address.

    - `secret: optional boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification: optional boolean`

      If `true`, PostGrid will skip running this contact's address through our address verification system.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/return_envelopes/$ID \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

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

- `ReturnEnvelope object { id, available, createdAt, 6 more }`

  - `id: string`

    A unique ID prefixed with return_envelope_

  - `available: number`

    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.

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope"`

    Always `return_envelope`.

    - `"return_envelope"`

  - `to: object { id, addressLine1, addressStatus, 17 more }`

    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: string`

      A unique ID prefixed with contact_

    - `addressLine1: string`

      The first line of the contact's address.

    - `addressStatus: "verified" or "corrected" or "failed"`

      One of `verified`, `corrected`, or `failed`.

      - `"verified"`

      - `"corrected"`

      - `"failed"`

    - `countryCode: string`

      The ISO 3611-1 country code of the contact's address.

    - `addressErrors: optional string`

      A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

    - `addressLine2: optional string`

      Second line of the contact's address, if applicable.

    - `city: optional string`

      The city of the contact's address.

    - `companyName: optional string`

      Company name of the contact.

    - `description: optional string`

      An optional string describing this resource. Will be visible in the API and the dashboard.

    - `email: optional string`

      Email of the contact.

    - `firstName: optional string`

      First name of the contact.

    - `forceVerifiedStatus: optional boolean`

      If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

    - `jobTitle: optional string`

      Job title of the contact.

    - `lastName: optional string`

      Last name of the contact.

    - `metadata: optional map[unknown]`

      See the section on Metadata.

    - `phoneNumber: optional string`

      Phone number of the contact.

    - `postalOrZip: optional string`

      The postal or ZIP code of the contact's address.

    - `provinceOrState: optional string`

      Province or state of the contact's address.

    - `secret: optional boolean`

      If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

    - `skipVerification: optional boolean`

      If `true`, PostGrid will skip running this contact's address through our address verification system.

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

# Orders

## Create Return Envelope Order

**post** `/print-mail/v1/return_envelopes/{id}/orders`

Creates a batch order of return envelopes. The minimum order quantity is
5000.

### Path Parameters

- `id: string`

### Body Parameters

- `quantityOrdered: number`

  The quantity of return envelopes ordered. Minimum 5000.

- `description: optional string`

  An optional string describing this resource. Will be visible in the API and the dashboard.

- `metadata: optional map[unknown]`

  See the section on Metadata.

### Returns

- `ReturnEnvelopeOrder object { id, createdAt, live, 8 more }`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string or 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.

    - `string`

    - `ReturnEnvelope object { id, available, createdAt, 6 more }`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        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.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: object { id, addressLine1, addressStatus, 17 more }`

        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: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" or "corrected" or "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors: optional string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2: optional string`

          Second line of the contact's address, if applicable.

        - `city: optional string`

          The city of the contact's address.

        - `companyName: optional string`

          Company name of the contact.

        - `description: optional string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email: optional string`

          Email of the contact.

        - `firstName: optional string`

          First name of the contact.

        - `forceVerifiedStatus: optional boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle: optional string`

          Job title of the contact.

        - `lastName: optional string`

          Last name of the contact.

        - `metadata: optional map[unknown]`

          See the section on Metadata.

        - `phoneNumber: optional string`

          Phone number of the contact.

        - `postalOrZip: optional string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState: optional string`

          Province or state of the contact's address.

        - `secret: optional boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification: optional boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `updatedAt: string`

        The UTC time at which this resource was last updated.

      - `description: optional string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

  - `status: "placed" or "filled" or "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

  - `quantityFilled: optional number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/return_envelopes/$ID/orders \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
    -d '{
          "quantityOrdered": 5000
        }'
```

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

**get** `/print-mail/v1/return_envelopes/{id}/orders`

Gets a list of orders for the return envelope by `id`.

### Path Parameters

- `id: string`

### Query Parameters

- `limit: optional number`

- `search: optional string`

  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 number`

### Returns

- `data: array of ReturnEnvelopeOrder`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string or 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.

    - `string`

    - `ReturnEnvelope object { id, available, createdAt, 6 more }`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        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.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: object { id, addressLine1, addressStatus, 17 more }`

        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: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" or "corrected" or "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors: optional string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2: optional string`

          Second line of the contact's address, if applicable.

        - `city: optional string`

          The city of the contact's address.

        - `companyName: optional string`

          Company name of the contact.

        - `description: optional string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email: optional string`

          Email of the contact.

        - `firstName: optional string`

          First name of the contact.

        - `forceVerifiedStatus: optional boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle: optional string`

          Job title of the contact.

        - `lastName: optional string`

          Last name of the contact.

        - `metadata: optional map[unknown]`

          See the section on Metadata.

        - `phoneNumber: optional string`

          Phone number of the contact.

        - `postalOrZip: optional string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState: optional string`

          Province or state of the contact's address.

        - `secret: optional boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification: optional boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `updatedAt: string`

        The UTC time at which this resource was last updated.

      - `description: optional string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

  - `status: "placed" or "filled" or "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

  - `quantityFilled: optional number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

- `limit: number`

- `object: "list"`

  - `"list"`

- `skip: number`

- `totalCount: number`

### Example

```http
curl https://api.postgrid.com/print-mail/v1/return_envelopes/$ID/orders \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

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

**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`.

### Path Parameters

- `id: string`

- `orderID: string`

### Query Parameters

- `expand: optional array of "returnEnvelope"`

  Pass `expand[]=returnEnvelope` to expand the order's
  `returnEnvelope` field into the full return envelope object.

  - `"returnEnvelope"`

### Returns

- `ReturnEnvelopeOrder object { id, createdAt, live, 8 more }`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string or 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.

    - `string`

    - `ReturnEnvelope object { id, available, createdAt, 6 more }`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        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.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: object { id, addressLine1, addressStatus, 17 more }`

        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: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" or "corrected" or "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors: optional string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2: optional string`

          Second line of the contact's address, if applicable.

        - `city: optional string`

          The city of the contact's address.

        - `companyName: optional string`

          Company name of the contact.

        - `description: optional string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email: optional string`

          Email of the contact.

        - `firstName: optional string`

          First name of the contact.

        - `forceVerifiedStatus: optional boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle: optional string`

          Job title of the contact.

        - `lastName: optional string`

          Last name of the contact.

        - `metadata: optional map[unknown]`

          See the section on Metadata.

        - `phoneNumber: optional string`

          Phone number of the contact.

        - `postalOrZip: optional string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState: optional string`

          Province or state of the contact's address.

        - `secret: optional boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification: optional boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `updatedAt: string`

        The UTC time at which this resource was last updated.

      - `description: optional string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

  - `status: "placed" or "filled" or "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

  - `quantityFilled: optional number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/return_envelopes/$ID/orders/$ORDER_ID \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

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

**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`.

### Path Parameters

- `id: string`

- `orderID: string`

### Returns

- `ReturnEnvelopeOrder object { id, createdAt, live, 8 more }`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string or 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.

    - `string`

    - `ReturnEnvelope object { id, available, createdAt, 6 more }`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        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.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: object { id, addressLine1, addressStatus, 17 more }`

        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: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" or "corrected" or "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors: optional string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2: optional string`

          Second line of the contact's address, if applicable.

        - `city: optional string`

          The city of the contact's address.

        - `companyName: optional string`

          Company name of the contact.

        - `description: optional string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email: optional string`

          Email of the contact.

        - `firstName: optional string`

          First name of the contact.

        - `forceVerifiedStatus: optional boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle: optional string`

          Job title of the contact.

        - `lastName: optional string`

          Last name of the contact.

        - `metadata: optional map[unknown]`

          See the section on Metadata.

        - `phoneNumber: optional string`

          Phone number of the contact.

        - `postalOrZip: optional string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState: optional string`

          Province or state of the contact's address.

        - `secret: optional boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification: optional boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `updatedAt: string`

        The UTC time at which this resource was last updated.

      - `description: optional string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

  - `status: "placed" or "filled" or "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

  - `quantityFilled: optional number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/return_envelopes/$ID/orders/$ORDER_ID/fills \
    -X POST \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

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

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

### Path Parameters

- `id: string`

- `orderID: string`

### Query Parameters

- `expand: optional array of "returnEnvelope"`

  Pass `expand[]=returnEnvelope` to expand the order's
  `returnEnvelope` field into the full return envelope object.

  - `"returnEnvelope"`

### Returns

- `ReturnEnvelopeOrder object { id, createdAt, live, 8 more }`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string or 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.

    - `string`

    - `ReturnEnvelope object { id, available, createdAt, 6 more }`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        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.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: object { id, addressLine1, addressStatus, 17 more }`

        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: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" or "corrected" or "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors: optional string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2: optional string`

          Second line of the contact's address, if applicable.

        - `city: optional string`

          The city of the contact's address.

        - `companyName: optional string`

          Company name of the contact.

        - `description: optional string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email: optional string`

          Email of the contact.

        - `firstName: optional string`

          First name of the contact.

        - `forceVerifiedStatus: optional boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle: optional string`

          Job title of the contact.

        - `lastName: optional string`

          Last name of the contact.

        - `metadata: optional map[unknown]`

          See the section on Metadata.

        - `phoneNumber: optional string`

          Phone number of the contact.

        - `postalOrZip: optional string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState: optional string`

          Province or state of the contact's address.

        - `secret: optional boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification: optional boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `updatedAt: string`

        The UTC time at which this resource was last updated.

      - `description: optional string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

  - `status: "placed" or "filled" or "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

  - `quantityFilled: optional number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.

### Example

```http
curl https://api.postgrid.com/print-mail/v1/return_envelopes/$ID/orders/$ORDER_ID \
    -X DELETE \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

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

- `ReturnEnvelopeOrder object { id, createdAt, live, 8 more }`

  - `id: string`

    A unique ID prefixed with return_envelope_order_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `object: "return_envelope_order"`

    Always `return_envelope_order`.

    - `"return_envelope_order"`

  - `quantityOrdered: number`

    The quantity of return envelopes ordered. Minimum 5000.

  - `returnEnvelope: string or 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.

    - `string`

    - `ReturnEnvelope object { id, available, createdAt, 6 more }`

      - `id: string`

        A unique ID prefixed with return_envelope_

      - `available: number`

        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.

      - `createdAt: string`

        The UTC time at which this resource was created.

      - `live: boolean`

        `true` if this is a live mode resource else `false`.

      - `object: "return_envelope"`

        Always `return_envelope`.

        - `"return_envelope"`

      - `to: object { id, addressLine1, addressStatus, 17 more }`

        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: string`

          A unique ID prefixed with contact_

        - `addressLine1: string`

          The first line of the contact's address.

        - `addressStatus: "verified" or "corrected" or "failed"`

          One of `verified`, `corrected`, or `failed`.

          - `"verified"`

          - `"corrected"`

          - `"failed"`

        - `countryCode: string`

          The ISO 3611-1 country code of the contact's address.

        - `addressErrors: optional string`

          A series of human-readable errors/warnings that were raised when running the provided address through our address verification.

        - `addressLine2: optional string`

          Second line of the contact's address, if applicable.

        - `city: optional string`

          The city of the contact's address.

        - `companyName: optional string`

          Company name of the contact.

        - `description: optional string`

          An optional string describing this resource. Will be visible in the API and the dashboard.

        - `email: optional string`

          Email of the contact.

        - `firstName: optional string`

          First name of the contact.

        - `forceVerifiedStatus: optional boolean`

          If `true`, PostGrid will force this contact to have an `addressStatus` of `verified` even if our address verification system says otherwise.

        - `jobTitle: optional string`

          Job title of the contact.

        - `lastName: optional string`

          Last name of the contact.

        - `metadata: optional map[unknown]`

          See the section on Metadata.

        - `phoneNumber: optional string`

          Phone number of the contact.

        - `postalOrZip: optional string`

          The postal or ZIP code of the contact's address.

        - `provinceOrState: optional string`

          Province or state of the contact's address.

        - `secret: optional boolean`

          If `true`, the contact's details are hidden from the dashboard and API responses apart from the final print. The contact ID can then be used as a token for sending mail without giving access to the underlying data.

        - `skipVerification: optional boolean`

          If `true`, PostGrid will skip running this contact's address through our address verification system.

      - `updatedAt: string`

        The UTC time at which this resource was last updated.

      - `description: optional string`

        An optional string describing this resource. Will be visible in the API and the dashboard.

      - `metadata: optional map[unknown]`

        See the section on Metadata.

  - `status: "placed" or "filled" or "cancelled"`

    The status of a return envelope order.

    - `"placed"`

    - `"filled"`

    - `"cancelled"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

  - `quantityFilled: optional number`

    The quantity of return envelopes that were filled for this order. Only
    returned once the order's status is `filled`.