From d9dd26e26355b22e270d0cc32e5e9efcca520764 Mon Sep 17 00:00:00 2001 From: mikael-lovqvists-claude-agent Date: Wed, 18 Mar 2026 03:35:48 +0000 Subject: [PATCH] Add plan.md with implementation stages and sender verification notes Co-Authored-By: Claude Sonnet 4.6 --- plan.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 plan.md diff --git a/plan.md b/plan.md new file mode 100644 index 0000000..ba372fd --- /dev/null +++ b/plan.md @@ -0,0 +1,61 @@ +# 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](../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