# Playbooks

> Step-by-step workflows for common Virtual Mail Public API use cases.

Web page: https://reference.earthclassmail.com/v1/rest-api/playbooks/

A collection of step-by-step workflows for common tasks using the Virtual Mail Public API.

## Retrieve Latest Pieces (with Images)

Retrieve the most recent mail including envelope and content scan images.

1. **Retrieve Inboxes** (optional).
   If you already know the inbox IDs, skip this step. Otherwise, use the
   [Current User](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getcurrentuser.md) endpoint to retrieve your user ID,
   then [List Inboxes](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxes.md) to get the inbox IDs your user has access to.

2. **Retrieve recent Pieces.**
   The [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) endpoint returns a paged list of
   Pieces for an Inbox. Sort on `received_at` and use the `received_after` filter to get the
   most recent items.

3. **Retrieve Piece Media.**
   Use the [Get Bulk Piece Media](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getbulkpiecemedia.md) endpoint with the
   Piece IDs. This returns envelope photos and content scans with short-lived download URLs.

---

## Requesting a Shipment

Forward physical mail to a destination mailing address.

1. **Retrieve Inboxes** (optional).
   Use [Current User](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getcurrentuser.md) and
   [List Inboxes](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxes.md) if you don't already have the inbox ID.

2. **Retrieve recent Pieces.**
   Use [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) with `received_at` sorting and
   `received_after` filtering.

3. **Retrieve Shipping Addresses.**
   Use [Get Shipping Addresses](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listshippingaddresses.md) to list saved
   destination addresses for the inbox.

4. **Retrieve Shipping Rates.**
   Use [Get Shipping Rates](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getshippingrates.md) to get real-time carrier
   quotes for the selected pieces and address.

5. **Create Shipment.**
   Use [Create Shipment](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/createshipment.md) with the chosen rate to
   submit the shipment.

6. **Track Shipments** (optional).
   Use [Get Shipments](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listshipments.md) to check the status of pending
   shipments.

---

## Email Pieces

Parse through inbox items and email scans to an external email address.

1. **Retrieve Inboxes** (optional).
   Use [Current User](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getcurrentuser.md) and
   [List Inboxes](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxes.md) if needed.

2. **Retrieve recent Pieces.**
   Use [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) with sorting and filtering.

3. **Identify scanned Pieces.**
   Each Piece has an `attributes` array. Items that have been scanned include the `"scanned"`
   attribute. Retrieve scan info with
   [Get Piece Scans](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getpiecescans.md).

4. **Email the scan.**
   Use the [Share Scan via Email](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/emailscan.md) endpoint:

   ```json
   {
     "emails": ["recipient@example.com"]
   }
   ```

5. **Archive** (optional).
   Use [Archive Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/archivepiece.md) to move the item out of the inbox
   after emailing.

---

## Shredding a Piece

Request permanent destruction (shredding) of a physical mail item.

1. **Identify the Piece.**
   Use [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) to find the Piece ID, or use one
   you already have.

2. **Request shredding.**
   Use [Request Piece Shredding](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/requestpieceshredding.md). The shredding
   endpoints live under `/pieces/{piece_id}/disposal`. Optionally set
   `delete_scans` to `true` to also remove digital scans:

   ```json
   { "delete_scans": true }
   ```

3. **Review the shredding request** (optional).
   Use [Get Piece Shredding Details](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getpieceshredding.md) to
   retrieve the request details, including its estimated completion time.

4. **Cancel shredding** (optional).
   Use [Cancel Pending Piece Shredding](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/cancelpieceshredding.md)
   within the 7-day grace period.

---

## List Pieces with Detected Checks

Find mail items where a check was detected during scanning.

Use [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) with the `attributes`
parameter set to `payment-detected`, sorted newest first (`sort_direction=1` is descending):

```
GET /inboxes/{inbox_id}/pieces?attributes=payment-detected&sort_by=received_at&sort_direction=1
```

Each returned Piece includes a `detected_checks_count` field indicating how many checks were
found. Add the `received_after` key to `filters` (for example,
`filters=received_after:2024-01-15T00:00:00Z`) to narrow results to recent items.

> **Caution**
>
> Don't use `filters=contains:payment-detected`. The `contains` filter is a text search: it
> matches sender names, recipient names, and scanned text that contain the value, and tag
> names that start with it. It looks for the literal text "payment-detected", not for pieces
> with detected checks.

---

## Depositing a Check

Have the checks in a piece deposited to one of the inbox's bank accounts, and cancel the
request if you change your mind.

1. **Find the Piece.**
   Use [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) with
   `attributes=payment-detected`, as in [List Pieces with Detected Checks](#list-pieces-with-detected-checks),
   or use a Piece ID you already have.

2. **Pick a bank account.**
   Use [Get Check Deposit Bank Accounts](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listcheckdepositbankaccounts.md)
   to list the inbox's bank accounts, and note the `id` of the one to deposit to.

3. **Request the deposit.**
   Use [Request Check Deposit](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/requestcheckdeposit.md) with the bank
   account ID. Optionally set `expedited`, and use `post_operation_action` to shred the rest
   of the piece once the checks are out:

   ```json
   {
     "check_deposit_bank_account_id": 500,
     "expedited": false,
     "post_operation_action": { "type": "shred" }
   }
   ```

   `expedited` ships the checks to the bank overnight, typically arriving the next business
   day, for a fee listed in [Virtual Mail detailed pricing](https://www.legalzoom.com/business/business-operations/lz-virtual-mail-detailed-pricing.html). Leave it off when the
   bank account's `financial_institution.expedited` is `true`: those banks get overnight
   delivery for free.

   The response is the new deposit request, with `status` set to `Opened`. A `409` means
   another operation is already in progress for the piece, or its checks were already requested.

4. **Track the deposit** (optional).
   Use [Get Requested Check Deposits for Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listpiececheckdepositrequests.md)
   to follow the request. `status` changes to `Shipped` once the checks are on their way, and
   `shipment` holds the tracking details.

5. **Cancel the deposit** (optional).
   Use [Cancel Check Deposit](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/cancelcheckdeposit.md) with the deposit
   request `id` from the previous step:

   ```
   DELETE /pieces/{piece_id}/check-deposit-requests/{check_deposit_request_id}
   ```

   This works only until the mailroom extracts the checks. After that it returns `400`.

---

## Retrieving Check Deposit Details

Use [Get Requested Check Deposits](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listcheckdepositrequests.md) to retrieve
deposit requests for an inbox. Each deposit request includes `status`, `bank_account`, `checks`
found, `deposit_slips` with download URLs, and `requested_at` / `extracted_at` timestamps.

Optional filters: `has_checks`, `date_from`, `date_to`, and sorting by `requested_at` or
`extracted_at`.

If you already know the Piece ID, use
[Get Requested Check Deposits for Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listpiececheckdepositrequests.md)
to retrieve deposit requests for that specific piece.