Architecture: self-hosted AI-native mailbox for agents

Design of record for OpenMail — one Go binary (smtpd/core/sender/mcp) + Postgres
+ object storage on a VPS. Covers inbound SMTP/MIME/threading, outbound
deliverability (relay-default, self-host opt-in), data model, AgentMail-shaped
v0 API + MCP server, and an MVP milestone path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

README.md

@@ -0,0 +1,38 @@
+# OpenMail
+
+A self-hosted, AI-native mailbox for agents — open-source infrastructure that gives an AI agent its
+own real email inbox (receive, parse, thread, search, send) on a box you control.
+
+Think "Gmail for agents, self-hosted." A single Go service + Postgres + object storage you run on a
+VPS, exposing a clean REST API (and an MCP server) so any agent can own an address, read its mail as
+structured threads, and reply.
+
+> **Status: private WIP.** This is a personal learning project and a self-hosting alternative in a
+> space that hosted products (e.g. AgentMail) serve well. Keep it private. Don't reference it in any
+> job application, PR, or interview, and shelve it if it would ever conflict with an employer. It was
+> designed only from public API surfaces and public RFCs — nothing proprietary.
+
+See **[ARCHITECTURE.md](./ARCHITECTURE.md)** for the design.
+
+## Why
+
+The hard, valuable part of an agent-mailbox product is not the API — it's the mail plumbing:
+receiving over SMTP/MX, sending with real deliverability (SPF/DKIM/DMARC, IP reputation), parsing
+MIME, threading, and storage at scale. OpenMail is an exercise in building that plumbing properly,
+self-hostable, with an agent-first API on top.
+
+## Goals
+
+- **Self-hostable** in one `docker compose up` on a single VPS, scaling to a small fleet later.
+- **Agent-first API** — persistent inboxes, structured threads, `extracted_text` (quoted-history
+  stripped), labels, search, drafts, webhooks/WebSocket events.
+- **AgentMail-API-shaped** where reasonable, so existing agent tooling/MCP can point at a self-hosted
+  endpoint with minimal change. (Compatibility is a non-goal where it conflicts with a cleaner design.)
+- **Deliverability taken seriously** — DKIM signing, SPF/DMARC guidance, and a pluggable send path
+  (self-host SMTP **or** relay through SES/Postmark) because reputation is the real moat.
+
+## Non-goals (for v1)
+
+- A hosted multi-tenant SaaS. OpenMail is self-host-first.
+- Beating a mature provider on deliverability out of the box — that takes IP warmup and time.
+- A webmail UI. The product is the API + MCP; humans use their own client or the CLI.