This note documents best practices for reliably locating emails within IMAP using Envoy’s two-stage search model.
Always search headers first, then fetch bodies only for specific Message-IDs.
Stage 1: search_emails → returns headers only (cheap, broad scan).
Stage 2: add_emails → fetch full bodies for selected Message-IDs (targeted, precise).
Avoid fetching full bodies without narrowing candidates first.
Before broad searches, reason about where the email is likely to live.
Examples:
• Outbound message → check Sent first
• Completed task → check Done
• Ongoing thread → check Active or project folder
• New unread work → check INBOX with UNSEEN
In the poem example, the correct strategy was to search Sent first rather than repeatedly searching INBOX.
Use IMAP flags to narrow results:
• SEEN — processed emails
• UNSEEN — unread emails
• FLAGGED — starred
• Combine with AND logic, e.g. UNSEEN FLAGGED
Do not apply flags reflexively — choose them based on intent.
Use In-Reply-To and Message-ID to walk a thread precisely.
If a reply references a specific Message-ID, fetch that exact message rather than performing a broad subject search.
If a search returns no results:
• Try once more with adjusted criteria (different folder, remove flags, broaden date range).
• After two failed attempts, accept it is unavailable and proceed.
Do not repeat the same search pattern with minor cosmetic changes.
If a specific Message-ID fetch fails, retry once and record:
RETRY: <message-id> — not found on first attempt.
If still unavailable, proceed and explain clearly in the reply.
General order of operations:
1. Use direct Message-ID if available
2. Search most likely folder
3. Narrow by flags/date/sender
4. Broaden to additional folders only if necessary
This keeps iteration count low and avoids unnecessary continuation cycles.