Lull Mail

lullmail.com — a briefing-first mail client. Mail is a document you read, not a console you operate: senders are screened once and routed forever, a daily digest tells you what actually needs you, and the work surfaces (board, calendar, notes) derive themselves from your mail instead of asking you to maintain them.

The design stance: your mail is yours. Credentials are sealed at rest, tracker images are blocked by default, and one-click export (mbox/EML, RFC 4155) is a table-stakes feature, not a cancellation flow.

What's in

• The Screener — new senders wait for one decision; everything they ever send follows it. Reversible, per sender.
• Today — the briefing: what needs you, who you're waiting on (with aging), what quietly arrived. "You're done." is a real state.
• Inbox / Reading / Receipts / Snoozed — mail files itself by your sender rules; dated snoozes return to the Inbox on their day.
• Board — a personal kanban where the cards write themselves: unread Inbox mail is the to-do column, threads you answered are the waiting-on column, dated snoozes are the deferred pile. Pin anything; pins are markers and never move your mail.
• Calendar — year/month/week over the mail that comes back to you.
• Notes — a spatial canvas of stickies. Thoughts, not tasks.
• Keyboard-first (j/k, verbs, g jumps, one command palette), undo on every action, light/sepia/dark plus more palettes, no telemetry.
• Rich sending — compose plain text or paste HTML: HTML goes out as multipart/alternative with an automatic plain-text fallback, a sandboxed preview shows the rendering, and IMAP/Gmail/Graph providers all carry the rich part. Attachments ride along as multipart/mixed (15 MiB per file, 25 MiB per message) and survive parked drafts; To/Cc/Bcc accept comma-separated address lists and the From account is a dropdown.
• Leave cleanly — download one original message as EML or a whole account as mailbox-by-mailbox mboxrd, with a manifest that discloses any local-mirror fallback instead of silently dropping data.
• Explicit history — every account states how much history Lull Mail organizes: 30 days, 90 days (default), 1 year, 3 years, or "All history." Changing the window grows or shrinks the organized views only; the local mirror obeys the separate retention setting, and provider mail is never touched. Bodies of the last 30 days of mail are prefetched during sync by default (so opening recent mail is local; older bodies load on first open); set PREFETCH_BODIES=0 to fetch bodies only when a thread is opened.
• Installable PWA with an explicit iOS path, account-bound offline reading, resilient local drafts, a conservative replay queue for reversible filing actions, and optional private web-push alerts.
• Password-primary security: argon2id password sign-in (hashed on your server), discoverable passkeys with required user verification, multiple-key management, printable one-use recovery codes, optional TOTP, HttpOnly server sessions, revocation, rate limiting, and provable self-serve deletion.

Standalone and single-owner by design: one owner per install, no multi-user tenancy, no campaign-sending infrastructure.

Quickstart (self-host)

No configuration required:

docker compose up -d
docker compose logs app      # one-time setup token, valid 24h

Open http://localhost:8080 and finish setup in the browser: paste the token, pick a name and password (or create a passkey instead), save the recovery codes. The token stops authenticating the moment the first credential exists. You can sign in with that name or the account email.

Deploying with teploy instead of raw Docker? A template teploy.yml is committed — point server: at a host from your ~/.teploy/servers.yml and teploy deploy <server>.

SECRET_KEY (seals credentials) and the setup token are generated on first boot and kept in the appdata volume; the browser origin is detected from your first visit and pinned — so behind a reverse proxy, reach the app through the final public URL when you run setup. Set the env vars below only to override any of this; env always wins. Migrations run automatically at boot (lullmail migrate runs them by hand).

Security

Sign-in is password-primary; passkeys, an authenticator (TOTP), and one-use recovery codes are opt-in additions, not requirements.

• Passwords are hashed with argon2id (m=64 MiB, t=3, p=4, 16-byte salt, PHC-encoded) on your server. Parameters travel inside the stored hash, so future tightening verifies old hashes without a migration. Changing a password requires the current one; removing it is refused while it is the only way in.
• Rate limits. Five failed password attempts lock the account for 15 minutes (answered with Retry-After); a per-host limiter throttles every auth route. Wrong email and wrong password are indistinguishable in the response, so accounts cannot be enumerated.
• Exposure guidance, not enforcement. The install classifies its pinned origin at boot: loopback, LAN, and Tailnet addresses read as private; anything else shows a passive warning suggesting an authenticator or a strong password. Nothing is ever blocked based on it.
• Agent tokens (lull_… Bearer) reach accounts and mail but never the auth or security surface — that boundary is enforced in the router.
• Removing a credential signs out every other session; deleting the account is explicit, typed-confirmation, and removes every stored secret.

Environment

Variable	Required	Notes
DATABASE_URL	yes	Postgres, e.g. postgres://user:pass@host:5432/lullmail
SECRET_KEY	no	Seals mail credentials, OAuth/passkey records, TOTP, and push subscriptions with AES-256-GCM. Generated on first boot into DATA_DIR/secret.key when unset; changing it invalidates sealed data.
LULL_TOKEN	no	One-time installation token for first-run setup (password or passkey). Generated (24h expiry, printed to logs) when unset. Rejected after the first credential exists; restart regenerates only while the install is unconfigured.
LULL_USER_EMAIL	no	Owner address used as the internal ident. Setup collects a name (login accepts that name or this address); leave unset to derive [email protected].
PUBLIC_URL	no	Browser origin, e.g. https://mail.example.com. Auto-detected from the first setup visit and pinned in the database; the env var forces an origin. WebAuthn and mutation-origin checks reject a different origin.
DATA_DIR	no	Where the generated key and setup token live (default ./data). Mount it as a volume or restarts regenerate them.
PREFETCH_BODIES	no	1 (default) fetches bodies of the last 30 days of mail during sync so opening recent mail is local; 0 fetches a body only when its thread is opened.
WEBAUTHN_RP_ID	no	Relying-party domain; derived from the effective origin.
PORT / ADDR	no	Defaults to :8080.

Optional Google: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET. Redirect URI: $PUBLIC_URL/api/oauth/google/callback. Required scopes are gmail.modify and gmail.send plus identity; public multi-user distribution still requires Google's restricted-scope verification/CASA process.

Optional Microsoft: MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, and MICROSOFT_TENANT (default common). Redirect URI: $PUBLIC_URL/api/oauth/microsoft/callback; delegated scopes are User.Read, Mail.ReadWrite, Mail.Send, and offline_access.

Optional web push: VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, and VAPID_SUBJECT (normally mailto:[email protected]). Generate a pair with any standards-compatible VAPID tool. Notifications are deliberately generic and never put subject/sender content on the lock screen.

Develop

Repo organization and house rules: CONVENTIONS.md.

go build ./... && go test ./... && go vet ./...
cd dashboard && npm ci && npm test && npm run typecheck && npm run build
go run . serve

dist/ is embedded into the binary at Go build time — after changing dashboard code, rebuild the dashboard, then rebuild/restart the binary; a running process keeps serving the copy it embedded.

The marketing site is a separate Neutron static build (site/), deployed at lullmail.com:

cd site && npm install && npm run dev

A local mail world for testing (GreenMail — real IMAP/SMTP against fake accounts):

docker run -d --name lullmail-mail -p 127.0.0.1:10143:3143 -p 127.0.0.1:10025:3025 \
  greenmail/standalone:2.0.1 -Dgreenmail.setup.test.all \
  [email protected]:password

Connect [email protected] / password / host 127.0.0.1 port 10143 from the Accounts page. Loopback IMAP is allowed plaintext for exactly this.

Agents and MCP

Mail is a great context source for scripts and AI agents, so the agent surface is first-class: long-lived revocable Bearer tokens (fenced to mail and work surfaces — they can never touch sign-in, passwords, passkeys, sessions, or mailbox zip export), and a standalone MCP adapter in mcp/ that exposes the whole read/screener/send/board/notes surface to any MCP-capable client. The server itself stays agent-agnostic; the adapter is optional and the product never depends on it.

Architecture

One Go binary. The mail engine (mail-engine/, vendored from Neutron's mail module) owns IMAP/JMAP sync and the mail_* mirror tables; the product layer (this repo's Go files) owns users, sender rules, buckets, briefing/board derivation, and the embedded Preact dashboard. Postgres is the only dependency.

provider ──sync──> mail_* mirror ──classify──> buckets ──derive──> Today / Board / Calendar

Status

Release-candidate, in daily production use over IMAP. Every feature above is implemented and tested locally against a real IMAP/SMTP server. Two things are operator work rather than code: the Gmail and Outlook connectors have not been exercised against real Google/Microsoft accounts (self-hosters can bring their own client IDs today; a distributed client needs Google's restricted-scope verification and CASA), and there is no hosted offering yet. Campaign-sending infrastructure is deliberately out of scope for this mailbox.

License

FSL-1.1-MIT (Functional Source License) — see LICENSE. Any use is permitted except offering a competing product, and each version automatically becomes MIT two years after its release. The copyright is held by a single author, so a commercial/hosted license remains possible alongside the FSL; the vendored mail-engine/ module is covered by the same license.