Mail Agent — Communication skill for Claude Code

Mail Agent

A personal email agent for a homelab: it indexes several IMAP accounts into PostgreSQL and answers natural-language questions over Telegram, using Claude with tools that **only query the database**. It never sends, moves, flags or deletes email.

🚧 **Work in progress.** Design, database schema and tool definitions are done (phase 1). See [project status](#project-status).

What it does

Example questions it answers:

• "Did anyone reply to the email I sent on Monday about the ACME job offer?"
• "Find my electricity bill from August" → answers and offers the PDF for download
• "What important emails did I get today?" / "Summarize my day"
• "Who hasn't replied to me this week?"

It replies in whatever language you write in (Spanish, Catalan or English).

Architecture

flowchart LR
    subgraph accounts["IMAP accounts"]
        G[Gmail]
        I[iCloud]
        M[Movistar]
    end

    subgraph homelab["Homelab · Docker Compose"]
        S["Synchronizer
every 15 min · no AI"]
        DB[("PostgreSQL
full-text + trigrams")]
        A["Agent
tool-use loop"]
        T["Telegram bot
long polling"]
    end

    C["Claude API
Haiku"]
    U((User))

    G & I & M -- "read-only IMAP
(EXAMINE, BODY.PEEK)" --> S
    S --> DB
    A -- "5 read-only
tools" --> DB
    A <--> C
    T <--> A
    U <--> T
    T -. "attachments on demand
(bypassing Claude)" .-> S

Three components in a single Spring Boot service:

1. Synchronizer — reads the INBOX and Sent folders of each account in read-only mode and stores them in Postgres incrementally (UID/UIDVALIDITY) and idempotently. It cleans up HTML, strips quoted replies and signatures, extracts text from PDF attachments and reconciles deletions once a day.
2. Agent — a hand-written tool-use loop on top of Anthropic's official Java SDK, with an iteration cap, a daily budget, and token and cost tracking per request.
3. Telegram bot — th