This document describes how Envoy reads and acts on emails via IMAP.
Email access is split into two distinct operations:• Search (search_emails) — returns headers only. Fast, low-context-cost. Use to survey a folder.• Fetch (add_emails) — returns full body. Use once you know which specific emails you need.
Typical workflow:1. Search one or more folders → receive headers (Date, Subject, From, To, CC, Message-ID, threading headers, read/starred status)2. Identify relevant emails from headers3. Fetch full bodies via add_emails for only those emails4. Process, summarise, and act
A list of search requests, one object per folder. Each object has these fields:
• folder — IMAP folder to search (e.g. INBOX, Done, Archive). Defaults to INBOX if empty.• sender — Filter by From address substring. Empty string = no filter.• subject_contains — Filter by Subject substring. Empty string = no filter.• since — ISO date string, e.g. 2026-02-01. Emails on or after this date.• before — ISO date string. Emails before this date.• search_flags — Space-separated IMAP flags. All specified flags must match.
• SEEN — Read/processed emails only• UNSEEN — Unread emails only• FLAGGED — Starred/flagged emails only• UNFLAGGED — Not starred• ANSWERED — Emails that have been replied to• UNSEEN FLAGGED — Unread AND starred (all listed flags must match)• `` (empty string) — No flag filter, match all emails
Each result contains: message_id, in_reply_to, references, date, subject, from, to, cc, read (bool), starred (bool), folder.No body content is included. Results appear in the === EMAIL SEARCH RESULTS === context section.
search_emails is a list — you can search multiple folders in one iteration:`search_emails: [ {"folder": "INBOX", "search_flags": "UNSEEN", ...}, {"folder": "Done", "since": "2026-02-01", ...}]`
Fetches complete emails (headers + body) by Message-ID. Use after searching to retrieve only the emails you actually need.Each entry: {"message_id": "<id>", "folder": "Done"}. The folder is a hint for faster lookup — leave empty to search all folders.
Fetched emails appear as --- Gathered Email N --- in context, with full body.
Set list_folders: true to refresh the list of available IMAP folders. The result appears in the next iteration context. Useful when you are unsure which folders exist.
Search results (headers) accumulate within a run and are shown each iteration.Full-body emails (gathered_emails) also accumulate within a run.Use working_note to record summaries, key Message-IDs, and findings to carry forward.Use drop to remove items you no longer need from context.
When processing resumes from a continuation email, full-body emails are re-fetched by Message-ID and folder from IMAP — they are never stored in the continuation attachment.Search results are NOT carried across continuation boundaries. Re-run any needed searches after resuming.Record important Message-IDs in working_note before a continuation if you will need them.
• INBOX — New unprocessed work (cron fetches UNSEEN only)• Done — Completed one-off tasks• Sent — Outbound copies (stored automatically)• Active — Pending work, awaiting reply• Archive — Long-term reference• Projects/{name} — Project-specific emails• DAV — WebDAV delivery staging (not for general use)
Folders are created automatically when you first move an email to them. Call list_folders to discover all current folders.