KI-AGENT: Gmail-Anhänge-Download-Skript hinzufügen

docs/bedienung/gmail-anhaenge-herunterladen.md

@@ -0,0 +1,59 @@
+# Gmail-Anhänge herunterladen
+
+Das Skript `scripts/download-gmail-attachments.py` lädt Anhänge aus einem Gmail-Postfach per IMAP herunter. Es nutzt nur Python-Standardbibliotheken.
+
+## Voraussetzungen
+
+- IMAP muss im Gmail-Konto aktiviert sein.
+- Für Konten mit Zwei-Faktor-Authentifizierung wird ein Gmail App-Passwort benötigt.
+- Python 3.9 oder neuer.
+
+## Beispiele
+
+Alle Anhänge aus dem kompletten Gmail-Postfach herunterladen:
+
+```bash
+GMAIL_APP_PASSWORD="dein-app-passwort" \
+python3 scripts/download-gmail-attachments.py \
+  --email name@gmail.com \
+  --output gmail-anhaenge \
+  --group-by-message
+```
+
+Nur Anhänge ab einem bestimmten Datum herunterladen:
+
+```bash
+GMAIL_APP_PASSWORD="dein-app-passwort" \
+python3 scripts/download-gmail-attachments.py \
+  --email name@gmail.com \
+  --since 2026-01-01 \
+  --output gmail-anhaenge
+```
+
+Nur ungelesene Mails durchsuchen:
+
+```bash
+GMAIL_APP_PASSWORD="dein-app-passwort" \
+python3 scripts/download-gmail-attachments.py \
+  --email name@gmail.com \
+  --search UNSEEN
+```
+
+Verfügbare IMAP-Postfächer anzeigen, falls `[Gmail]/All Mail` nicht passt:
+
+```bash
+GMAIL_APP_PASSWORD="dein-app-passwort" \
+python3 scripts/download-gmail-attachments.py \
+  --email name@gmail.com \
+  --list-mailboxes
+```
+
+Wenn `--password` nicht gesetzt ist und `GMAIL_APP_PASSWORD` fehlt, fragt das Skript das Passwort interaktiv ab.
+
+## Häufige Optionen
+
+- `--mailbox "[Gmail]/All Mail"` durchsucht standardmäßig alle Mails.
+- `--list-mailboxes` zeigt alle verfügbaren Gmail-IMAP-Postfächer an.
+- `--group-by-message` legt pro Mail einen Unterordner an.
+- `--overwrite` überschreibt vorhandene Dateien.
+- `--since YYYY-MM-DD` und `--before YYYY-MM-DD` grenzen den Zeitraum ein.