Email Agent

Triage the family inbox from one page: all mail lands in a single Gmail account and this service classifies it, recommends actions, performs bulk actions, drafts replies, and answers the Hub.

The build spec is AGENTS.md. ORIGINAL_NOTES.md is archived pre-planning material and is not authoritative.

Status

Phase 1.1 — Go service skeleton. Complete when this file was written: config from the environment, SQLite schema init, GET /health, Dockerfile and docker-compose. Mail fetch, classification, login, and the HTMX screens come in later phases.

Layout

cmd/email-agent/        service entry point
internal/config/        environment-driven configuration
internal/store/         SQLite open + schema (internal/store/schema.sql)
internal/server/        HTTP routes and middleware
internal/version/       build metadata (set via -ldflags)
Dockerfile              multi-stage, CGO-free build
docker-compose.yml      this project's own container and image

Configuration

All configuration is read from environment variables. Secrets live in ~/.config/environment.d/10-secrets.conf on the host and are passed into the container by docker-compose; no secret value is ever committed. See .env.example for the full list of names.

Key variables:

Variable	Default	Purpose
EMAIL_AGENT_ENV	development	development, production, or test
EMAIL_AGENT_ADDR	:8790	Listen address
EMAIL_AGENT_PORT	8790	Listen port (used when EMAIL_AGENT_ADDR is unset)
EMAIL_AGENT_DB_PATH	data/email_agent.db	SQLite file
EMAIL_AGENT_LOG_LEVEL	info	debug, info, warn, error
EMAIL_AGENT_SESSION_SECRET	(empty)	Session cookie signing key (Phase 1.2)

Run locally

go run ./cmd/email-agent
curl -s localhost:8790/health

Docker

docker compose up -d --build
curl -s localhost:8790/health

The container is email-agent, image email-agent:latest, named volume email_agent_data mounted at /data, listening on 8790. It runs as an unprivileged user and has a built-in healthcheck (email-agent -healthcheck). Caddy on .35 proxies mail.lab.audasmedia.com.au to this port.

Endpoints (Phase 1)

Method	Path	Purpose
GET	/health	Liveness + database check, JSON
GET	/readyz	Readiness, JSON
GET	/	Placeholder dashboard (real screens in Phase 1.2)

Database

SQLite is opened with the pure-Go modernc.org/sqlite driver (no CGO). The schema in internal/store/schema.sql creates the AGENTS.md §7 tables: messages, classifications, rules, actions_log, unsubscribe, drafts, summaries, plus schema_migrations. Schema init is idempotent and runs on every start.