Lucas RayanandClaude Opus 5
b33fc12f08
The webmail was indigo over glass and the console was green over glass, so the
two halves of one product did not look related, and neither followed a system
anything could be checked against. This replaces the interface with the
Nocturne design system from Claude Design: a near-neutral blue-grey ground,
Inter at weight 500, solid surfaces with a 1px inset edge instead of blur, and
a single blurple accent used as a line, a mark and a glow rather than a flood.
The palette is remapped at the source rather than renamed at every call site.
tailwind.config.js points slate, indigo, emerald, teal and the rest at the
Nocturne ramps, and globals.css carries the same values as variables, so a
utility class and a token cannot drift apart and no colour can enter the
interface from outside the system. The console's green is gone because it
resolves to the one accent; that was the point.
Structurally, both surfaces now share one rail - the same brand mark, the same
3px accent mark on the active item, the same account tile - with a segmented
control for crossing between them. Crossing into the console still goes to the
step-up rather than the admin sign-in, and leaving it is still a plain link.
Settings moves from eight stacked panels to a tab strip, so enabling a second
factor and writing a filter are no longer separated by everything else.
Nothing is sized by the length of its text any more. Labels wrap, tab strips
wrap instead of scrolling, subjects and queue diagnostics wrap instead of
truncating, and the message list's snippet is clamped to two lines rather than
one. That is what broke when the interface was read in Portuguese or Spanish.
Defects found while doing it:
- The queue and DMARC screens styled their status pills with "badge-danger",
"badge-warning" and "badge-verified" - three class names no stylesheet in
this project defines - so every verdict rendered as identical unstyled
text. They are Badge variants now, which exist.
- The DMARC screen printed the literal string "quarantine" as the
enforcement level whatever the domains publish. The report endpoint returns
no policy at all, so it was asserting a configuration nobody had made. It
shows the DMARC pass ratio it genuinely has.
- Half the mailboxes screen and two lines of the audit trace were hardcoded
strings, some Portuguese and some English, so they stayed in one language
whatever the interface was set to. They come from the bundle now, with the
new keys added to all three locales.
- Avatars printed email[0], so every account at one domain collapsed onto the
same letter. initialsFor takes two letters from the local part's own word
boundaries, behind tests.
Trivy reported one HIGH: nanoid 3.3.16, pulled in transitively by postcss,
vulnerable to a denial of service via an infinite loop in ID generation
(CVE-2026-67213). Pinned to ^3.3.18 through the overrides block the package
already uses for sharp and postcss.
Verified: 98 webmail tests green, tsc clean, production build clean, and the
compiled stylesheet serves the Nocturne values with no stock Tailwind indigo,
emerald or slate hex left in it. Trivy fs with the CI scanners, severities and
skip-dirs exits 0.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
LambdaMail
A self-hosted mail server with an integrated webmail and admin console, built to
run on Coolify from a single docker-compose.yaml.
SMTP, IMAP, POP3 and ManageSieve, with SPF, DKIM, DMARC, ARC, MTA-STS and TLS-RPT, DNS automation through Cloudflare, and spam and virus filtering. No paid tiers and no artificial limits on domains or mailboxes.
Status: pre-release. The mail path, the security posture and the web interfaces work end to end, and there is an automated test suite behind them. Several console panels are still read-only, and some features are recorded but not yet acted on — see What is not finished before putting real mail through it.
What it does
| Area | |
|---|---|
| Protocols | SMTP MX (25), Submission (587 STARTTLS, 465 implicit TLS), IMAP (143/993) with UID, flags, IDLE and CONDSTORE, POP3 (110/995), ManageSieve (4190) |
| Authentication | SPF, DKIM (Ed25519 + RSA dual signature), DMARC, ARC sealing, DANE/TLSA and MTA-STS on delivery, TLS-RPT ingestion |
| Filtering | Rspamd scoring with greylisting, RBLs and rate limiting; ClamAV; Sieve |
| Delivery | Durable outbound queue in Postgres with the retry ladder and RFC 3464 bounces; smarthost fallback for hosts with port 25 blocked |
| DNS | Cloudflare reconciliation of the 13 records, idempotent, with drift detection |
| Web | Webmail at /user/* and an admin console at /admin/*, isolated by session audience, with TOTP two-factor, recovery codes, app passwords, and English, Portuguese and Spanish |
Architecture
Two runtimes, split by what each is good at:
protocols(Go) — every protocol listener, the delivery worker, TLS certificate handling, DNS reconciliation, and the webmail's mail API. It owns folder, UID, flag and blob semantics.auth(TypeScript) — logins, sessions, two-factor, account management and the admin console API.web(Next.js) — both web surfaces, and the proxy that gives the browser a single origin.storage(TypeScript) — health only today.
Postgres is the source of truth for everything, including the outbound queue. Redis is a cache and dispatch index; losing it loses no mail.
┌──────────┐
browser ─────────▶│ web │──┬─▶ auth (sessions, accounts, admin)
└──────────┘ └─▶ protocols (mail read/send, DKIM, TLS)
│
internet ──25/587/465/143/993──────────┘
│
Postgres ─┴─ Redis ─ Rspamd ─ ClamAV
Deploying
For a real VPS, follow docs/DEPLOYMENT.md. It covers the three things no code can do for you — reverse DNS, the DNSSEC delegation and getting port 25 unblocked — and the order the rest has to happen in.
The short version:
cp .env.production.example .env # then replace every CHANGE
make preflight # checks port 25, PTR, RBLs, token scope
docker compose up -d
make create-admin EMAIL=you@example.com PASSWORD='...'
make create-admin is not optional: a fresh install has no mailbox, and every
route into the console needs one.
Ports
Everything below is TCP. "Inbound" is what the host's firewall and the provider's security group must allow; "outbound" is what the host must be able to reach.
| Port | Direction | Who connects | Required? | Notes |
|---|---|---|---|---|
| 25 | in | Any sending MTA | Yes to receive mail | Must be open to the world. Rate-limited, not authenticated — that is how SMTP works. |
| 25 | out | This host → remote MTAs | Yes to send mail | The one most providers block. Without it, set a relay (RELAY_HOST); see docs/DEPLOYMENT.md. |
| 80 | in | Let's Encrypt, browsers | Yes | ACME HTTP-01 challenge, and the redirect to HTTPS. Closing it means no certificate. |
| 443 | in | Browsers | Yes | Webmail, admin console, MTA-STS policy, autodiscover. |
| 587 | in | Mail clients | Recommended | Submission with STARTTLS. The port clients should use. |
| 465 | in | Mail clients | Optional | Submission with implicit TLS, for clients that insist. |
| 143 | in | Mail clients | Optional | IMAP with STARTTLS. Prefer 993. |
| 993 | in | Mail clients | Recommended | IMAPS. |
| 110 / 995 | in | Mail clients | Optional | POP3 / POP3S. Leave closed unless something needs POP3. |
| 4190 | in | Mail clients | Optional | ManageSieve, for editing filters from a desktop client. |
| 53 | out | This host → resolver | Yes | MX, SPF, DKIM, DANE and MTA-STS lookups. UDP and TCP — DNSSEC answers overflow UDP. |
| 443 | out | This host → APIs | If used | Cloudflare DNS automation, MTA-STS policy fetch, ClamAV signature updates. |
Ports 110, 995 and 4190 are published by the compose file but are worth closing at the firewall unless a client actually needs them — every open port is one more thing to keep patched.
What the host has to allow
- Reverse DNS (PTR) for the public IPv4 must resolve to
PRIMARY_MAIL_HOST, and that name must resolve back to the same address. Set by whoever owns the IP block — your provider's panel, never Cloudflare. Gmail and Outlook spam-folder or refuse mail without it. If the host has a public IPv6 and publishes an AAAA record, it needs a PTR too: senders that connect over IPv6 are judged on the IPv6 reverse. - Outbound port 25 unblocked. Ask the provider; a timeout rather than a refusal when connecting to a remote MX is the signature of a block.
- Docker with the compose plugin, and a user in the
dockergroup or root. - Ports below 1024 are bound by Docker's proxy on the host, so the daemon needs the privilege — the default on a normal install. The containers themselves run unprivileged.
- The proxy's certificate directory must be readable by the
protocolscontainer. UnderTLS_MODE=traefikit reads the certificate the proxy obtained, from the directory given byCOOLIFY_PROXY_DIR, mounted read-only. The images run as a non-root user, so anacme.jsonleft at mode600and owned by root cannot be read, and the mail listeners fall back to a self-signed certificate while HTTPS keeps working — a confusing failure that looks like a certificate problem and is a permissions problem. - Disk for the mail spool (
protocols_spool) and Postgres. Mail is stored once and reference-counted, but plan for growth. - A firewall that does not rate-limit port 25 into uselessness. Some providers apply aggressive SYN limits that look like intermittent delivery failures.
Running locally
cp .env.example .env
make gen-dev-cert # self-signed certificate for the listeners
make up # builds from source via the build overlay
make seed # a postmaster@example.test fixture
The webmail is on http://localhost:3000. The seeded password is
dev-password-only — it is a fixture, not a credential.
Testing
make test # Go suite, auth and webmail
make lint # go vet, tsc, and the language lint
The Go and auth suites include integration tests that need Postgres. They skip
without TEST_DATABASE_URL and run against a real database in CI, which is
where the security regressions are enforced — wrong password, wrong TOTP code,
session revocation, surface isolation, cross-mailbox reads.
Configuration
Every variable is documented inline in
.env.production.example. The ones without a safe
default:
| Variable | |
|---|---|
JWT_SECRET |
Signs sessions. At least 32 characters; the service refuses to start below that rather than fall back to a constant. |
LAMBDAMAIL_MASTER_KEY |
Encrypts DKIM keys, TOTP secrets and provider tokens. Back it up separately from the database — losing it makes every stored secret unrecoverable. |
POSTGRES_PASSWORD, REDIS_PASSWORD |
No defaults; compose fails without them. |
MAIL_DOMAIN, PRIMARY_MAIL_HOST, PUBLIC_IPV4 |
Identity. PRIMARY_MAIL_HOST must match the PTR of PUBLIC_IPV4. |
Operating
make preflight |
Port 25 egress, PTR and FCrDNS, RBL listings, Cloudflare token scope, certificate presence |
make create-admin EMAIL=… PASSWORD='…' |
First administrator on a fresh install |
make reset-password EMAIL=… PASSWORD='…' |
Recovers a locked-out account and signs out its sessions |
docker compose logs -f protocols |
Delivery, TLS and DNS reconciliation |
GET /health on protocols |
200 healthy, 200 with X-LambdaMail-Health: degraded when a certificate needs attention, 503 when a dependency is down |
docs/OPERATIONS.md covers backups, certificate rotation, what the alerts mean and how to read a delivery failure.
What is not finished
Stated plainly, because a mail server that half works loses mail:
- Recorded but not acted on. Vacation responder, signature and the Sieve rules built in the UI are stored, but nothing consumes them yet — enabling a vacation reply does not send one.
- Read-only console panels. The guided domain onboarding checklist, the DNS desired-vs-actual diff and the CSV import report on state rather than driving it.
- Not implemented. JMAP, BIMI, CalDAV/CardDAV, multi-node. Backups are documented but not automated.
- DANE is off unless
TLS_MODE=acme, and deliberately so: under a Traefik-managed certificate the key changes at every renewal and the published TLSA record stops matching, which permanently rejects mail at every validating MTA.
Contributing
- All code, comments and identifiers are in English.
make lintenforces it. - Tests come with the change that needs them; the suites above must stay green.
- Commits reference their issue:
#N: what changed and why.
License
MIT — see LICENSE.