Mail Agent — Communication skill for Claude Code
Self-hosted personal email agent: indexes IMAP accounts into PostgreSQL and answers questions over Telegram using Claude.
How to install Mail Agent
This entry records only its repository, not the path inside it, so there is no
exact command to give. Open perecollet/mail_agent and copy the folder into
~/.claude/skills/, or the file into ~/.claude/agents/.
What Mail Agent does
Self-hosted personal email agent: indexes IMAP accounts into PostgreSQL and answers questions over Telegram using Claude. Read-only and hardened against prompt injection. Java 25 · Spring Boot 4 · hexagonal architecture.
Alternatives in Communication
- Agentrove — A self-hosted web and macOS desktop app for Claude Code and Codex, powered by ACP 270 ★
- Post Shortform — Publish a short vertical video with a caption to TikTok, Instagram Reels, and YouTube Shorts simultaneously 212 ★
- Learning Chat — You are an assistant helping the user understand a completed code change 94 ★
README
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:
- 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.
- 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.
- Telegram bot — th
Related Skills
Gmail
Gmail API and IMAP access patterns for sending, drafting, and searching email across Max's accounts
Kb Builder
Answer a dozen questions in a chat, and it builds your personal knowledge base for you (WorkBuddy / Doubao / C
Scribble
Self-hosted Slack knowledge bot that watches invited conversations, keeps durable notes in a Git-backed wiki,
Context Injection
Configure and tune automatic context injection for Memory OS. Covers the Icarus pre_llm_call hook flow, 4 sour
Old Claude MCP
Local MCP server that indexes exported Claude chat history into SQLite FTS5 for context retrieval
Auto Pc
Boot this chat's own PC (isolated run dir + fenced resources)
Related Agents
Kotlin Backend Engineer
Kotlin/Spring Boot specialist. Invoke for Kotlin backend implementation, Spring Security, Spring Data JPA, fin
Be Springboot Expert
Expert Spring Boot 4.0 developer for enterprise-grade Java 25 LTS applications. Use for Spring Boot projects,
Java Build Resolver
Java/Maven/Gradle build, compilation, and dependency error resolution specialist. Fixes build errors, Java com