Mail Filter

Ein selbstständiger Mailfilter für IMAP-E-Mail-Accounts, ähnlich den Filtern in Thunderbird. Prüft regelmäßig auf neue E-Mails und führt Aktionen basierend auf konfigurierbaren Filterregeln aus.

Features

• ✅ IMAP-Integration: Unterstützt alle IMAP-Server (Gmail, Outlook, etc.)
• ✅ SMTP-Integration: E-Mail-Versendung für Forward/Reply (pro Account konfigurierbar)
• ✅ Flexible Filter: Kriterien basierend auf Absender, Betreff, Body, Anhängen, Größe, Datum
• ✅ Mehrere Aktionen: Verschieben, Löschen, Weiterleiten, Antworten, Externe Scripts
• ✅ Prioritätssystem: Filter mit Prioritäten, mehrere Aktionen pro E-Mail möglich
• ✅ Multi-Account: Unterstützung für mehrere E-Mail-Accounts
• ✅ State-Management: SQLite-basiertes Tracking verarbeiteter E-Mails
• ✅ Sicherheitsfeatures: Rate Limiting, Script-Whitelist, Delete → Trash, Action-Limits
• ✅ Monitoring: Error-Notifications und tägliche Reports per E-Mail

Schnellstart

Voraussetzungen

• Python 3.8+
• pip

Installation

1. Repository klonen:

git clone <repository-url>
cd mail-filter

2. (Optional) Python Virtual Environment erstellen

   Empfohlen: Verwende ein Python Virtual Environment, um Abhängigkeiten isoliert zu installieren.

   Linux/Mac:

   python3 -m venv venv
   source venv/bin/activate
   

   Windows:

   python -m venv venv
   venv\Scripts\activate
   

3. Abhängigkeiten installieren:

pip install -r requirements.txt

4. Konfiguration einrichten:

Option A: Konfiguration im Code-Repo (für Entwicklung/Test)

cp config/config.yaml.example config/config.yaml
cp filters/work_rules.yaml.example filters/work_rules.yaml

Option B: Getrenntes Config-Repo (für Produktion empfohlen)

# Separates privates Config-Repo klonen
git clone <config-repo-url> /opt/mail-filter-config

# Credentials erstellen
mkdir -p /opt/mail-filter-config/config/credentials
# Credentials-Dateien manuell erstellen (siehe Format unten)

5. Konfiguration anpassen und Credentials erstellen (siehe Dokumentation)

6. Ersten Test durchführen:

python main.py validate-config
python main.py test-connection <account-name>
python main.py check --account <account-name> --dry-run

Verwendung

Mit Wrapper-Script (Empfohlen)

Nach der Installation des Wrappers (siehe INSTALL_WRAPPER.md):

Mit Standard-Konfiguration (config/config.yaml):

# Scheduler starten
mail-filter run

# Einmaliger Check
mail-filter check

# Verbindung testen
mail-filter test-connection <account-name>

# Konfiguration validieren
mail-filter validate-config

# Statistiken zurücksetzen
mail-filter reset-statistics --today --confirm

Mit externer Konfiguration (z.B. getrenntes Config-Repo):

# Scheduler starten
mail-filter --config /opt/mail-filter-config/config/config.yaml run

# Einmaliger Check
mail-filter --config /opt/mail-filter-config/config/config.yaml check

# Verbindung testen
mail-filter --config /opt/mail-filter-config/config/config.yaml test-connection <account-name>

# Konfiguration validieren
mail-filter --config /opt/mail-filter-config/config/config.yaml validate-config

Direkt mit Python

# Scheduler starten (Standard-Konfiguration)
python main.py run

# Mit externer Konfiguration
python main.py --config /opt/mail-filter-config/config/config.yaml run

# Einmaliger Check
python main.py check
python main.py --config /opt/mail-filter-config/config/config.yaml check

# Weitere Befehle
python main.py test-connection <account-name>
python main.py validate-config
python main.py reset-statistics --today --confirm
python main.py --help

Hinweis:

• Wenn du ein venv verwendest, stelle sicher, dass es aktiviert ist, oder verwende den Wrapper-Script.
• Mit --config kannst du eine Konfigurationsdatei an beliebiger Stelle angeben. Die Pfade zu accounts.yaml, credentials/ und filters/ werden automatisch relativ zum Verzeichnis der config.yaml aufgelöst (siehe Konfiguration).

Dokumentation

Die vollständige Dokumentation befindet sich im Wiki-Repository, das als Submodule eingebunden werden kann.

Wiki-Submodule einbinden

Wenn du das Repository bereits geklont hast:

# Submodule initialisieren und aktualisieren
git submodule update --init --recursive

Wenn du das Repository neu klonst:

# Repository mit Submodules klonen
git clone --recurse-submodules <repository-url>

Wiki-Dokumentation betrachten

Die Wiki-Dokumentation kann auf verschiedene Weise betrachtet werden:

Option 1: Über das Wiki-Interface (Online) - Empfohlen

Die Dokumentation ist online im Wiki verfügbar:

• Home - Übersicht und Navigation
• Installation - Detaillierte Installationsanleitung
• Konfiguration - Konfigurationsoptionen
• Accounts - IMAP- und SMTP-Konfiguration
• Filter - Filterkriterien und -optionen
• Aktionen - Verfügbare Aktionen
• Verwendung - CLI-Befehle und Parameter
• Sicherheit - Sicherheitsfeatures
• State-Management - State-Datenbank
• Logging - Logging und Fehlerbehebung
• Entwicklung - Code-Struktur

Wiki-Startseite: https://git.home.schumbi.de/ralf/mail-filter/wiki

Option 2: Lokal lesen

Die Wiki-Dateien befinden sich im Verzeichnis doc/ und können lokal gelesen werden:

• VS Code: Installiere die "Markdown Preview" Extension
• Editor: Öffne die .md Dateien in einem Markdown-fähigen Editor
• Terminal: Verwende einen Markdown-Viewer wie glow oder mdless

Wiki aktualisieren

Um die neueste Version der Wiki-Dokumentation zu erhalten:

git submodule update --remote doc

Konfiguration

Konfigurationsstruktur

Der Mail-Filter unterstützt zwei Konfigurationsmodi:

1. Standard-Modus (Konfiguration im Code-Repo)

Die Konfiguration liegt direkt im Code-Repository:

mail-filter/
├── config/
│   ├── config.yaml          # Hauptkonfiguration
│   └── credentials/         # Credentials-Dateien
├── filters/
│   └── *.yaml               # Filterregeln

Verwendung:

mail-filter run  # Verwendet automatisch config/config.yaml

2. Getrenntes Config-Repo (Empfohlen für Produktion)

Die Konfiguration liegt in einem separaten, privaten Repository:

mail-filter-config/
├── config/
│   ├── config.yaml          # Hauptkonfiguration (ohne Passwörter)
│   ├── accounts.yaml        # Account-Konfigurationen
│   └── credentials/         # Credentials-Dateien (nicht versioniert)
└── filters/
    └── *.yaml               # Filterregeln

Verwendung:

mail-filter --config /opt/mail-filter-config/config/config.yaml run

Automatische Pfadauflösung: Wenn config_paths nicht in config.yaml definiert sind, werden die Pfade automatisch relativ zum Verzeichnis der config.yaml aufgelöst:

• accounts_file: <config-dir>/accounts.yaml
• credentials_dir: <config-dir>/credentials
• filters_dir: <config-dir>/../filters

Explizite Pfade (optional): Falls die Standard-Struktur nicht passt, können config_paths in config.yaml explizit angegeben werden:

config_paths:
  filters_dir: "/opt/mail-filter-config/filters"
  credentials_dir: "/opt/mail-filter-config/config/credentials"
  accounts_file: "/opt/mail-filter-config/config/accounts.yaml"

Siehe auch: config/config.yaml.example für detaillierte Konfigurationsoptionen.

Projektstruktur

mail-filter/                    # Code-Repository
├── config/
│   ├── config.yaml.example     # Beispiel-Konfiguration
│   └── credentials/            # Credentials-Dateien (optional)
├── filters/
│   └── *.yaml.example          # Beispiel-Filterregeln
├── templates/                  # Reply-Templates
├── scripts/                    # Externe Scripts
├── state/                      # SQLite-Datenbank
├── logs/                       # Log-Dateien
├── attachments/                # Gespeicherte Anhänge
├── doc/                        # Wiki-Dokumentation (Submodule)
├── src/                        # Quellcode
└── main.py                     # Haupteinstiegspunkt

Lizenz

[Deine Lizenz hier]

Beitragen

[Deine Contributing-Guidelines hier]