Paperless-ngx, Teil 11: Mail-Abruf mit vielen Extras
Die meisten Dokumente erreichen uns inzwischen in Form eines Mail-Anhangs: Rechnungen, Aufstellungen, Protokolle, Zugangsdaten usw. usw. Dazu kommen noch unterschiedliche Konten bei verschiedenen Mail-Anbietern: Hier ein beruflicher Account mit „maier@unixyz.de“, da einer vom Verein mit „info@vereinxyz.com“ und dort noch ein privater mit „udo_0815@web.de“. Natürlich könnte man die Anhänge exportieren, speichern und nach Paperless-ngx schieben. Aber es geht viel einfacher: Paperless-ngx kann Mail-Konten auf Wunsch abrufen und Anhänge in das Dokumentenarchiv aufnehmen.
Inhalt
Beispiele für einen Abruf
Paperless-ngx schaut wie ein „normales“ Mailprogramm nach der Post auf dem Mailserver. Sofern ein E-Mail-Anhang den vorgegebenen Kriterien entspricht, nimmt Paperless-ngx diesen Anhang in sein Archiv auf. Hier zwei Beispiele:
Beispiel für die automatische Aufnahme:
Eine Kriterienvorgabe könnte lauten: „Falls der Absender einer Mail ’schmidt@schornsteinfeger-ulm.de‘ ist und die Betreffzeile das Wort ‚Rechnung‘ aufweist, so nimm den Anhang in das Archiv auf, vergib die Tags ‚Eingang‘ und ‚Rechnung‘ und speichere das Dokument auf dem Dateipfad ‚/2024/Nebenkosten‘.
Beispiel für die manuelle Zuordnung:
Die Mails werden vorab vom Empfänger durchgesehen. Sofern ein Anhang für das Archiv interessant ist, wird die Mail in den Ordner „Paperless“ des E-Mail-Programms verschoben. Paperless-ngx erkennt, dass eine neue Datei in diesem Mail-Ordner ist, nimmt den Anhang in sein Archiv auf, markiert die Mail als gelesen und verschiebt sie in den Mail-Ordner „verarbeitet“.
Privates bleibt privat
Das „Nachschauen“ nach interessanten Anhängen erledigt Paperless-ngx in der gleichen Weise, wie dies auch durch Mail-Programme wie Outlook oder Thunderbird geschieht: Es werden die Zugangsdaten für den Abruf in der Anwendung eingetragen – aber alles wird lokal über den kleinen Raspberry Pi abgewickelt. Es sind also keine zusätzlichen Stellen oder Server involviert. Und Paperless-ngx holt auch keineswegs alle Anhänge ab – es richtet sich nach Kriterien, die man zuvor festgelegt hat. Einzige Bedingung: Der Post-Server muss ein IMAP-Server sein – aber das ist heute fast immer der Fall. Auch „doppelt gesicherte“ Postfächer, die durch einen zweiten Faktor gesichert sind, können durch Paperless-ngx abgerufen werden. Denn für diesen Fall kann man ein „anwendungsspezifische“ Passwort generieren, das man in die Paperless-ngx-Anwendung einträgt.
Erster Schritt: E-Mail-Konten einrichten
Es können beliebig viele E-Mail-Konten für den Abruf eingerichtet werden. Dabei ist es gleichgültig, ob es sich um unterschiedliche Mailanbieter handelt oder man bei einem Anbieter mehrere Konten führt. Da es unzählige Anbieter gibt, beschränke ich mich bei den folgenden Beispielen auf die Anbieter „Web.de“ und „Gmail“. Die Übertragung auf GMX, eine Uni-Mail-Adresse, Proton, Mailbox usw. sollte leicht fallen.
Es sind nur wenige Felder auszufüllen:
- IMAP-Server: Ja nach Anbieter. Bei „web.de“ lautet der Eintrag „imap.web.de“, bei Gmail „imap.gmail.com“ usw.
- IMAP-Port: sollte bei den meisten Anbietern 993 sein
- IMAP-Sicherheit: SSL
- Benutzername: je nach Anbieter – z.B. „musterperson@web.de“
- Passwort: das Zugangspasswort
Web.de und Gmail bieten jeweils in den Sicherheitseinstellungen des Kontos an, ein gesondertes Passwort für Paperless-ngx zu erstellen, sofern man den Zugang mit einem zweiten Faktor abgesichert hat. Hilfeseite Web.de, Hilfeseite Gmail
Bei Web.de muss man, sofern noch nicht geschehen, den IMAP-Zugriff in einem zusätzlichen Schritt aktivieren (IMAP-Aktivierung Web.de).
Die Standardeinstellung ist, dass die Konten alle 10 Minuten auf neue Anhänge von Paperless-ngx überprüft werden.
Zweiter Schritt: Kriterien für den Abruf definieren
Besonderheiten von Mail-Programmen
IMAP-Server stellen, etwas verkürzt ausgedrückt, für die Verwaltung der E-Mails nur ein sehr einfaches Grundgerüst zur Verfügung: Eine INBOX mit Unterordnern, dazu Kennzeichnungen wie „Entwurf“ oder „wichtig“. Die Bezeichnungen, die ein Anbieter verwendet, können unterschiedlich sein. So verwendet Gmail beispielsweise die Bezeichnung „Label“, die meisten Anbieter behalten aber den Begriff „Ordner“ bei. Dafür kennen Mail-Programme wie Thunderbird sowohl Ordner als auch Labels usw. iCloud wiederum fährt ein System mit farblichen Etiketten (was von Paperless-ngx übrigens auch genutzt werden kann.). Meist sind farbliche Kennzeichnungen, zusätzliches Tags oder Filter, Gruppierungen, Darstellungen usw. Funktionen, das jeweilige Mail-Programm für den Anwender zur Verfügung stellt. Hingegen kann Paperless-ngx nur das abfragen, was der IMAP-Server in seinen Standardfunktionen zur Verfügung stellt.
E-Mail-Regel bearbeiten
Für die Definition der Abruf-Regel stellt Paperless-ngx ein Formular zur Verfügung. Das Formular sieht umfangreich aus, aber es sind nur wenige Eintragungen notwendig, damit der Abruf klappt.
In diesem Beispiel erfolgt ein Abruf über Web.de (die Zugangsdaten wurden zuvor in ein Konto eingetragen, das den Namen „Web.de-2“ [1] trägt).
[2] Im Posteingang wurde ein Ordner „ppl-Rechnungen“ angelegt. Der Ordner kann über das Web-Frontend von Web.de oder über das lokale Mail-Programm, etwa Thunderbird, eingerichtet werden.
Der Ordner „ppl-Rechnungen“ wird in der Standardeinstellung alle 10 Minuten überprüft (die Mails darin sollten die Markierung „ungelesen“ aufweisen). Mit [3] wird vorgegeben, dass sich Paperless-ngx um keine Anhänge kümmern soll, die älter als 10 Tage sind. Unter [4] wird dem Programm gesagt, dass nur der Anhang nicht aber die Text der Mail ins Archiv wandern soll.
Mit [5] wird die Reihenfolge der Abarbeitung der Regeln bestimmt. In diesem Beispiel werden zuerst die Mails der letzten 10 Tage aus dem Ordner geholt. Vielleicht gibt es noch eine zweite Regel, die ohne zeitliche Begrenzung alle Mails mit dem Stichwort „Angebot Anbau“ abrufen soll. Trägt diese im Feld „Regelreihenfolge“ eine „2“, so wird sie erst nach der ersten Regel ausgeführt und holt aus dem Ordner vielleicht einen Anhang, der z.B. 14 Tage alt ist.
Unter „Aktion“ [6] ist ausgewählt „In angegebenen Ordner verschieben“. Unter [7] wird der Name des gewünschten Ziel-Ordners genannt: „verarbeitet“.
Das bedeutet: Paperless-ngx nimmt zunächst den Anhang der Mail ins Archiv auf, anschließend wird von Paperless-ngx die bearbeitete Mail in den Mail-Ordner „verarbeitet“ verschoben.
Mit [8] erhält das Dokument Tags im Paperless-ngx-Archiv.
Für Gmail kann die gleiche Regel definiert werden. Der Unterschied zu Web.de: In Gmail muss es seich bei „ppl-Rechnungen“ und „verarbeitet“ um Labels handeln.
Alternativ kann mit den Feldern in der Mitte des Formulars ein automatischer Abruf definiert werden. Etwa könnte unter „Absender filtern“ die „Sparkasse Ulm“ eingetragen werden und unter „Filter: Anhang-Dateiname enthält“ der Begriff „Kontoauszug*.pdf“ eingetragen werden. Paperless-ngx übernimmt dann alle Anhänge der Sparkasse Ulm mit Namen wie „Kontoauszug-2024-01.pdf“ ins Archiv, vergibt den Tag „Kontoauszug“ und weist den Korrespondenten „Sparkasse“ zu. Allerdings muss man darauf achten, dass es sich um UND-Verknüpfungen handelt. Beide Bedingungen müssen im Beispiel erfüllt sein. Ein Anhang mit dem Namen „Kontoauszug.pdf“, der als Absender „DKB“ aufweist, wird nicht aufgenommen. Lässt man hingegen den Absender weg, so landen alle Kontoauszüge in Paperless-ngx.
Tipps
Filter des Mailprogramms für Paperless-ngx nutzen
Mailprogramme wie Outlook oder Thunderbird können selbst recht komplexe Filter definieren. Diese Möglichkeiten kann man auch für Paperless-ngx nutzen. Bleiben wir beim Beispiel Thunderbird mit dem Ordner „ppl-Rechnungen“. Hier ist eine Möglichkeit, die Mail per Hand in den gewünschten Ordner zu verschieben. Da gerade unter Thunderbird viele Anwender recht gerne mit Schlagwörtern arbeiten, kann man diese für eine Filteranweisung nutzen.
Zunächst definiert mit die gewünschten Schlagwörter, z.B. „ppl-Rechnungen“:
Mit „Extras“, „Filter“ definiert man in Thunderbird anschließend folgende Bedingung: „Wenn eine Mail das Schlagwort ‚ppl-Rechnungen‘ zugewiesen bekommt -> dann verschiebe die Mail in den Ordner ‚ppl-Rechnungen‘ UND markiere diese Mail als ‚ungelesen'“:
Nachrichtentext einbeziehen
Oft benötigt man zusätzlich zum Anhang Infos aus dem eigentlichen Mail-Text. Um diesen einzubeziehen, gibt es verschiedene Möglichkeiten. In meinen Tests hat die folgende Variante recht gut funktioniert:
Im Abrufformular gibt es das Feld „Verarbeitungsumfang“ mit der Option „Nachricht als .eml und Anhänge separat verarbeiten …“.
Bei dieser Auswahl wird ein weiteres PDF-Dokument von Paperless-ngx generiert. Das Resultat sieht dann so aus:
Unter [1] findet sich wie gewohnt der eigentliche Anhang. [2] enthält das Anschreiben.
Ab Paperless-ngx 2.1 kann man beide Dokumente verlinken:
Bisherige Teile der Paperless-ngx-Serie:
Teil 1: Ausführlicher Überblick
Teil 2: Suche & Tags
Teil 3: consume-Ordner – Einsatz von Scannern
Teil 4: Speicherpfade konfigurieren
Teil 5: Installation auf dem Raspberry Pi
Teil 6: Neue Funktionen in Version 2
Teil 7: Dokumente unterwegs über das eigene Modem abrufen
Teil 8: Exportfunktion nutzen
Teil 9: Update durchführen
Teil 10: Das Rundum-sorglos-Backup
Teil 11: Mail-Abruf mit vielen Extras
Teil 12: Mein Alltag mit Paperless-ngx
Teil 13: Ein Quanten-Code für das Papier-Archiv
FORUM für Fragen eröffnet
Teil 14: Automatisierte Ablage auf Speicherpfaden
Teil 15: Neue Funktion für das Verbinden und Trennen von Dokumenten
Das könnte dich ebenfalls interessieren
Paperless-ngx, Teil 12: Mein Alltag mit Paperless-ngx
Paperless-ngx, Teil 10: Das Rundum-sorglos-Backup
19 Kommentare
Frank Wächtler
Hallo!
Vielen Dank für die Infos in Teil des 11 zu Paperless-NGX.
Kann es sein, dass man das benutzerdefinierte Feld für die Dokumentenverlinkung zu dem Anhang der E-Mail jedesmal hinzufügen muss? Oder kann man irgendwo einstellen, dass dieses Feld bei jedem neuem Dokument angezeigt wird?
Noch optimaler wäre natürlich, wenn Paperless die E-Mail und den Anhang der E-Mail automatisch verknüpfen würde.
Vielen Dank im Voraus für Deine Rückmeldung!
VG
Frank
Herbert
Das könnte über die neue Funktion „Arbeitsabläufe“ (ab Version 2.4) möglich sein, damit kann man ja E-Mail-Eingang mit den benutzerdefinierten Felder verknüpfen – habe ich aber noch nicht probiert.
Andy
hi, man kann leider nicht dergleichen definieren. Habe es schon probiert.
Das Verknüpfungsfeld füge ich automatisch jedem Dokument/Email hinzu. Aber man kann dann z.b. nicht definieren, dass Dokumente mit dem gleichen Namen zusammengefasst werden.
Vllt kommt ja in Zukunft noch was 🙂
Karl
Tag zusammen,
klasse Seite! Klasse Leute. Weiter so.
Eine kleine Ergänzung aus dem Alltag: auch ich bin kürzlich über Paperless gestolpert und inzwischen fast vollgas unterwegs. Ein bisschen Tuning steht noch bei den Speicherpfaden und Workflows an – ansonsten ist das alles fein.
Die zwei zugehörigen PDF aus einer Email kann man tatsächlich nicht automatisch verknüpfen. Sehr lästig. Allerdings empfinde ich es nicht als besonder praktisch, noch ein Dokument in der Ablage liegen zu haben, wenn das nicht zwingend notwendig ist. An die Information in einer Mail kommt man auch anders: Parsen. Ja, technisch nicht ganz so trivial – aber mir war es den Aufwand wert.
Ich habe einen Workflow vorgeschalten, der mir regelmäßig durch meine Mails kämmt und dabei zB. so Dissidenten wie Apple heraus fischt, die Rechnungen als HTML Mail verschicken. Amis…
Ich brauche aber ein PDF^^ Also lasse ich via N8N lokal einen Workflow laufen, der mir diese Burschen herausfischt, aus dem schicken HTML ein schickes PDF rendert und es im paperless Ordner auf meinem NAS ablegt – bereits mit passendem Dateinamen. Der Upload erfolgt lokal via SFTP. Ein Ordner Sync Cronjob wäre alternativ möglich. Oder WebDAV…je nach Geschmack.
Swen
Vielen Dank für die ausführliche Antwort. Bei mir kommt es zu einem merkwürdigen Verhalten: Ich habe die Verbindung zu Gmail erfolgreich aufgebaut. Dort setzte ich händisch bei relevanten Mails das Label „paperless“. In Paperless-NGX habe ich dann eine entsprechende Regel definiert, die die Anhänge entgegen nimmt und das Label auf „verarbeitet“ setzt. Das klappt bei ca 9 von 10 Mails. Einige bleiben jedoch einfach mit dem Label „paperless“ versehen und nichts passiert. Kann sich das jemand erklären?
Herbert
Wenn es in 90 % der Fälle klappt, dann scheinen Deine Einstellungen ja korrekt zu sein. Aber PDF-Formate und Mail-Formate unterscheiden sich stark. Vielleicht rufst Du mal den Log-File auf, ob Du da einen Hinweis findest.
Peter
Hallo,
leider erhalte ich mit meinen Gmail Zugangsdaten von Paperless die Meldung „Verbinden zum Mailserver nicht möglich“. Exakt diese Zugangsdaten funktionieren in allen anderen Mailprogrammen.
Paperless läuft im Docker unter Proxmox und ließ sich problemlos installieren und updaten, dann sollte doch die Verbindung ins Internet i.O. sein? Woran kann es noch liegen, hat jemand eine Idee?
Herbert
Es kommt nicht nur auf die Zugangsdaten an – die stellen nur die Verbindung zum Mailserver her. Wichtig ist, den richtigen Ordner auf dem iMap-Server anzusprechen (eigentlich kennt iMap weder Ordner noch Tags im üblichen Sinn). Manchmal ist das INBOX – für Gmail habe ich aber ein Beispiel im Text. Probier‘ mal testweise, es genau nach diesem Beispiel zu konfigurieren. Paperless-ngx legt zudem Logs an, die Du direkt über das Web-Frontend aufrufen kannst – darin steht, was die Anwendung beim Abruf der Mail stört.
Peter
@Herbert
Danke für deine Antwort, aber so ganz verstehe ich es nicht. Unter Email Konten – Konten hinzufügen geht es doch noch gar nicht um Ordner, sondern nur um den Login in den jeweiligen Email Account. Wo Paperless nach Dokumenten suchen soll, wird ja erst im nachfolgenden Schritt unter Regeln definiert, aber soweit komme ich ja gar nicht. Oder verchecke ich es gerade völlig 🙂
Herbert
Ach so, Du meinst den Schritt davor. Du hast einen „normalen“ = privaten Gmail-Account? Evtl. 2FA eingerichtet? In diesem Fall benötigst Du ein App-Passwort. Aber ruf trotzdem mal den Logfile auf und poste die Fehlermeldung.
Peter
Alle anderen Mail-Accounts funktionieren übrigens problemlos in Paperless. Den Gmail Account habe ich nun mehrfach entfernt und neu hinzugefügt, ohne Erfolg.
Herbert
Siehe meine Antwort darüber. Was sagt denn der Logfile?
Peter
Sorry das hat sich gerade überschnitten, hier der Logauszug:
paperless_mail.mail.MailError: Error while authenticating account xxxxx@gmail.com
[2024-08-10 16:00:00,565] [ERROR] [paperless.mail.tasks] Error while processing mail account xxxxx@gmail.com
Kann ja nur an den Logindaten liegen (die getestet überall sonst funktionieren 🙂
Ich legs jetzt mal beiseite und versuche mich später nochmal. Ist für Anfänger schon eine heftige Zeitverbrennungsmaschine 🙂
Herbert
„authenticating account“ wäre für mich ein Hinweis, dass Du 2FA bei Gmail nutzt – ist das so?
Peter
Erstmal ganz lieben Dank für Deine Hilfe!
Ich logge mich ganz normal mit einem Kennwort ein, das ich in KeePass gespeichert habe. Das funktioniert in jedem Browser auch nach Löschen der Cookies.
Im Google Sicherheitscenter kann ich sehen, dass 2FA deaktiviert ist. Sehr misteriös..
Herbert
Habe es gerade noch mal getestet – funktioniert einwandfrei. Allerdings nutze ich 2FA für Gmail, dann erstellt man ein spezielles Passwort für Paperless-ngx – damit funktioniert es.
Dabei habe ich gesehen, dass Gmail im Juni 2024 eine Änderung für Konten vorgenommen hat, die kein 2FA nutzen. Vielleicht schaust Du da mal, ob durch Gmail-Änderungen für Deinen Account etwas nicht funktioniert. Ansonsten würde ich ohnehin immer 2FA nutzen (Bitwarden, Keepass haben ja die entsprechenden Funktionen), gerade bei dem wichtigen Gmail-Konto – aber das muss jeder selbst entscheiden.
Peter
Hallo Herbert, das ist vermutlich der goldene Hinweis. Ohne den wäre ich nie darauf gekommen, warum paperless die Mitarbeit verweigern könnte. Für heute ist meine Motivation erstmal verbrannt, etwas anzufassen was dann wieder ewig nicht funktioniert und Fehlersuche nach sich zieht – die Erfahrung mache ich aber immer wieder, seit ich mich mit Proxmox, Paperlessngx oder Homeassistant beschäftige. Umso schöner, wenn dann wirklich mal etwas funktioniert 🙂
Deinen Hinweis, 2FA möglichst immer zu nutzen, ist natürlich richtig. Allerdings sind bei Verwendung von Keepass dann ja wieder beide Faktoren in einer App vereint, was den Gedanken des zweiten Faktors zur Authentifizierung ein wenig ad absurdum treibt.
Herbert
Tja, verstehe ich. Für die Umstellungen, die der US-Konzern Google da seinen Mail-Nutzern „über Nacht“ zumutet, kann halt das ehrenamtliche Entwickler-Team von Paperless-ngx nichts. Aber ich kann verstehen, dass die Einrichtung am Anfang etwas Mühe kostet – doch ist das geschafft, läuft wirklich alles rund und spart viel Zeit. – Zu 2FA: Das von Dir genannte Probleme sehe ich persönlich nicht und egal ob Nextcloud, Gmail oder-was-auch-immer: Wo 2FA genutzt werden kann, nutze ich es. Aber das wäre eine Diskussion zu einem anderen Thema 🙂
Peter
Alles klar, dann mache ich das ab jetzt so und stelle auf 2FA um. Vielen Dank nochmals für Deinen tollen Input