--- name: lz-virtual-mail-mail-triage description: Work through unread and unfiled mail in an LZ Virtual Mail mailbox, surfacing what needs attention, marking items read or unread, filing them into folders and tags, and leaving anything consequential for the user to decide. Use when the user asks to triage, sort, clear, go through or catch up on their virtual mail, or asks what new mail they have. --- # Triage the virtual mailbox Triage answers one question for each item: **does this need the user's attention, a filing decision, or nothing?** The aim is a short list of items that matter, with the rest sorted into folders and tags without losing anything. Do not move, tag or mark items in bulk just because they look similar. Mail is physical correspondence: a bank notice filed as "junk" can cost the user money. ## 1. Confirm the scope before touching anything Start with `get_current_user` so you know whose mailbox this is, then `list_inboxes` to see which inboxes exist. If the user has more than one inbox or recipient, ask which one to triage. Do not assume the first one. Read `get_inbox_overview` for counts of unread and unfiled items so you can report the size of the job before you start. Note the scope you agreed on (one inbox, one recipient, or all) and keep to it for the whole session. ## 2. Pull the working set, then sort by what the item is Use `list_mail_items` filtered to unread items first, then to unfiled items (items in no folder). Page through the results rather than requesting everything at once. Keep a running note of counts so you can report totals at the end. For items that need more detail than the list gives, use `get_mail_item` for the record and `get_mail_item_text` for the content of a letter. Read the text only when the sender or type does not settle the question. Sort each item into one of three buckets: - **Needs the user:** anything from a government body, tax authority, court, lender, insurer, landlord or employer; anything with a deadline, a payment request, a signature request or a notice of change; anything that looks like a legal document. Leave these unread, flag them, and do not file them away. - **Routine, safe to file:** statements you can recognise, marketing, catalogues, receipts already paid, newsletters. These can be filed and marked read once the user has agreed to the category. - **Unclear:** anything you cannot place. Ask the user rather than guessing. Document the sender and the type as you go, because the user will want to check your sorting, and an item's content is the only reliable guide to its importance. ## 3. Decide on filing in batches, then apply Propose the folders and tags you would use, grouped by kind of mail (for example "Bills", "Banking", "Marketing"), and ask the user to confirm the grouping. Use `list_folders` and `list_tags` first so you reuse what already exists instead of creating near-duplicates. Once the grouping is agreed, apply it with `move_mail_items` and `apply_mail_items_tags`. Apply in small batches of related items so that a mistake is easy to reverse. After each batch, re-read the affected items with `list_mail_items` to confirm the change took effect. To change read state, use `mark_mail_items_read` for items you have fully handled and `mark_mail_items_unread` for anything the user still needs to read. Never mark an item read that the user has not seen, if the user is going to act on it. **Creating a new tag with `create_mail_item_tag`** and **deleting tags with `delete_mail_item_tags`** each need the user's explicit yes first. Filing into an existing folder or tag, and marking read or unread, also change state, so confirm the batch before you apply it. Wait for the user's explicit yes on each batch in this conversation. ## 4. Keep an audit trail of what you changed Before you finish, use `get_mail_item_history` on a sample of items you moved or tagged to confirm the change was recorded as you intended. Report any item where the history does not match what you expected. ## Common patterns and traps - **Marketing that is really a notice.** Envelopes with promotional branding often contain account or policy changes. Read the text before filing anything from a sender you do not recognise. - **Duplicates.** The same bill can arrive twice, once as a scan and once as a notice. Check the amount and date before you file the second copy as a duplicate. - **Unread is not the same as new.** Old unread items may be ones the user already dealt with on paper. Ask before marking a long backlog read. - **Filing hides items.** An item moved into a folder can drop out of the default view. Tell the user where each batch went, so nothing looks lost. - **Over-tagging.** Many tags on one item make later searches noisy. Prefer one folder plus at most one or two tags. - **Paging.** Large mailboxes return results in pages. Counting only the first page will understate the work. Keep paging until the list is exhausted, or tell the user that you have only seen part of it. ## Output ``` Mailbox: , checked as of