marco.morath/thunderbird-paperless-connector

Files

Marco Morath d032e3b19c Übergabe von E-Mails als PDF mit eingebetteten Anlagen

2026-09-07 22:33:55 +02:00

11 KiB

Raw Blame History

Paperless-Connector für Thunderbird / Betterbird

Legt Anhänge und ganze E-Mails in einem Paperless-ngx-Archiv ab und fügt Dokumente aus dem Archiv als Anhang oder Freigabelink in Entwürfe ein.

Schwestererweiterung zur LibreOffice-Fassung; dieselben Erkenntnisse zur Paperless-Schnittstelle, aber vollständig eigener Code — Thunderbird kennt WebExtensions, LibreOffice UNO.

Funktionen

Ort	Befehl	Wirkung
Kontextmenü am Anhang	Anhang in Paperless ablegen	ausgewählte Anhänge als Dokument
Kontextmenü in der Nachrichtenliste	E-Mail in Paperless ablegen	als PDF mit eingebettetem Original, wahlweise als `.eml`
Schaltfläche im Nachrichtenfenster	dasselbe für die angezeigte Nachricht
Schaltfläche im Verfassenfenster	Aus Paperless einfügen	als Anhang oder als Freigabelink

Beim Ablegen stehen dieselben zwei Ziele zur Wahl wie in der LibreOffice-Fassung: ein neues Dokument oder eine neue Version eines bestehenden. Der zweite Fall deckt die Lücke, die Dokumentenverwaltungen gern offenlassen:

Die Rechnung kommt als PDF im Anhang. Später entsteht die bearbeitbare Fassung. Beides gehört zusammen — aber das PDF war zuerst da.

Was beim Ablegen passiert

Anhänge einzeln wählbar. Kleine Bilder und Signaturen sind vorab abgewählt — sie gehören zur Darstellung der Nachricht, nicht zum Inhalt. Wer sie alle mit archiviert, hat nach einem Jahr hunderte Logos im Bestand. Die Schwelle liegt bei 8 KB und ist einstellbar.

Die ganze Nachricht als PDF. Betreff als Überschrift, darunter ein grau hinterlegter Kopfblock mit Konto, Absender, Empfängern, Datum und Anlagen, dann der Nachrichtentext. Zitierte Abschnitte stehen grau und eingerückt — bei langen Verläufen sieht man so auf einen Blick, was neu ist.

Eingebettet werden die vollständige Originalnachricht als .eml sowie alle Anhänge im Original. Es geht also nichts verloren, auch wenn die Darstellung nicht originalgetreu ist.

Wer lieber die Rohfassung will, stellt das in den Einstellungen um oder nimmt das Häkchen im Ablegen-Dialog heraus.

Titel aus dem Betreff. Präfixe wie AW: oder Fwd: werden entfernt — sie tragen im Archiv nichts bei und stören beim Sortieren.

Klassifizierung direkt danach. Sonst trägt ein neues Dokument nur den Titel, und nachträglich macht man es erfahrungsgemäß nicht mehr.

Warum kein originalgetreues Abbild

HTML-Nachrichten werden als Text gesetzt. Eine WebExtension hat keine Darstellungsmaschine, die HTML nach PDF überträgt, und Thunderbird bietet Erweiterungen keine Druckfunktion an — die tabs-Schnittstelle kennt in Manifest V3 kein saveAsPDF, anders als in Firefox. Geprüft an der API-Dokumentation für Thunderbird 156.

Für die Umwandlung von HTML nach Text übernimmt messengerUtilities.convertToPlainText() die Arbeit. Das ist dieselbe Funktion, die beim Antworten in Nur-Text greift, und liefert deutlich bessere Ergebnisse als eine selbstgebaute Entschlackung.

Der PDF-Erzeuger

Selbst geschrieben, in lib/pdf.js. Der Grund ist Vorsatz: Eine Erweiterung soll nichts nachladen, und eine mitgelieferte Bibliothek wie pdf-lib wäre rund ein Megabyte für einen Bruchteil ihrer Fähigkeiten. Gebraucht werden hier nur Text und eingebettete Dateien.

Erzeugt wird PDF 1.7 mit den eingebauten Schriften Helvetica und Helvetica-Bold. Die sind in jedem Betrachter vorhanden und müssen nicht eingebettet werden.

Ausdrücklich kein PDF/A. Dafür wären eingebettete Schriftschnitte, ein Farbprofil und XMP-Metadaten nötig — und vor allem eine Prüfung mit veraPDF. Ein Dokument als PDF/A zu bezeichnen, ohne es geprüft zu haben, wäre eine leere Behauptung.

Einstellbar sind Papierformat (A4, A5, Letter, Legal), die vier Ränder in Millimetern und die Grundschriftgröße (Vorgabe 11 Punkt).

Das Konto im Kopfblock

Bei Nachrichten an Blindkopie-Empfänger geht aus An und Kopie nicht hervor, welches Konto sie empfangen hat. Im Archiv ist das später die entscheidende Angabe.

Ermittelt wird sie auf zwei Wegen: über die accounts-Schnittstelle, die allerdings die Berechtigung accountsRead braucht, und ersatzweise über die Zustellkopfzeilen Delivered-To, X-Original-To und Verwandte.

Letztere setzt der zustellende Server, und sie sind nicht immer vorhanden — Postfix und Dovecot setzen sie zuverlässig, Microsoft-Umgebungen oft nicht. Findet sich nichts, fehlt die Zeile im PDF ganz.

Einfügen in Entwürfe

Als Anhang. Das Original wird geladen (?original=true), nicht die Archivfassung — bei ZUGFeRD bleibt damit die eingebettete XML erhalten. Die Version ist wählbar, mit Datum und Format.

Als Freigabelink. Zeitlich begrenzt, ohne Anmeldung abrufbar, auf Wunsch mit einem Tag am Dokument. Eingefügt werden Name (fett), Adresse und Gültigkeit:

Einladung Generalversammlung
https://dms.example.org/share/ZYGwdw…
Link gültig bis 11.09.2026

Die Adresse steht sichtbar, nicht nur als Verweisziel — bei einem Link, der ohne Anmeldung Zugriff gewährt, sollte der Empfänger sehen, wohin er führt.

Der Tag ist abschaltbar. Ein leeres Tag-Feld bedeutet: keine Kennzeichnung setzen. Wer es dauerhaft nicht will, leert das Feld in den Einstellungen.

Einschränkung: Die Compose-Schnittstelle kennt kein Einfügen an der Schreibmarke. Der Nachrichtentext muss vollständig gelesen und zurückgeschrieben werden. Der Link landet deshalb am Ende des Textes, nicht an der Cursorposition. Bei HTML-Nachrichten wird er vor dem schließenden </body> eingesetzt.

Wann was: Der Anhang für alles, was auch in fünf Jahren noch lesbar sein muss, wenn der Link längst abgelaufen ist. Der Link für große Dateien und für Empfänger, die ohnehin Zugriff auf das Archiv haben sollen.

Einrichten

Add-ons-Verwaltung → Paperless-Connector → Einstellungen
Basisadresse eintragen, etwa https://dms.example.org — ohne abschließenden Schrägstrich
API-Token eintragen, erzeugt im Benutzerprofil von Paperless
Speichern — dabei wird das Zugriffsrecht für genau diese Adresse erbeten und die Verbindung sofort geprüft

Das Zugriffsrecht steht bewusst nicht pauschal im Manifest. Eine Erweiterung, die von Haus aus jede Adresse erreichen darf, ist eine unnötig große Angriffsfläche.

Bauen und installieren

./build.sh

Zum Ausprobieren ohne Installation:

Extras → Entwicklerwerkzeuge → Debuggen von Add-ons
→ Temporäres Add-on laden → manifest.json wählen

Das ist beim Entwickeln der bessere Weg: Änderungen sind nach einem Klick auf „Neu laden" wirksam, und die Konsole zeigt Fehler im Klartext.

Dauerhaft:

Add-ons-Verwaltung → Zahnrad → Add-on aus Datei installieren
→ paperless-thunderbird-1.0.0.xpi

Bekannte Einschränkung: Zugriff über IP-Adresse

Der Zugang über https:// und einen Rechnernamen funktioniert. Der direkte Weg über eine LAN-Adresse wie http://192.168.1.5:8000 schlägt dagegen mit NetworkError fehl, auch wenn das Zugriffsrecht erteilt wurde.

Die Ursache ist nicht abschließend geklärt. Eine Vermutung: Neuere Gecko-Versionen schränken Anfragen aus erweiterten Kontexten in private Adressbereiche ein. Falls das zutrifft, lässt es sich von der Erweiterung aus nicht umgehen.

Praktisch ist das verschmerzbar — der Weg über den Reverse Proxy ist ohnehin der bessere, weil er verschlüsselt ist. Wer es untersuchen möchte, findet in about:networking und in der Netzwerkanalyse der Add-on-Debugansicht Ansatzpunkte.

Manifest-Version

Gebaut nach Manifest V3 mit den Thunderbird-Besonderheiten:

background.scripts als Ereignisseite, kein Service Worker — Thunderbird unterstützt keine
compose_action und message_display_action neben action
optional_host_permissions statt fester Adressen

Sollte die eingesetzte Version noch MV2 verlangen, sind vier Änderungen nötig: manifest_version auf 2, optional_host_permissions nach optional_permissions, host_permissions entfällt, und background.type: module bleibt wie es ist.

Sprachen

Deutsch, Englisch und Französisch über die eingebaute Verwaltung (_locales/). Die Sprache richtet sich nach der Oberfläche von Thunderbird. Eine weitere Sprache ergänzt man, indem man ein Verzeichnis mit messages.json anlegt — die Schlüssel stehen in _locales/de/messages.json.

Sicherheit

Ausführlich in SICHERHEIT.md. Die Lage ist entspannter als bei der LibreOffice-Fassung, weil hier keine fremden Dokumente geöffnet werden — der heikelste Punkt entfällt. Die wichtigsten Maßnahmen:

Zugriffsrecht nur für die eingetragene Adresse, zur Laufzeit erbeten
Nur die fünf tatsächlich benötigten Berechtigungen — compose.send war im ersten Entwurf enthalten, ohne je benutzt zu werden, und ist entfernt
Nur http und https als Basisadresse
Dateinamen aus Anhängen werden bereinigt — sie stammen vom Absender
Anhangdaten werden erst beim Hochladen geladen, nicht beim Öffnen des Dialogs
Freigabelinks und Dokumentnamen werden beim Einfügen HTML-maskiert
Aufträge zwischen Dialog und Ereignisseite werden nach 30 Minuten verworfen

Aufbau

manifest.json
background.js              Menüs, Schaltflächen, Vermittlung
lib/
  client.js                REST-Client (fetch, FormData)
  settings.js              Einstellungen, Dateinamen, Hilfsmittel
ui/
  store.html/.js           Ablegen: Anhänge oder ganze Nachricht
  classify.html/.js        Klassifizierung direkt danach
  insert.html/.js          Einfügen als Anhang oder Link
  options.html/.js         Verbindung einrichten
  gemeinsam.js/.css        geteilte Hilfsmittel
_locales/{de,en,fr}/
icons/

Die Dialoge sprechen nicht selbst mit Paperless, sondern lassen die Ereignisseite arbeiten. Dort hängt die zur Laufzeit erteilte Berechtigung; ein Dialogfenster müsste sie sonst erneut erbitten.

Vor einer Veröffentlichung

Datei	Was
`manifest.json`	`browser_specific_settings.gecko.id`, `author`, `homepage_url`
`LICENSE`	Rechteinhaber

Die Kennung sollte einer Domain folgen, die dir gehört. Aktuell steht dort paperless@example.org.

Lizenz

MIT, siehe LICENSE.

Haftung

Die Erweiterung schreibt in ein Dokumentenarchiv. Sie wurde gegen eine Paperless-Instanz entwickelt, aber nicht formal getestet. Die MIT-Lizenz schließt jede Gewährleistung aus.

Vor dem ersten produktiven Einsatz: eine Testnachricht ablegen und in Paperless nachsehen, ob Titel, Datum und Anhänge stimmen.

Es wird weder eine Gewähr noch eine Haftung übernommen. Für entstandene Schäden haftet der jeweilige Anwender. Die Nutzun erfolgt auf eigenes Risiko.

11 KiB Raw Blame History