claude-mail-buddy/plan.md

claude-mail-buddy — Plan

Concept

Poll a dedicated IMAP mailbox for incoming mail from a trusted sender, dispatch the message as a prompt to Claude Code via claude-remote, and have Claude reply via a CCC send-email action.

---

Sender Verification

The allowed_sender config filter is a basic check but not cryptographically sound. Stronger options (in increasing strength):

• Authentication-Results header — check that the inbound mail server stamped DKIM/SPF pass before dispatching. Practical and low-effort since your mail server already does the verification.
• DKIM — cryptographic signature from the sending domain's DNS key. Proves the message genuinely originated from that domain.
• PGP/S/MIME — end-to-end signature tied to the sender's personal key, independent of mail infrastructure. Strongest guarantee; requires signing outbound mail from your client.

For now, allowed_sender substring match is sufficient for exploration. Worth adding Authentication-Results checking before using this for anything sensitive.

---

Implementation Stages

Stage 1 — Explore the message object (current)

Receive a message and inspect() the full imapflow msg object to understand what data is available (headers, body parts, envelope, flags, etc.).

Stage 2 — Prompt construction

Parse the message into a well-formed prompt: sender, subject, body. Prefix with instructions telling Claude to reply via the CCC send-email action.

Stage 3 — CCC send-email action

Extend claude-code-conduit with a send-email action (SMTP). Claude calls it as a tool with recipient, subject, and body.

Stage 4 — Wire it together

Replace the inspect() call with make_prompt + send_to_claude. End-to-end flow: email in → Claude processes → email out.

Stage 5 — Adaptive polling

High/low frequency mode: switch to fast polling (e.g. 10s) when a message arrives, step back down to slow polling (e.g. 45s) after a configurable idle period with no new messages (e.g. 5 minutes). Keeps the conversation feeling responsive without hammering the server during quiet periods.

Stage 6 — Persist last UID

Save the last processed UID to a state file so the script picks up where it left off across restarts rather than skipping everything that existed at startup.

Stage 7 — Hardening

• Verify Authentication-Results header for DKIM/SPF pass
• Mark messages seen only after successful dispatch
• Reconnect/retry logic for IMAP drops