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.)
Email envoy@critchley.biz directly, naming the note key, e.g.: "Please work through the open items in gdata-server/todo. Mark each item done directly in the note as you complete it — don't wait for me to reply to your confirmation email, since I may not see or reply to it. Correct what you can directly; reply if anything needs a decision." A reusable Gmail draft with this wording is saved (subject Work through open items: [NOTE_KEY]) — duplicate it, swap in the note key, send. This is the manual/ad-hoc counterpart to the cron-triggered periodic reconciliation described in envoy/todo ("Regular maintenance emails") — same mechanism, triggered by John instead of a schedule.
Envoy does the work itself (it has full notes read/write access and a coding phase) rather than delegating out to Claude Code or Codex — there is no working handoff-to-a-separate-coding-agent path yet. The hermes mailbox reserved for a future Claude Code assistant (see memory/envoy/mail-server) is provisioned but not wired up to anything yet.
The note itself, not a reply email, is the record of progress: since these handoffs may go unanswered, Envoy should check off/move completed items using whatever done-convention the target note already uses (e.g. gdata-server/todo's strikethrough-plus-FIXED-date-and-move-to-Completed pattern, or envoy/todo's ☐/✅ checkbox pattern) rather than inventing a new one. If a note has no existing done-marker convention, a short dated note under a Completed/Done heading is the fallback.