LZ Virtual Mail

Generate temporary, pre-signed links to the envelope/exterior photos of one or more mail items when the user wants to see what an unopened piece of mail looks like from the outside, including before any scan exists. Also use this to refresh envelope_small_url/envelope_large_url once a previously fetched link (e.g. from get_mail_item) has expired. Do not use it to view the scanned document contents (use get_mail_item_pdf_url for the scanned PDF, or get_mail_item_text for extracted text). A link is returned only for the image sizes actually available for an item (envelope_small_url, envelope_large_url); an item with no envelope photo captured yet has both omitted. Links are temporary and expire after approximately 60 minutes; each link's expiry, when available, is returned alongside it. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Read-only.

Retrieve the chronological event timeline for one mail item: received, scanned, shipped, deposited, moved, tagged. Use when the user asks what has happened to an item, its current progress, or whether it is stuck. Do not use it to get item metadata or status fields (use get_mail_item), or to read item contents (use get_mail_item_text). Requires pmb (from list_inboxes) and a known mail_item_id (from list_mail_items). Returns paginated history entries ordered chronologically, plus total_count, page, and has_next_page for paging. Read-only.

Generate temporary, pre-signed links to scanned PDF files for one or more mail items when access to the actual scanned documents is needed, rather than only extracted text. Also use this to refresh pdf_url once a previously fetched link (e.g. from get_mail_item) has expired. For reading, summarizing, or searching document text, get_mail_item_text is usually the appropriate tool. Do not use it to view the envelope/exterior appearance of a piece of mail (use get_mail_item_envelope_image_url). A link is returned only for items whose scan is available; an item that has not been scanned yet, or whose scan is still in progress, has no PDF yet, and is returned without a link. Links are temporary and expire after approximately 60 minutes; each link's expiry, when available, is returned in expires_at. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Read-only.

Retrieve the OCR-extracted text of one scanned mail item. Use when the user wants to read, summarize, search, or ask questions about the item's contents. Do not use it to obtain a downloadable file (use get_mail_item_pdf_url) or item metadata (use get_mail_item). Requires pmb (from list_inboxes) and a known mail_item_id (from list_mail_items), and the item must already be scanned. Returns up to 5 pages per call using start_page and page_count, plus total_pages for paging through longer items. Read-only.

Retrieve the shipment(s) that carry one or more mail items: status, tracking number and link, carrier, rate, destination address, ship and delivery dates, and the mail items included in each shipment. Use when the user asks about the shipment or package for a piece of mail they can point to — "where's my package?", "did this letter get forwarded?", "track the shipment for this item." Do not use it to browse or search a mailbox's mail (use list_mail_items) or to fetch a mail item's own metadata (use get_mail_item); it returns shipping data, not the mail item. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Returns the distinct shipments covering the requested items, deduplicated by shipment id, so several items sharing one shipment yield a single entry; a mail item that has never been shipped contributes no shipment. Read-only.

List all folders in an inbox — both the built-in system folders (Inbox, All Mail, Archive, Trash, Junk Mail) and the user-created custom folders — each with its id, name, type, and unread/total piece counts where available. Use to resolve a folder name to the id you pass as folder_id to list_mail_items or move tools. Requires pmb (from list_inboxes). Read-only.

List the virtual mail inboxes accessible to the authenticated user. Each result includes the PMB (Private Mail Box number), account name, and unread and total mail counts. The PMB returned by this tool is the inbox identifier required by tools that operate on a specific inbox. This tool does not fetch mail items, recipients, or account details. Read-only.

Search and list mail items within one inbox, filtering by recipient, folder, status, tag and/or matching free text across sender, recipient, and scanned content. Use when the user wants to find, browse, or count mail and does not have a specific item ID ("the letter from the IRS," "what came in last week," "any checks?"). Do not use it when you already have a mail_item_id (use get_mail_item) or to read one item's full text (use get_mail_item_text). Requires pmb (from list_inboxes). Returns matching items with IDs, sender, dates, and status; for already-scanned items on AI-features accounts each item also includes the AI-derived document type (e.g. "Bank Statement") and a short summary. Read-only.

List the recipients - the named people or businesses that receive mail - configured on an inbox, each with its ID and name. Use to resolve a recipient name to its ID before filtering mail by recipient or transferring mail, or when the user asks who is set up on the inbox. Do not use it to list a recipient's mail (use list_mail_items with recipient_id) or to add, rename, or remove recipients (not supported). Requires pmb (from list_inboxes). Returns the recipients on the inbox with their IDs and names. Read-only.

List the tags available on an inbox (optionally filtered by a name fragment via match_phrase), returning tag IDs and labels. Use to resolve a tag name to its ID before filtering mail with list_mail_items or applying tags with apply_mail_items_tags. Requires pmb (from list_inboxes). Results are paginated (first/after), defaulting to 20 per page. Read-only.

Mark one or more mail items as read (viewed). Use when the user wants to clear unread status or says they have handled certain mail. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Side effect: marks the items read and lowers unread counts.

Mark one or more mail items as unread (not viewed). Use when the user wants to restore unread status on mail they have not dealt with yet. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Side effect: marks the items unread and raises unread counts.

Move one or more mail items to a destination: the inbox, the archive, the trash, or a recipient folder. Use when the user wants to file, archive, or trash mail. Do not use it to permanently destroy physical mail (use request_mail_items_shred) or to reassign items to a different recipient (use transfer_mail_items_to_recipient). Requires pmb (from list_inboxes), mail_item_ids (from list_mail_items), and a destination_folder (INBOX, ARCHIVE, TRASH, or a numeric recipient-folder id from list_folders). Side effect: relocates the items, changing where they appear.

Echo back the given message (prefixed with "pong: ") as a health check. Use only to verify MCP connectivity and the request/response round-trip. Returns no customer data and touches no account state. Read-only.

Request that the mailroom open and scan one or more physical mail items so their contents can be read; the physical originals are kept in storage afterward. Use when the user wants unscanned mail digitized ("open and scan this," "scan the letter from the IRS"). Do not use it if the item is already scanned (scan status is available from get_mail_item), to read existing text (use get_mail_item_text), or to scan and then destroy the original (use request_mail_items_scan_then_shred). Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Each item is checked first: a scan is requested only for items where it is an available action, and any item that cannot be scanned (e.g. a scan is already in progress, the item is archived, or identity is not verified) is skipped and returned with a reason. Side effect: queues a staff-handled scan for the eligible items; the originals stay in storage and scanning is not instant.

Request that the mailroom open and scan one or more physical mail items and then securely shred (permanently destroy) the physical originals once scanning is complete. Use when the user wants mail digitized and the paper destroyed in one step ("scan this then shred it," "scan and shred these"). Do not use it to scan and keep the original (use request_mail_items_scan), to shred without scanning first (use request_mail_items_shred), or to read existing text (use get_mail_item_text). Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Each item is checked first: the operation is requested only for items where scanning is an available action, and any item that cannot be scanned (e.g. a scan is already in progress, the item is archived, or identity is not verified) is skipped and returned with a reason. Side effect: queues a staff-handled scan followed by irreversible physical destruction of the originals; scanning and shredding are not instant.

Request secure shredding (permanent physical destruction) of one or more physical mail items. Use when the user explicitly wants their physical mail destroyed ("shred these," "securely dispose of this"). Do not use it to merely hide or declutter items (use move_mail_items to TRASH, which is reversible); shredding is irreversible. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items), and optionally post_shred_action. Each item is checked first: a shred is requested only for items where it is an available action, and any item that cannot be shredded (e.g. a shred is already in progress, it has already been shredded, or it has been shipped) is skipped and returned with a reason. Side effect: queues an irreversible, staff-handled physical destruction for the eligible items.

Reassign one or more mail items to a different recipient on the inbox. Use on multi-recipient (business) inboxes when mail was attributed to the wrong recipient and needs to be moved to the correct one. Do not use it to move items between folders (use move_mail_items) or to change a recipient's own details (not supported). Requires pmb (from list_inboxes), mail_item_ids (from list_mail_items), and the target recipient_id (from list_recipients). Returns a confirmation of how many items were reassigned. Side effect: changes each item's recipient.