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 endpoint to retrieve your user ID, then List Inboxes to get the inbox IDs your user has access to.

2. Retrieve recent Pieces. The List Inbox Pieces 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 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 and List Inboxes if you don’t already have the inbox ID.

2. Retrieve recent Pieces. Use List Inbox Pieces with received_at sorting and received_after filtering.

3. Retrieve Shipping Addresses. Use Get Shipping Addresses to list saved destination addresses for the inbox.

4. Retrieve Shipping Rates. Use Get Shipping Rates to get real-time carrier quotes for the selected pieces and address.

5. Create Shipment. Use Create Shipment with the chosen rate to submit the shipment.

6. Track Shipments (optional). Use Get Shipments 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 and List Inboxes if needed.

2. Retrieve recent Pieces. Use List Inbox Pieces 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.

4. Email the scan. Use the Share Scan via Email endpoint:

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

5. Archive (optional). Use Archive Piece 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 to find the Piece ID, or use one you already have.

2. Request shredding. Use Request Piece Shredding. The shredding endpoints live under /pieces/{piece_id}/disposal. Optionally set delete_scans to true to also remove digital scans:

   { "delete_scans": true }

3. Review the shredding request (optional). Use Get Piece Shredding Details to retrieve the request details, including its estimated completion time.

4. Cancel shredding (optional). Use Cancel Pending Piece Shredding 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 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 with attributes=payment-detected, as in List Pieces with Detected Checks, or use a Piece ID you already have.

2. Pick a bank account. Use Get Check Deposit Bank Accounts 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 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:

   {
     "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. 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 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 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 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 to retrieve deposit requests for that specific piece.