No description
  • Go 69.2%
  • TypeScript 27.4%
  • Go Template 2.5%
  • Dockerfile 0.6%
  • CSS 0.2%
  • Other 0.1%
Find a file
2026-08-26 21:39:08 +02:00
api Update module github.com/emersion/go-message to v0.18.2 2026-08-26 19:30:18 +00:00
cli fix mailimport 2026-08-26 21:39:08 +02:00
frontend Merge branch 'renovate/cgr.dev-chainguard-nginx' into 'master' 2026-08-26 21:25:32 +02:00
helm allow dual stack setup 2026-08-26 20:29:10 +02:00
ingester fix typos 2026-08-26 15:06:38 +02:00
.gitignore Add API server and ingester services 2026-08-26 15:04:06 +02:00
.gitlab-ci.yml build cli in CI 2026-08-26 21:03:07 +02:00
docker-compose.yml extend to support multiple ingester 2026-08-26 15:39:23 +02:00
README.md drop bundeleed mariadb 2026-08-26 20:02:34 +02:00
renovate.json add renovate config 2026-08-26 21:20:23 +02:00

Mail Archiver

A self-hosted mail archiving system with three components:

  • api/ — Go/gin REST API. Central component: auth, search, storage configuration, mail retrieval. Stateless, safe to run as multiple Kubernetes replicas.
  • ingester/ — Go service that gets mail into the archive: an SMTP listener mail servers can relay/push to, and an IMAP puller that polls mailboxes. Both forward to the API over HTTP. Stateless; configuration is fetched from the API so it can be reconfigured entirely from the web UI.
  • frontend/ — React/TypeScript/Tailwind SPA: search mail, view it (sanitized HTML, sandboxed iframe), download as .eml, and administer users, mailboxes, storage, retention and ingester settings.

Architecture notes

Multi-replica API. No in-memory session state — auth is a stateless JWT. Background jobs (retention sweep, search reindex retry) are gated by a simple database row lease (worker/scheduler.go) so exactly one replica runs them at a time while all replicas keep serving HTTP traffic.

Storage is the source of truth, the database is not. Every archived mail is written to the storage backend (file or S3-compatible, via minio-go) as two objects: the raw .eml (byte-identical to what arrived) and a .json metadata sidecar (mailbox, from/to/subject/date/message-id, attachment list). If the database is lost entirely, POST /api/admin/reindex walks the storage backend and rebuilds the database (and search index) purely from these sidecars — see archive/reindex.go. Only derived/administrative state (users, storage/ingester settings, search index) is allowed to be lost; none of it is required to recover the archived mail itself.

Optional encryption at rest: set STORAGE_ENCRYPTION_KEY on the API and every new .eml/.json object is AES-256-GCM encrypted before it's written. The key lives in an environment variable, deliberately not the database, so an encrypted archive stays recoverable even after a full database loss.

Search. Meilisearch indexes mail metadata + body text for the search UI. It's a derived index, not a source of truth — worker/scheduler.go retries indexing for anything that fails, and reindex rebuilds it from scratch if needed.

Auth & scoping. Three roles:

  • admin — full access, including settings and user management.
  • auditor — read-only access to all archived mail, no config changes.
  • receiver — scoped to only the mailbox(es) assigned to them.

HTML mail safety. Mail HTML is sanitized server-side (bluemonday, scripts, event handlers, iframes, forms stripped) and then rendered in the frontend inside a fully sandboxed <iframe sandbox=""> as defense in depth.

Running locally

cp .env.example .env   # if you add one; otherwise set env vars directly
docker compose up --build

Then create an ingester API key from the web UI (Settings → Ingester API keys) and set INGESTER_API_KEY before starting the ingester, or restart the ingester service after creating one.

Key environment variables

api

Variable Purpose
JWT_SECRET required; signs auth tokens
DB_DRIVER sqlite (default), postgres, mysql, mssql
MEILISEARCH_HOST, MEILISEARCH_API_KEY search backend
STORAGE_FILE_PATH file backend base path (ignored if backend is s3; configurable via UI too)
STORAGE_ENCRYPTION_KEY optional; enables at-rest encryption of archived mail
INITIAL_ADMIN_EMAIL / INITIAL_ADMIN_PASSWORD seeded on first boot only
ENABLE_SCHEDULER set to false on replicas that shouldn't run background jobs (optional — the lease makes this safe to leave on everywhere)

ingester

Variable Purpose
API_BASE_URL e.g. http://api:8080
API_KEY created via Settings → Ingester API keys in the web UI
CONFIG_REFRESH_SECONDS how often to re-fetch SMTP/IMAP config from the API

Kubernetes

A Helm chart is in helm/ (based on the filamentmanagement chart's structure/conventions). It bundles meilisearch as an optional subchart dependency (can be pointed at an external instance instead via meilisearch.enabled=false) and expects an external MariaDB/MySQL instance (mariadb.external.host/mariadb.auth.*), and auto-generates JWT/admin/ ingest secrets on first install if not supplied.

cd helm
helm dependency update
helm install mail-archiver . -n mail-archiver --create-namespace

Key values worth setting before a real deployment:

  • storage.backend (file or s3) and storage.s3.* / storage.file.persistence.*
  • storage.encryptionKey for at-rest encryption
  • admin.email / admin.password (or leave blank to auto-generate — see helm get notes for how to retrieve it)
  • replicaCountApi + autoscaling.enabled for the api tier (the component designed to run as N replicas)
  • ingress.enabled and ingress.hosts

Note: the frontend image's nginx config proxies /api/ to a fixed in-cluster hostname (api), matching docker-compose.yml — the chart names the api Service accordingly, which means only one release of this chart should run per namespace.

The chart deploys one ingester, authenticated via a bootstrap key (INGEST_BOOTSTRAP_API_KEY) that works only while exactly one Ingester exists in the database (the api auto-seeds one named "Default" on first boot). If you create additional ingesters from the web UI (Settings > Ingesters), the bootstrap key stops working — mint a real API key for the chart-deployed ingester from the UI instead and point ingest.existingSecret at a Secret containing it.

Run helm template . | kubectl apply --dry-run=client -f - to validate against your cluster's API schema before installing.