Lightr

A lightweight mail engine. Lightr owns SMTP, identity, policy and the operator surface; Dovecot serves the mailboxes.

01The Problem

Email remains one of the most operationally awkward parts of running software. Traditional self-hosted stacks mean stitching together several daemons, carrying years of configuration baggage, and debugging deliverability across tools that were never designed to feel like one system. Managed providers are convenient, but they can be expensive, restrictive, or a poor fit when you want to own the whole flow.

For small teams, personal products, and operators who want to understand what they run, there is a missing middle: something practical and inspectable that does not turn mail into a separate profession.

02The Solution

Lightr is a mail engine written in Python. It does the part that is actually its own (getting mail in and out, deciding who may do what, and giving an operator a CLI and an API that answer questions without a database client) and hands mailbox storage and IMAP to Dovecot.

That split is deliberate. Implementing IMAP well is a multi-year job that Dovecot has already done: UIDs, flags, partial fetch, IDLE, and every client quirk that comes with them. Lightr drives Dovecot itself, generating its configuration, master user and auth, checking it with Dovecot's own parser and reloading it, so an operator never edits dovecot.conf.

03How It Works

1. SMTP in - Receives on :25 and accepts authenticated submission on :587.
2. Policy - Checks SPF, DKIM and DMARC, scores spam, and signs outbound mail with DKIM.
3. Delivery - Hands local mail to Dovecot over LMTP, stored as Maildir, one file per message.
4. Outbound queue - Retries with backoff, processes bounces, and keeps a suppression list.
5. Operator surface - A REST API, a CLI, and webhooks over the same objects.

04Key Features

• Organizations, domains, accounts, aliases - Every object addressable by its human name; no command needs a UUID.
• Pluggable authentication - Local passwords, or offloaded to LDAP, OIDC, or an HTTP endpoint.
• Scoped API keys - Keys scoped to an organization, a domain or a single account, which cannot read another tenant's data.
• Mailbox API - Folders, messages, search, flags, attachments, sending and live updates, for building mail clients.
• Webhooks - Signed with HMAC, with test, rotate and delivery history.
• Backups and migration - lightr backup, and mailbox import/export from mbox, Maildir or .eml.
• Resilient by design - If Dovecot is down, the API, the queue and SMTP receive keep working.
• Safe CLI - Passwords are never accepted as command-line arguments; table output on a terminal, JSON when piped.

05Technical Stack

• Python 3.11+ - The engine, CLI and REST API.
• Dovecot - IMAP, message storage, Sieve and quota, driven through doveadm.
• SQLite or PostgreSQL - Engine state, with Alembic migrations.
• Linux - Shipped as a Debian package that pulls in Dovecot, or installed with pipx.

06The Rewrite

Lightr started as a single Go binary with its own IMAP server. That version worked, but its IMAP used positional UIDs that shifted on every delete, and doing IMAP properly would have been a project of its own. The rewrite kept what was Lightr's (SMTP, policy, the API) and gave the mailbox to software that has done it well for decades. The Go engine is preserved on an archive branch, and lightr migrate adopts an existing database in place.

07In Production

Lightr runs the mail for nigelbasa.tech. The internal mail client on this site is built on its mailbox API, and portal sign-in doubles as mailbox sign-in through its HTTP authentication hook.

08Why I Built This

I wanted email infrastructure I could reason about end to end. I needed something usable for my own projects and potentially for small organizations, but I did not want to inherit the complexity of a stitched-together legacy mail stack. Lightr became an exercise in drawing the boundary in the right place: own what is genuinely yours, and lean on proven software for the rest.

09Links

• GitHub Repository