SelfArchiver
Docker app from S3lfcod3r's Repository
Self-hosted email archiver: pick exactly which IMAP folders to archive, build rules with filters (sender / subject / attachment / age), give each rule its own schedule, and…
Requirements
Overview
Readme
View on GitHub
Self-hosted email archiver that keeps your mailbox small and your mail safe — with the controls other archivers are missing.
Selbstgehosteter E-Mail-Archivierer, der dein Postfach klein und deine Mails sicher hält — mit den Stellschrauben, die anderen Archivierern fehlen.
Version
License
Backend
Web
Deploy
Ko-fi
📰 What's new / Neuigkeiten → CHANGELOG.md
🇬🇧 English
Most archivers can only mirror a whole account. SelfArchiver connects to your IMAP mailboxes and archives only what your rules select — and can then delete it from the mailbox, so a free mailbox quota is enough. It is not a full-account mirror or mail server, and an independent implementation, not a fork of other archivers (NOTICE.md).
Part of the Self family (SelfMailer, SelfStream, SelfDashboard …) — same design system, same deploy style (GHCR → Unraid).
TL;DR — selective folders · rule-based filters · per-rule schedules · archive-then-delete · full-text search · single container · no external DB.
📑 Table of contents
Features · How it works · Architecture · Quick start · Unraid · Configuration · API · Security · Tech stack · Development · Roadmap
✨ Features
📂 Archiving
- Selective folders — archive only the folders you choose (e.g.
Invoices,Insurance), never the spam-filled inbox; Refresh button and an option to include new subfolders - Rule-based filters —
From/Subject/Tocontains-any, require attachment, only-read, exclude-flagged — so important or unread mail is never touched - Age — only act on mail older than N days or hours
- Per-rule schedules — builder for hourly / daily / weekly / monthly (time, weekdays, day of month) or a custom cron, with a live "next run" preview; every rule runs independently
- Archive-then-delete retention — Archive only or Archive, then delete from mailbox; deletion only happens after a confirmed archive
- Idempotent — a stable per-message key prevents duplicates, re-running a rule is always safe
🔎 Archive
- Browse + full-text search (subject, sender, recipients, body); filter by mailbox, folder and sent date
- Click an archived email to read it inline; download any message as
.emlor single attachments - Delete single archived emails or a whole folder (with confirmation)
📊 Activity
- Run history with scanned / archived / deleted counts and errors, filterable
- See which emails a run archived; delete single runs or clear the whole history; configurable history retention
🔐 Security & platform
- Mailbox credentials encrypted at rest (AES-256-GCM); self-signed certificates (local servers) can be allowed per mailbox
- Optional single-password login for the whole UI
- Dark or light UI, 12 languages (dropdown), collapsible navigation, mobile layout with hamburger drawer
- Single container — SQLite (with full-text search) and
.emlfiles on one volume; no Postgres, Redis, search engine or Tika sidecars
🔁 How it works
- You add an IMAP mailbox (source).
- You create one or more rules: pick folders, set a filter, choose an age threshold, a schedule and whether to delete after archiving.
- On schedule (or Run now), SelfArchiver lists messages older than the threshold in each selected folder, archives the ones matching the filter (full
.emlincl. attachments) into the database + disk, and — if enabled — deletes those messages from the mailbox.
🧭 Architecture
┌──────────────────────────── container ────────────────────────────┐
│ Fastify (HTTP) │
│ ├── /api/* REST API (sources, rules, emails, runs) │
│ └── /* static React SPA (web/dist) │
│ │
│ Scheduler (node-cron) Runner │
│ └── one task per rule ───▶ fetch → filter → archive → delete │
│ │
│ imapflow ─────────────▶ IMAP mailbox (TLS) │
│ │
│ SQLite (better-sqlite3) Disk │
│ ├── sources /data/archive/<source>/<yyyy>/<mm>/ │
│ ├── rules *.eml │
│ ├── archived_emails │
│ ├── emails_fts (FTS5) │
│ └── runs │
└─────────────────────────────────────────────────────────────────────┘
Details: docs/ARCHITECTURE.md.
🚀 Quick start (Docker)
git clone https://github.com/s3lfcod3r/selfarchiver.git
cd selfarchiver
cp .env.example .env
# set APP_SECRET (openssl rand -hex 32) and AUTH_PASSWORD
docker compose up -d
Open http://<host>:3000 → add a mailbox → create a rule.
⚠️ Without
AUTH_PASSWORDthe server only listens on127.0.0.1inside the container (the open API stays unreachable from the network). Binding elsewhere without a password requires settingHOSTexplicitly — not recommended.⚠️ Archive-then-delete permanently removes mail from your mailbox once archived — test with Archive only first and keep backups of anything irreplaceable.
📦 Unraid
Add the template from
https://raw.githubusercontent.com/s3lfcod3r/unraid-templates/main/templates/selfarchiver.xml
(all my templates: s3lfcod3r/unraid-templates)
or import it under Docker → Add Container → Template. Set APP_SECRET and AUTH_PASSWORD and map /data to e.g. /mnt/user/appdata/selfarchiver.
The image is published to GHCR: ghcr.io/s3lfcod3r/selfarchiver:latest.
⚠️ APP_SECRET: set it once and keep it — changing it makes stored mailbox passwords undecryptable.
⚠️ Permissions: the container starts as root only to
chownthe/datavolume, then drops to the unprivilegednodeuser (uid1000) viagosu.
⚙️ Configuration
Environment variables (no common prefix).
| Variable | Required | Default | Purpose |
|---|---|---|---|
PORT |
– | 3000 |
HTTP port |
APP_SECRET |
– | (auto) | Encrypts mailbox passwords + signs sessions (≥ 32 chars). Empty = generated once and stored in /data/.secret. Set and keep stable. |
AUTH_PASSWORD |
– | (empty) | Optional UI password. Empty = no auth, server binds to 127.0.0.1 only |
HOST |
– | 0.0.0.0 |
Bind address; without AUTH_PASSWORD only honoured if set explicitly |
COOKIE_SECURE |
– | false |
Set to true when serving over HTTPS (behind a TLS proxy) so the session cookie is only sent over secure connections (also enables HSTS) |
TZ / CRON_TZ |
– | Europe/Berlin |
Timezone for cron schedules (compose/Unraid default; without Docker the code falls back to UTC) |
DATA_DIR |
– | /data |
SQLite DB + .eml archive location |
DB_PATH |
– | $DATA_DIR/selfarchiver.sqlite |
SQLite file |
ARCHIVE_DIR |
– | $DATA_DIR/archive |
.eml archive directory |
LOG_LEVEL |
– | info |
trace … error |
🔌 API overview
Base path /api, authentication via session cookie (only when AUTH_PASSWORD is set). Health check: GET /api/health.
| Group | Endpoints (excerpt) |
|---|---|
| Auth | login, logout, session |
| Sources | sources (CRUD), sources/test-connection, sources/{id}/test, sources/{id}/folders |
| Rules | rules (CRUD), rules/validate-cron, rules/{id}/run |
| Archive | emails, emails/folders, emails/{id}, …/download, …/content, …/attachment/{index}, emails/delete-folder |
| Activity | runs, runs/{id}/emails, settings |
| Dashboard | dashboard, health |
🛡️ Security
- Mailbox passwords AES-256-GCM-encrypted with a key derived from
APP_SECRET— losing/changing the secret makes them unrecoverable - Server-side sessions (random id, HMAC-signed cookie,
HttpOnly,SameSite=Lax), revocable on logout; login rate limit (10 attempts / 15 min) with constant-time password check - CSRF guard: state-changing requests with a foreign
Originare rejected - Without
AUTH_PASSWORDthe server binds to loopback only - Security headers (CSP,
X-Frame-Options: DENY,nosniff,no-referrer, HSTS withCOOKIE_SECURE); archived HTML is rendered in a sandboxed iframe with its own strict CSP - Crash-safe archiving: the
.emlis written + fsynced before the DB insert; deleting from the mailbox only happens for messages that exist in the archive; deleting an archive folder requires the expected count - Run behind HTTPS (reverse proxy) if exposed beyond a trusted LAN
- Deliberate trade-offs (documented): single shared password (no user accounts); sessions live in memory and end on restart; Archive, then delete is irreversible on the mailbox side — the archive copy remains, treat it like any retention policy
Security update history → CHANGELOG.md (entries marked 🔒).
🧱 Tech stack
| Part | Tech |
|---|---|
| Backend | Node 22 · Fastify · better-sqlite3 (SQLite WAL + FTS5) · imapflow · mailparser · node-cron · cron-parser · zod · pino |
| Web | React · Vite · TypeScript · Tailwind CSS · React Router |
| Deploy | Docker (multi-stage, runs as node via gosu) · GHCR · Unraid |
🛠️ Development
npm install
npm run dev # backend on :3000 (tsx watch)
npm run dev:web # frontend on :5173 (Vite, proxies /api)
npm run build # build web + prepare server
Checks (no automated tests yet):
npm run typecheck # type-check both workspaces
🗺️ Roadmap
- IMAP sources · folder picker · self-signed certificates
- Rules: filters · age in days/hours · per-rule schedules · archive-then-delete
- Archive: full-text search · inline reader ·
.eml+ attachment download · delete emails/folders - Activity: filterable run history · archived emails per run · history retention
- Security hardening (sessions, headers, non-root, CSRF, crash-safe archiving)
- 12 UI languages · mobile layout
🇩🇪 Deutsch
Die meisten Archivierer können nur ein ganzes Konto spiegeln. SelfArchiver verbindet sich mit deinen IMAP-Postfächern und archiviert nur, was deine Regeln auswählen — und kann es danach aus dem Postfach löschen, sodass ein kostenloses Postfach-Kontingent reicht. Es ist kein Komplett-Spiegel und kein Mailserver, sondern eine eigenständige Implementierung, kein Fork anderer Archivierer (NOTICE.md).
Teil der Self-Familie (SelfMailer, SelfStream, SelfDashboard …) — gleiches Design-System, gleicher Deploy-Stil (GHCR → Unraid).
Kurz — gezielte Ordner · regelbasierte Filter · Zeitplan pro Regel · archivieren, dann löschen · Volltextsuche · ein Container · keine externe DB.
📑 Inhaltsverzeichnis
Funktionen · Funktionsweise · Architektur · Schnellstart · Unraid · Konfiguration · API · Sicherheit · Tech-Stack · Entwicklung · Roadmap
✨ Funktionen
📂 Archivierung
- Gezielte Ordner — archiviere nur die Ordner, die du wählst (z. B.
Rechnungen,Versicherung), nie den Spam-vollen Posteingang; Aktualisieren-Button und Option neue Unterordner einbeziehen - Regelbasierte Filter —
Von/Betreff/Anenthält, Anhang nötig, nur gelesene, geflaggte ausschließen — damit Wichtiges oder Ungelesenes nie angetastet wird - Alter — nur Mails älter als N Tage oder Stunden verarbeiten
- Zeitplan pro Regel — Baukasten für stündlich / täglich / wöchentlich / monatlich (Uhrzeit, Wochentage, Tag im Monat) oder eigener Cron, mit Live-Vorschau „nächster Lauf“; jede Regel läuft unabhängig
- Archivieren, dann löschen — Nur archivieren oder Archivieren, dann aus Postfach löschen; gelöscht wird nur nach bestätigter Archivierung
- Idempotent — ein stabiler Schlüssel pro Nachricht verhindert Duplikate, ein erneuter Lauf ist immer sicher
🔎 Archiv
- Durchsuchen + Volltextsuche (Betreff, Absender, Empfänger, Inhalt); Filter nach Postfach, Ordner und Sende-Datum
- Archivierte Mail anklicken, um sie direkt zu lesen; jede Mail als
.emloder einzelne Anhänge herunterladen - Einzelne archivierte Mails oder einen ganzen Ordner löschen (mit Bestätigung)
📊 Aktivität
- Lauf-Historie mit Anzahl geprüft / archiviert / gelöscht und Fehlern, filterbar
- Sehen, welche Mails ein Lauf archiviert hat; einzelne Läufe löschen oder die ganze Historie leeren; Aufbewahrung der Historie einstellbar
🔐 Sicherheit & Plattform
- Postfach-Zugangsdaten verschlüsselt gespeichert (AES-256-GCM); selbstsignierte Zertifikate (lokale Server) je Postfach zulassen
- Optionaler Ein-Passwort-Login für die gesamte Oberfläche
- Dunkles oder helles UI, 12 Sprachen (Dropdown), ein-/ausklappbare Navigation, Handy-Ansicht mit Seitenmenü
- Ein Container — SQLite (mit Volltextsuche) und
.eml-Dateien auf einem Volume; kein Postgres, Redis, keine Suchmaschine oder Tika-Beiwagen
🔁 Funktionsweise
- Du fügst ein IMAP-Postfach (Quelle) hinzu.
- Du erstellst eine oder mehrere Regeln: Ordner wählen, Filter setzen, Altersgrenze, Zeitplan und ob nach dem Archivieren gelöscht wird.
- Nach Zeitplan (oder Jetzt ausführen) listet SelfArchiver in den gewählten Ordnern die Mails, die älter als die Grenze sind, archiviert die zum Filter passenden (vollständige
.emlinkl. Anhängen) in Datenbank + Datei und löscht sie — falls aktiviert — aus dem Postfach.
🧭 Architektur
┌──────────────────────────── Container ────────────────────────────┐
│ Fastify (HTTP) │
│ ├── /api/* REST-API (Quellen, Regeln, Mails, Läufe) │
│ └── /* statische React-SPA (web/dist) │
│ │
│ Scheduler (node-cron) Runner │
│ └── ein Task je Regel ───▶ holen → filtern → archiv. → löschen │
│ │
│ imapflow ─────────────▶ IMAP-Postfach (TLS) │
│ │
│ SQLite (better-sqlite3) Festplatte │
│ ├── sources /data/archive/<source>/<yyyy>/<mm>/ │
│ ├── rules *.eml │
│ ├── archived_emails │
│ ├── emails_fts (FTS5) │
│ └── runs │
└─────────────────────────────────────────────────────────────────────┘
Details: docs/ARCHITECTURE.md.
🚀 Schnellstart (Docker)
git clone https://github.com/s3lfcod3r/selfarchiver.git
cd selfarchiver
cp .env.example .env
# APP_SECRET (openssl rand -hex 32) und AUTH_PASSWORD setzen
docker compose up -d
http://<host>:3000 öffnen → Postfach hinzufügen → Regel anlegen.
⚠️ Ohne
AUTH_PASSWORDlauscht der Server im Container nur auf127.0.0.1(die offene API ist vom Netz aus nicht erreichbar). Ohne Passwort anders zu binden geht nur, wenn duHOSTausdrücklich setzt — nicht empfohlen.⚠️ Archivieren, dann löschen entfernt Mails endgültig aus dem Postfach, sobald sie archiviert sind — teste zuerst mit Nur archivieren und behalte Backups von allem Unwiederbringlichen.
📦 Unraid
Vorlage von
https://raw.githubusercontent.com/s3lfcod3r/unraid-templates/main/templates/selfarchiver.xml
(alle meine Vorlagen: s3lfcod3r/unraid-templates)
hinzufügen oder unter Docker → Add Container → Template importieren. APP_SECRET und AUTH_PASSWORD setzen und /data z. B. auf /mnt/user/appdata/selfarchiver mappen.
Das Image liegt auf GHCR: ghcr.io/s3lfcod3r/selfarchiver:latest.
⚠️ APP_SECRET: einmal setzen und behalten — eine Änderung macht die gespeicherten Postfach-Passwörter unlesbar.
⚠️ Rechte: der Container startet nur als root, um das Volume
/dataperchownvorzubereiten, und wechselt dann pergosuzum Nutzernode(uid1000) ohne Root-Rechte.
⚙️ Konfiguration
Umgebungsvariablen (ohne gemeinsames Präfix).
| Variable | Pflicht | Standard | Zweck |
|---|---|---|---|
PORT |
– | 3000 |
HTTP-Port |
APP_SECRET |
– | (auto) | Verschlüsselt die Postfach-Passwörter + signiert Sitzungen (≥ 32 Zeichen). Leer = wird einmal erzeugt und in /data/.secret gespeichert. Setzen und stabil halten. |
AUTH_PASSWORD |
– | (leer) | Optionales UI-Passwort. Leer = keine Anmeldung, Server bindet nur an 127.0.0.1 |
HOST |
– | 0.0.0.0 |
Bind-Adresse; ohne AUTH_PASSWORD nur wirksam, wenn ausdrücklich gesetzt |
COOKIE_SECURE |
– | false |
Auf true setzen, wenn über HTTPS (hinter einem TLS-Proxy) bereitgestellt, damit das Sitzungs-Cookie nur über sichere Verbindungen gesendet wird (aktiviert auch HSTS) |
TZ / CRON_TZ |
– | Europe/Berlin |
Zeitzone für die Zeitpläne (Standard in compose/Unraid; ohne Docker fällt der Code auf UTC zurück) |
DATA_DIR |
– | /data |
Ort der SQLite-DB + des .eml-Archivs |
DB_PATH |
– | $DATA_DIR/selfarchiver.sqlite |
SQLite-Datei |
ARCHIVE_DIR |
– | $DATA_DIR/archive |
Ordner des .eml-Archivs |
LOG_LEVEL |
– | info |
trace … error |
🔌 API-Übersicht
Basispfad /api, Anmeldung per Sitzungs-Cookie (nur wenn AUTH_PASSWORD gesetzt ist). Health-Check: GET /api/health.
| Bereich | Endpunkte (Auszug) |
|---|---|
| Auth | login, logout, session |
| Quellen | sources (CRUD), sources/test-connection, sources/{id}/test, sources/{id}/folders |
| Regeln | rules (CRUD), rules/validate-cron, rules/{id}/run |
| Archiv | emails, emails/folders, emails/{id}, …/download, …/content, …/attachment/{index}, emails/delete-folder |
| Aktivität | runs, runs/{id}/emails, settings |
| Dashboard | dashboard, health |
🛡️ Sicherheit
- Postfach-Passwörter AES-256-GCM-verschlüsselt mit einem aus
APP_SECRETabgeleiteten Schlüssel — Verlust/Änderung des Secrets macht sie unwiederbringlich - Serverseitige Sitzungen (Zufalls-ID, HMAC-signiertes Cookie,
HttpOnly,SameSite=Lax), beim Abmelden widerrufen; Rate-Limit beim Login (10 Versuche / 15 Min) mit zeitkonstantem Passwortvergleich - CSRF-Schutz: ändernde Anfragen mit fremdem
Originwerden abgelehnt - Ohne
AUTH_PASSWORDbindet der Server nur an Loopback - Sicherheits-Header (CSP,
X-Frame-Options: DENY,nosniff,no-referrer, HSTS mitCOOKIE_SECURE); archiviertes HTML wird in einem abgeschotteten iframe mit eigener strenger CSP angezeigt - Absturzsicheres Archivieren: die
.emlwird geschrieben + per fsync gesichert, bevor der DB-Eintrag folgt; aus dem Postfach gelöscht werden nur Mails, die im Archiv liegen; das Löschen eines Archiv-Ordners verlangt die erwartete Anzahl - Hinter HTTPS (Reverse Proxy) betreiben, wenn über ein vertrauenswürdiges LAN hinaus erreichbar
- Bewusste Kompromisse (dokumentiert): ein gemeinsames Passwort (keine Benutzerkonten); Sitzungen liegen im Speicher und enden beim Neustart; Archivieren, dann löschen ist auf Postfach-Seite unumkehrbar — die Archivkopie bleibt, behandle es wie jede Aufbewahrungsrichtlinie
Verlauf der Sicherheitsupdates → CHANGELOG.md (Einträge mit 🔒).
🧱 Tech-Stack
| Teil | Technik |
|---|---|
| Backend | Node 22 · Fastify · better-sqlite3 (SQLite WAL + FTS5) · imapflow · mailparser · node-cron · cron-parser · zod · pino |
| Web | React · Vite · TypeScript · Tailwind CSS · React Router |
| Deploy | Docker (Multi-Stage, läuft als node per gosu) · GHCR · Unraid |
🛠️ Entwicklung
npm install
npm run dev # Backend auf :3000 (tsx watch)
npm run dev:web # Frontend auf :5173 (Vite, leitet /api weiter)
npm run build # Web bauen + Server vorbereiten
Prüfungen (noch keine automatischen Tests):
npm run typecheck # beide Workspaces typprüfen
🗺️ Roadmap
- IMAP-Quellen · Ordnerauswahl · selbstsignierte Zertifikate
- Regeln: Filter · Alter in Tagen/Stunden · Zeitplan pro Regel · archivieren, dann löschen
- Archiv: Volltextsuche · Mail-Ansicht ·
.eml- + Anhang-Download · Mails/Ordner löschen - Aktivität: filterbare Lauf-Historie · archivierte Mails je Lauf · Aufbewahrung der Historie
- Sicherheits-Härtung (Sitzungen, Header, ohne Root, CSRF, absturzsicheres Archivieren)
- 12 Oberflächen-Sprachen · Handy-Ansicht
☕ Support / Unterstützen
🇬🇧 This project is free for private use and built in my spare time. If it saves you time, a coffee keeps the next update coming. No pressure, a ⭐ on the repo helps too!
🇩🇪 Dieses Projekt ist für private Nutzung kostenlos und entsteht in meiner Freizeit. Wenn es dir Zeit spart, hält ein Kaffee das nächste Update am Laufen. Kein Muss, ein ⭐ auf dem Repo hilft auch!
⚖️ Lizenz / License
🇩🇪 Alle Rechte vorbehalten. © 2026 s3lfcod3r / SelfCoder
Du darfst die Software privat und nicht-kommerziell installieren und benutzen (z. B. im Homelab, über Docker oder Unraid).
Ohne schriftliche Erlaubnis verboten: kommerzielle Nutzung · Kopieren · Verändern · Weitergeben · Einbauen in eigene Projekte (auch Closed Source) · Verkaufen.
Details: LICENSE
🇬🇧 All rights reserved. © 2026 s3lfcod3r / SelfCoder
You may install and use the software privately and non-commercially (e.g. in your home lab, via Docker or Unraid).
Not permitted without written permission: commercial use · copying · modifying · redistributing · incorporating into other projects (including closed source) · selling.
Details: LICENSE
SelfArchiver · part of the Self family · Teil der Self-Familie
made with 🗄️ for self-hosting
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/s3lfcod3r/selfarchiver:latestRuntime arguments
- Web UI
http://[IP]:[PORT:3000]/- Network
bridge- Shell
sh- Privileged
- false
- Extra Params
--restart=unless-stopped
Template configuration
SQLite database and the .eml archive. Grows with the archived mail - choose a share with enough space.
- Target
- /data
- Default
- /mnt/user/appdata/selfarchiver
- Value
- /mnt/user/appdata/selfarchiver
Port for the SelfArchiver web interface.
- Target
- 3000
- Default
- 3000
- Value
- 3000
Stable secret for encrypting stored mailbox passwords and signing sessions. Generate with: openssl rand -hex 32. Keep it constant - changing it makes stored mailbox passwords unreadable. Empty = generated once and stored in the data folder.
- Target
- APP_SECRET
Password protecting the web UI. Empty = open instance (trusted private network only).
- Target
- AUTH_PASSWORD
Timezone used for the per-rule schedules.
- Target
- TZ
- Default
- Europe/Berlin
- Value
- Europe/Berlin
Timezone for evaluating the cron schedules. Normally the same as Timezone.
- Target
- CRON_TZ
- Default
- Europe/Berlin
- Value
- Europe/Berlin
Set to true when the UI is served over HTTPS only (reverse proxy), so the session cookie is sent over secure connections only.
- Target
- COOKIE_SECURE
- Default
- false
- Value
- false
Log verbosity: trace, debug, info, warn, error.
- Target
- LOG_LEVEL
- Default
- info
- Value
- info