Best practices and guidance for interacting with Envoy effectively.
Envoy can move processed emails to different folders:
• Done — Completed tasks, processed requests
• Archive — Reference material, historical emails
• Active — Ongoing work, pending items
• Custom folders — Projects, clients, topics
Envoy knows about all available IMAP folders. The folder list is loaded automatically on startup and included in the LLM context from iteration 1. The LLM can also request a refreshed folder listing at any time by setting list_folders: true.
When fetching emails by Message-ID (add_emails), each request includes a folder hint — the IMAP folder where the email is expected. The hinted folder is searched first, then fallback order is: INBOX, Done, then all other folders. This makes cross-folder fetching efficient: most lookups hit on the first try.
The search_emails action accepts a folder parameter. Envoy can search any folder it knows about:
• {"folder": "Done", "since": "2026-02-13"} — Today's completed work
• {"folder": "Archive", "subject_contains": "project X"} — Search archive
• {"folder": "INBOX", "flags": "SEEN"} — Read emails still in inbox
Search is still one folder at a time. To search across multiple folders, Envoy must issue separate searches in successive iterations. See TODO for planned multi-folder search aggregation.
Envoy knows what folders exist, so you can name them directly:
✅ "Summarize emails in my Done folder from today"
✅ "Search my Archive folder for emails about project X"
✅ "What's in my Active folder?"
For broad queries like "summarize all emails today", Envoy can iteratively search multiple folders, but being specific about where to look is still more efficient.
1. New email arrives in INBOX2. Envoy processes it3. Envoy moves it to Done/Archive/Active/Projects4. Email no longer in INBOX
Therefore: Most of Envoy's work is in Done folder, not INBOX!
Ask: "Summarize emails in Done folder from today"
Ask: "Show me unread emails in INBOX"
Ask: "Search Done folder for emails with subject containing 'project X'"
(Or specify Archive, Active, etc.)