archivmail/features/PROJ-2-import-eml-mbox.md

PROJ-2: E-Mail-Import: EML/MBOX Upload

Status: In Progress

Created: 2026-03-12 Last Updated: 2026-03-12

Dependencies

• Requires: PROJ-1 (Authentifizierung) – nur eingeloggte Admins dürfen importieren
• Requires: PROJ-5 (Speicherung & Indexierung) – importierte E-Mails werden gespeichert

User Stories

• Als Admin möchte ich EML-Dateien per Drag-and-Drop hochladen, damit ich einzelne E-Mails archivieren kann.
• Als Admin möchte ich MBOX-Dateien importieren, damit ich ganze Postfach-Exporte auf einmal archivieren kann.
• Als Admin möchte ich den Fortschritt eines laufenden Imports sehen, damit ich weiß wie weit der Import ist.
• Als Admin möchte ich nach dem Import eine Zusammenfassung sehen (importiert, übersprungen, Fehler), damit ich Probleme nachvollziehen kann.
• Als System möchte ich Duplikate erkennen und überspringen, damit E-Mails nicht doppelt archiviert werden.

Acceptance Criteria

• Upload-Interface akzeptiert .eml und .mbox Dateien (auch mehrere gleichzeitig)
• Maximale Dateigröße konfigurierbar (Standard: 500 MB pro Upload)
• EML-Parser liest Envelope-Header (From, To, CC, BCC, Date, Subject, Message-ID)
• MBOX-Parser iteriert über alle enthaltenen E-Mails in der Datei
• Anhänge werden extrahiert und getrennt gespeichert
• Fortschrittsanzeige während des Imports (Anzahl verarbeitet / gesamt)
• Duplikate (gleiche Message-ID) werden erkannt und übersprungen
• Import-Zusammenfassung: Anzahl importiert, übersprungen, fehlerhaft
• Fehlerhafte E-Mails (korrupte Dateien) werden geloggt und übersprungen, brechen Import nicht ab

Edge Cases

• MBOX-Datei mit 100.000+ E-Mails → chunked processing, kein Timeout
• EML-Datei ohne Message-ID → synthetische ID generieren (Hash des Inhalts)
• E-Mail mit verschachtelten MIME-Teilen (multipart/mixed, multipart/alternative)
• Encoding-Probleme (ISO-8859-1, Windows-1252) → automatische Konvertierung zu UTF-8
• Upload wird unterbrochen → partiell importierte Daten bereinigen

Technical Requirements

• Streaming-Upload für große Dateien (kein komplettes In-Memory-Laden)
• MBOX-Parsing als Background-Job mit Statusrückmeldung via WebSocket oder Polling
• Maximale Anhang-Größe pro E-Mail konfigurierbar

---

Tech Design (Solution Architect)

Komponentenstruktur

Next.js Frontend (Admin-Bereich):

/admin/upload
├── DropZone                        ← Drag-and-Drop + Datei-Dialog
│   ├── akzeptiert: .eml, .mbox
│   └── Mehrfachauswahl möglich
├── Upload-Queue                    ← Liste der hochgeladenen Dateien
│   └── FileItem (pro Datei)
│       ├── Dateiname + Größe
│       ├── Typ-Badge (EML / MBOX)
│       └── Status (wartend / läuft / fertig / Fehler)
├── Fortschrittsanzeige (pro Datei)
│   ├── Fortschrittsbalken (X von Y Mails verarbeitet)
│   └── Aktueller Status
└── Abschlussbericht
    ├── Importiert: X
    ├── Übersprungen (Duplikate): Y
    └── Fehler: Z (mit Liste der fehlerhaften Mails)

Go Backend:

POST /api/admin/upload
├── Session Middleware (Admin)
├── Multipart-Stream-Handler        ← Datei wird nicht komplett in RAM geladen
├── Dateityp-Erkennung (.eml / .mbox)
└── Import-Worker starten (Hintergrund-Goroutine)

Import-Worker
├── EML-Modus
│   └── Einzelne Mail direkt parsen → Storage Coordinator
│
├── MBOX-Modus
│   ├── MBOX-Parser (iteriert über "From "-Trennzeilen)
│   ├── Für jede Mail:
│   │   ├── Duplikat-Check (Message-ID)
│   │   └── → Storage Coordinator (PROJ-5)
│   └── Fortschritt in DB schreiben
│
└── Encoding-Normalisierer
    └── ISO-8859-1 / Windows-1252 → UTF-8

GET /api/admin/upload/{job_id}/progress  ← Polling alle 2 Sek.

Upload- und Importfluss

Admin zieht Datei in DropZone
        │
        │  POST /api/admin/upload (multipart/form-data, streaming)
        ▼
Go Backend empfängt Stream
        │
        ├── .eml? → direkt parsen → Storage Coordinator → fertig
        │
        └── .mbox? → Import-Worker (Hintergrund)
                │
                ▼
          MBOX-Parser liest zeilenweise
          Trenner: Zeilen die mit "From " beginnen
                │
                └── Pro Mail:
                      Encoding-Erkennung + UTF-8-Normalisierung
                      Message-ID vorhanden?
                        Nein → SHA-256(Inhalt) als ID
                      Duplikat? → überspringen
                      → Storage Coordinator (PROJ-5)
                      Fortschritt in DB aktualisieren
                │
                ▼
          Abschlussbericht in DB speichern

Next.js pollt GET /progress alle 2 Sek.
→ Fortschrittsbalken aktualisieren
→ Bei status:"done" → Abschlussbericht anzeigen

Technische Entscheidungen

Entscheidung	Begründung
Streaming-Upload	500 MB MBOX nie komplett in RAM – Go liest den HTTP-Body als Stream direkt in den Parser
MBOX zeilenweises Parsen	MBOX-Format trennt Mails durch From –Zeilen – kein vollständiges Einlesen der Datei nötig
Background-Worker + Polling	MBOX mit 100k+ Mails dauert Minuten – HTTP-Request darf nicht so lange offen bleiben
Encoding-Normalisierung	E-Mail-Exporte aus Outlook/Thunderbird kommen oft als ISO-8859-1 – Index und DB erwarten UTF-8
Fehler überspringen, nicht abbrechen	Eine korrupte Mail soll nicht den gesamten Import einer 50k-MBOX-Datei stoppen
Synthetische Message-ID	EML-Dateien ohne Message-ID (selten aber möglich) bekommen SHA-256(Inhalt) – Duplikatschutz bleibt konsistent

Abhängigkeiten

Paket	Zweck
golang.org/x/text/encoding	ISO-8859-1 / Windows-1252 → UTF-8 Konvertierung
mime, mime/multipart	EML + MBOX MIME-Parsing (Stdlib)

QA Test Results

To be added by /qa

Deployment

To be added by /deploy