# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-03-04

HANDLER-NAME: email
Email-Versand via Gmail API mit integrierter Draft-Sicherheit.

BESCHREIBUNG:
Der Email-Handler ermöglicht sicheren E-Mail-Versand über die Gmail API.
Jede Email wird zuerst als Entwurf erstellt und muss explizit mit 'confirm'
bestaetigt werden, bevor sie gesendet wird. Dies verhindert versehentliche
Email-Versaendung.

OPERATIONEN:

  send <to> <subject> <body>              Entwurf erstellen (Hauptbefehl)
    Optionen: --cc <email>, --bcc <email>, --attach <dateipfad>

  draft <to> <subject> <body>             Alias für send

  confirm <id>                            Entwurf bestaetigen und senden
    Optionen: --by <name>

  cancel <id>                             Entwurf verwerfen (löschen)

  drafts                                  Offene Entwuerfe auflisten
    Alias: list (leerer Befehl zeigt auch Entwuerfe)

  sent                                    Gesendete Mails anzeigen

  show <id>                               Entwurf-Details anzeigen
    Zeigt vollständigen Text, Empfaenger, CC/BCC, Status

  setup                                   Gmail API Scopes erweitern (einmalig)
    Benötigt OAuth2-Authentifizierung für readonly + send

  test                                    Test-Email an eigene Adresse senden

  help                                    Diesen Hilfe-Text anzeigen

BEISPIELE:

  1. Entwurf mit positional args erstellen:
     bach email send user@example.com "Betreff" "Hallo Welt"

  2. Entwurf mit Named Args:
     bach email send user@example.com --subject "Meeting" --body "Termin: 14:00"

  3. Mit CC und Anhang:
     bach email send user@example.com \
       --subject "Bericht" \
       --body "Siehe Datei" \
       --cc admin@example.com \
       --attach C:\dokumente\report.pdf

  4. Entwurf versenden:
     bach email confirm 42

  5. Entwurf verwerfen:
     bach email cancel 42

  6. Alle offenen Entwuerfe anzeigen:
     bach email drafts

DATEIEN:

  hub/email.py                            Dieser Handler (EmailHandler Klasse)
  _services/mail/email_sender.py          Gmail API Integration, Draft-Verwaltung
  _services/mail/account_manager.py       OAuth2 Token-Verwaltung
  data/bach.db                            Lokale Email-Metadaten (Draft-Records)

SICHERHEIT:

  - Draft-Modell: Jede Email wird zuerst als Entwurf gespeichert
  - Explizite Bestaetigung: Nur 'confirm' sendet tatsaechlich
  - Token-Scopes: readonly + send (Gmail API oauth2)
  - Fehlerbehandlung: Fehler werden in DB geloggt (show <id> zeigt Details)

KONFIGURATION:

  Account: Gesteuert über ~/.config/paper_publisher/config.json oder
           lokale OAuth2-Token unter _services/mail/tokens/

FEHLERBEHANDLUNG:

  - Ungueltige Email-Adressen werden sofort rejiziert
  - Fehlende Betreff/Text werden gemeldet
  - Gmail-Fehler werden mit Betreff und ID protokolliert
  - Entwurf kann jederzeit mit cancel verworfen werden

SIEHE AUCH:

  docs/help/base.txt                      Handler-Basisklasse
  docs/help/telegram.txt                  Telegram-Integration für Remote-Control
  _services/mail/README.md                Gmail API Setup-Anleitung
