lilmail
open source · MIT bring your own inbox

Your mail, calendar & contacts — in one tiny binary.

lilmail is a database-free PIM client that connects to the Gmail, Outlook or IMAP account you already have. Drop one ~30 MB binary next to a config file and it runs — comfortably — on 64 MB of RAM. A connector, never a hosted mailbox.

View on GitHub Read the docs
MIT licensed Single Go binary ≈30 MB · 64 MB RAM Linux · macOS · Windows
lilmail localhost:3000/inbox lilmail three-pane reading view — folder list, message list and an open message
Bring your own inbox

A connector — not a mailbox.

lilmail hosts no mail and depends on no central server. It brokers the account you already own over OAuth2 / IMAP / SMTP. Your messages stay with your provider; lilmail is just the client that renders them.

Gmail Outlook Any IMAP
lilmail your binary · your box
your browser
One client, three surfaces

Everything a personal information manager should be.

Mail

IMAP mailbox browsing, SMTP sending, conversation threading (JWZ), rich-text compose with attachments and scheduled send, search, labels and snooze.

Calendar

CalDAV month and week views, event CRUD, free/busy and end-to-end iTIP/iMIP meeting invites — send a request, parse an invite, RSVP. Opt-in.

Contacts

CardDAV address book with recipient autocomplete backed by a recent-recipients store. Your people, from your own account. Opt-in.

See it in action

Fast, familiar, and entirely yours.

Every screen below is the real client running in demo mode — no mockups.

lilmaillocalhost:3000/inbox lilmail Inbox — a three-pane reading view with threads, unread badges and attachment markers

Inbox

A three-pane reading view with threads, unread badges and attachment markers — familiar the second you open it.

lilmail lilmail message viewer — an open message in the reading pane

Read

A clean message viewer with a sandboxed email iframe, threaded replies and inline attachments.

lilmail lilmail compose modal with TO/CC/BCC, attachments and scheduled send

Compose

Rich compose with TO/CC/BCC, attachments and scheduled send, right over the inbox.

lilmail lilmail search results filtered by query

Search

Fast full-text search that filters the list in place.

lilmail lilmail settings page — multi-account, notifications and licences

Settings

Multi-account, notifications and licences — everything is a config key.

lilmaillocalhost:3000/login lilmail sign-in — password or OAuth2, connect the mailbox you already own

Sign in

Password or OAuth2 — connect the mailbox you already own. Nothing to sign up for.

How it works

From download to a working inbox — in four steps.

No account to create and nothing to migrate. Run the binary, connect the mailbox you already own, and lilmail renders it in your browser.

  1. Terminal~/lilmail 
    # one binary, one config beside it
$ ./lilmail
lilmail listening on http://localhost:3000
store: bbolt (embedded) · no database
    1

    Drop in the binary and run it

    Grab the ~30 MB binary (or go build), put a config.toml next to it, and start it. There is no database to provision and no asset pipeline — state lives in an embedded bbolt file.

    → http://localhost:3000

  2. lilmaillocalhost:3000/login lilmail sign-in — password or OAuth2 against the mailbox you already own
    2

    Sign in with the account you already own

    Enter your email and mail-server password, or click Sign in with OAuth2 for Gmail, Outlook or any OIDC provider. lilmail brokers your account over IMAP/SMTP — it never stores your mail.

  3. lilmaillocalhost:3000/inbox lilmail inbox — a three-pane reading view with threaded conversations and unread badges
    3

    Read your inbox — familiar the second it opens

    A three-pane reading view with real JWZ conversation threading, unread badges and attachment markers. Full-text search filters the list in place; snooze, labels, archive and spam are one click away.

  4. lilmaillocalhost:3000/compose lilmail compose modal — TO/CC/BCC, rich text, attachments and scheduled send
    4

    Compose, attach, and schedule the send

    Rich-text compose with TO/CC/BCC, file attachments, inline images and recipient autocomplete — plus scheduled send and 30-second draft auto-save. Turn on the opt-in AI assistant for smart compose and thread summaries.

Self-host in minutes

One file to run. Nothing to provision.

There is no SPA, no asset pipeline and no database to stand up. HTML templates and vendored JS compile straight into the binary; durable state lives in an embedded bbolt file. It runs fully offline / air-gapped with only a config.toml beside it.

  • No external database — embedded bbolt by default (optional Postgres)
  • Server-rendered HTMX + Alpine — no build step, no CDN
  • Cross-compiles for Linux, macOS and Windows
Get lilmail Getting started
lilmail — quick start 
# Grab the binary (or: go build -o lilmail)
git clone https://github.com/vul-os/lilmail
cd lilmail

# Point it at the mailbox you already own
cp config.toml.example config.toml   # edit imap/smtp + secrets

# Run — no database, no build step
./lilmail                            # → http://localhost:3000
Install

Two ways in. Both end with ./lilmail.

Take a pre-built release binary or build it yourself from source — either path is one file to run, with only a config.toml beside it. No database, no Node, no build pipeline.

Pre-built binary

no Go toolchain needed

download & run 
# 1 · grab the archive for your OS from Releases,
#     then extract it and step in
$ tar xzf lilmail_linux_amd64.tar.gz
$ cd lilmail

# 2 · add your config beside the binary
$ cp config.toml.example config.toml

# 3 · run it
$ ./lilmail                 # → :3000

Build from source

Go 1.23+ · one static binary out

go build 
# 1 · clone the repo
$ git clone https://github.com/vul-os/lilmail.git
$ cd lilmail

# 2 · build (or: make build)
$ go build -o lilmail

# 3 · configure & run
$ cp config.toml.example config.toml
$ ./lilmail                 # → :3000

Then point it at your mailbox.

A minimal config.toml needs only an IMAP/SMTP server and two secrets. Everything else — OAuth2, CalDAV, CardDAV, notifications, AI, multi-account — is opt-in and off by default.

  • Generate a strong jwt.secret — e.g. openssl rand -hex 32
  • Use a random 32-character encryption.key (AES-256, credentials at rest)
  • Open http://localhost:3000 and sign in — no signup, nothing to migrate
Full install guide Download a release
config.toml — minimal 
[server]
port = 3000

[imap]
server = "imap.example.com"
port   = 993
tls    = true

[smtp]
server       = "smtp.example.com"
port         = 587
use_starttls = true

[jwt]
secret = "change-me — openssl rand -hex 32"

[encryption]
key = "a-32-character-encryption-key!!"
Under the hood

Small binary. Serious mail engine.

Everything beyond core mail is opt-in via a config key and adds zero overhead when it's off.

One binary, no database

Templates and vendored JS embed via embed.FS; durable state uses an embedded bbolt file by default. Nothing to run — an optional Postgres backend is there for shared deploys.

Stable /v1 JSON API

A clean REST surface — folders, paginated messages, search, flags, move/archive/spam, compose, drafts, attachments, scheduled send, calendar and contacts — served beside the HTMX UI from the same engine.

OAuth2 / OpenID Connect

Full authorization-code flow with PKCE (S256), XOAUTH2 and OAUTHBEARER SASL and transparent token refresh. Classic username/password login still works.

Conversation threading

The JWZ algorithm over Message-ID, References and In-Reply-To headers, backed by an embedded bbolt store — real threads without a heavyweight index.

Real-time notifications

An IMAP IDLE watcher drives an SSE stream, browser notifications, native desktop toasts and VAPID Web Push. Entirely opt-in and zero-overhead when disabled.

AI mail assistant

Smart compose, thread summaries, reply suggestions, action-item extraction and phishing detection through any OpenAI-compatible endpoint. Off by default; no mail is persisted.

Multiple accounts

Add and switch IMAP accounts and browse a unified inbox with concurrent fan-out and per-account error isolation. Opt-in via config.

Security-first

JWT sessions, AES-256-GCM encrypted credentials at rest, a strict Content-Security-Policy, SameSite=Lax cookies and a sandboxed email iframe.

Self-host your inbox in five minutes.

Free and open source under the MIT License. Clone it, point it at your mailbox, and run.

View on GitHub Read the docs