Push-Nachrichten auf dem Smartphone

Paperless-ngx: Telegram-Benachrichtigung bei E-Mail-Eingang

Paperless-ngx kann ja auch E-Mail-Anhänge extrahieren und in den Dokumenten-Pool einpflegen. Dies passiert dann automatisch im Hintergrund. Mittels einem kleinen Skript kann man sich hierüber auch per Telegram-Push-Nachricht auf dem Handy informieren lassen.

Screenshot: Telegram-Nachricht von Paperless-ngx bezüglich eines neuen Dokumentes

Wenn ein neues Dokument per E-Mail eingepflegt wurde, erhalte ich automatisch eine Nachricht per Telegram.

Das Dokumenten-Managemenent-System ›Paperless-ngx‹ kann auch diverse E-Mail-Konten auf Anhänge (z. B. Rechnungen) prüfen und diese PDF-Dateien (oder Bilder) automatisch in den Bestand einpflegen. Dies ist eine der vielen Features dieser tollen Open-Source-Software. Ich hatte hierüber bereits einen kleinen Beitrag geschrieben: Wie ich Paperless-ngx nutze. Eine konkrete Anleitung für das automatische Importieren von Mail-Anhängen findet man z. B. auf Digital Cleaning. Aber ich wollte mehr:

Wer auf dem Smartphone oder Tablet den Messenger ›Telegram‹ nutzt, weiß vielleicht, dass man sich dort auch kleine „Bots“ anlegen kann: Ein Raspberry Pi beispielsweise kann einem dadurch gewisse Statusmeldungen zusenden.

Ich dachte mir, es wäre doch elegant, wenn mir mein Raspberry (auf dem Paperless-ngx läuft) bzw. ein Linux-Rechner auch eine Meldung auf das Smartphone schickt, wenn ein neues Dokument vorliegt, welches eben automatisch ^x per E-Mail importiert wurde, während ich vielleicht gerade in der Badewanne liege.

^x Ich bekomme regelmäßig Rechnungen zugeschickt, die per Bankeinzug beglichen werden. Ich benötige sie nicht als ungelesene Dokumente im Posteingang.

Und genau das geht tatsächlich relativ einfach. Denn Paperless-ngx unterstützt das Ausführen von Skripten, nachdem neue Dokumente eingepflegt worden sind („Post-Consume-Skript„).

Zuvor müssen wir seitens Paperless noch zwei Dinge erledigen:

API-Authentifizierungstoken anlegen

Damit externe Anwendungen – bzw. unser Skript – Zugriff auf die Mechanismen hinter Paperless-ngx erhalten können, muss via ›API-Authentifizierungstoken‹ Eintritt gewährt werden können. Das geht einfach: Oben rechts in der Benutzeroberfläche auf den eigenen Nutzernamen klicken und dann auf „Mein Profil“. Dort generiert man diesen Token und speichert diesen gleich im eigenen Passwortmanager (oder wie auch immer man sich solche Daten notiert).

Dieser Token wird nur für externe Anwendungen bzw. Skripte relevant sein – nicht für das eigene Einloggen über die Nutzeroberfläche.

Jetzt brauchen wir noch einen speziellen Tag:

E-Mail-Tag anlegen

Damit das Skript nicht ausgeführt wird, wenn man manuell bzw. regulär ein neues Dokument einpflegt, legen wir unter Paperless-ngx noch einen neuen „Tag“ an – z. B. E-Mail-Import.

Danach definieren wir im E-Mail-Filter von Paperless-ngx („E-Mail-Regeln“), dass alle Dokumente, die per Mail importiert werden, eben diesen Tag automatisch erhalten. Somit kann das Telegram-Skript später selektieren, für welche Art von Dokumenten es anschlagen soll (eben nicht für jedes).

Tag-ID notieren

Jeder Tag unter Paperless-ngx besitzt eine ID (eine Ziffer). Die ID des eben angelegten Tags benötigen wir gleich. Sie lässt sich leicht ermitteln, indem man innerhalb der Tag-Verwaltung eben diesen Tag anklickt. Im nun aufploppenden Fenster steht diese ID ganz oben – z. B. #5 Diese Ziffer merken wir uns.

Telegram-Bot einrichten

Damit Nachrichten an den eigenen Telegram-Account gesendet werden können, muss seitens dieses Messengers ein s. g. (persönlicher) Bot angelegt werden. Außerdem muss dort der s. g. Bot-Token ermittelt werden (eine Art Passwort) und die Chat-ID des zukünftigen „Gesprächs“ mit dem eigenen Bot. Beide Daten benötigen wir gleich für das Skript.

Bildschirmfoto: Nachricht vom Raspberry Pi in der Messenger-App Telegram

Wie man einen persönlichen Bot anlegt und Bot-Token bzw. Chat-ID ermittelt, hatte ich in einem separaten Beitrag erklärt → Den Raspberry Pi Nachrichten an Telegram senden lassen

Bitte lesen Sie zunächst diesen Beitragsabschnitt. Ich möchte die Vorgehensweise hier nicht wiederholen.

Skript erstellen

Wir erstellen nun das Skript. Ich habe es unter dem Dateinamen telegram-notify.sh direkt im Docker-Verzeichnis erstellt, in dem auch die yml- bzw. die env-Datei für paperless-ngx liegt.

#!/bin/bash

# --- Konfiguration ---
BOT_TOKEN="[der-eigene-TELEGRAM-BOT-TOKEN]"
CHAT_ID="[die-eigene-TELEGRAM-CHAT-ID]"
PAPERLESS_API_URL="http://localhost:8000" # Container-intern / nicht ändern
PAPERLESS_EXTERNAL_URL="http://192.168.178.2:8010" # IP oder Domain unter der Paperless im Heimnetzwerk läuft
API_TOKEN="[der-eigene-API-TOKEN]" # Paperless-ngx API-Token
TAG_ID=5 # ID des Tags "E-Mail-Import" unter Paperless-ngx

DOCUMENT_ID="$DOCUMENT_ID"

if [ -z "$DOCUMENT_ID" ] || [ "$DOCUMENT_ID" = "null" ]; then
    echo "Fehler: Keine DOCUMENT_ID erhalten."
    exit 1
fi

# --- 1. Dokument abfragen ---
DOC_JSON=$(curl -s -H "Authorization: Token $API_TOKEN" \
    "${PAPERLESS_API_URL}/api/documents/${DOCUMENT_ID}/")

# --- 2. Prüfen, ob der Tag vorhanden ist ---
if ! echo "$DOC_JSON" | grep -q "\"tags\":.*\<$TAG_ID\>"; then
    echo "Kein Mail-Tag vorhanden. Keine Benachrichtigung."
    exit 0
fi

echo "Mail-Tag erkannt. Sammle Informationen..."

# --- 3. Basisinformationen aus dem Dokument ---
ORIGINAL_FILENAME=$(echo "$DOC_JSON" | grep -o '"original_file_name":"[^"]*"' | cut -d'"' -f4)
TITLE=$(echo "$DOC_JSON" | grep -o '"title":"[^"]*"' | cut -d'"' -f4)
CREATED_DATE=$(echo "$DOC_JSON" | grep -o '"created":"[^"]*"' | cut -d'"' -f4)   # z. B. 2026-05-15

# --- 4. Korrespondent (Name) abfragen, falls vorhanden ---
CORRESPONDENT_NAME="–"
CORRESPONDENT_ID=$(echo "$DOC_JSON" | grep -o '"correspondent":[0-9]*' | cut -d':' -f2)
if [ -n "$CORRESPONDENT_ID" ] && [ "$CORRESPONDENT_ID" != "null" ]; then
    CORR_JSON=$(curl -s -H "Authorization: Token $API_TOKEN" \
        "${PAPERLESS_API_URL}/api/correspondents/${CORRESPONDENT_ID}/")
    CORRESPONDENT_NAME=$(echo "$CORR_JSON" | grep -o '"name":"[^"]*"' | cut -d'"' -f4)
    [ -z "$CORRESPONDENT_NAME" ] && CORRESPONDENT_NAME="–"
fi

# --- 5. Dokumententyp (Name) abfragen, falls vorhanden ---
DOCTYPE_NAME="–"
DOCTYPE_ID=$(echo "$DOC_JSON" | grep -o '"document_type":[0-9]*' | cut -d':' -f2)
if [ -n "$DOCTYPE_ID" ] && [ "$DOCTYPE_ID" != "null" ]; then
    DOCTYPE_JSON=$(curl -s -H "Authorization: Token $API_TOKEN" \
        "${PAPERLESS_API_URL}/api/document_types/${DOCTYPE_ID}/")
    DOCTYPE_NAME=$(echo "$DOCTYPE_JSON" | grep -o '"name":"[^"]*"' | cut -d'"' -f4)
    [ -z "$DOCTYPE_NAME" ] && DOCTYPE_NAME="–"
fi

# --- 6. Telegram-Nachricht zusammenbauen (ohne Dokumenten-ID) ---
MESSAGE="📄 <b>Neues Dokument per Mail in Paperless-ngx</b>%0A%0A"
MESSAGE+="📎 <b>Dateiname:</b> ${ORIGINAL_FILENAME:-unbekannt}%0A"
MESSAGE+="📑 <b>Titel:</b> ${TITLE:-unbekannt}%0A"
MESSAGE+="🏢 <b>Korrespondent:</b> ${CORRESPONDENT_NAME}%0A"
MESSAGE+="📂 <b>Dokumententyp:</b> ${DOCTYPE_NAME}%0A"
MESSAGE+="📅 <b>Datum:</b> ${CREATED_DATE:-unbekannt}%0A%0A"
MESSAGE+="🔗 <a href='${PAPERLESS_EXTERNAL_URL}/documents/${DOCUMENT_ID}'>Direkt zum Dokument</a>"

# --- 7. Senden ---
curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
    -d "chat_id=${CHAT_ID}" \
    -d "text=${MESSAGE}" \
    -d "parse_mode=HTML" \
    -d "disable_web_page_preview=true" > /dev/null

echo "Benachrichtigung mit Korrespondent, Typ und Datum gesendet."

Natürlich müssen die meisten oberen Konfigurationswerte geändert werden:

BOT_TOKEN
CHAT_ID
PAPERLESS_EXTERNAL_URL
API_TOKEN
TAG_ID

Hinweis: Die eckigen Klammern müssen dort entfernt werden. Was was ist, steht als Hilfe im Skript. Danach sollte das Skript noch ausführbar gemacht werden, z. B. so (Pad beachten):

chmod +x /home/pi/docker/paperless/telegram-notify.sh

Es läuft ggf. aber auch ohne diesen Schritt.

Docker yml-Datei editieren

Noch weiß Paperless-ngx gar nichts von unserem Telegram-Skript. Das ändern wir. Als erstes fügen wir eine Zeile in der yml-Datei für Docker hinzu:

volumes:
# ... bereits vorhandenen Volumes ...
  - ./telegram-notify.sh:/scripts/telegram-notify.sh

Dieser Pfad setzt voraus, dass die telegram-notify.sh direkt im Docker-Verzeichnis liegt. Hierdurch gelangt das Skript in den Container.

Docker env-Datei editieren

Bei meiner Paperless-Variante via Docker nutze ich noch eine env-Datei für weitere Angaben. Sicherlich ginge es auch ohne (fragen Sie mich nicht wie). In der env-Datei muss ebenfalls noch etwas hinzugefügt werden – und zwar am besten ganz am Ende:

PAPERLESS_POST_CONSUME_SCRIPT=/scripts/telegram-notify.sh

Dieser Pfad muss nicht angepasst werden. Er bezieht sich auf das Innere des Docker-Containers.

Docker-Container neu starten

Nun muss der Container neu gestartet werden. Man begibt sich also via Konsole als erstes in den entsprechenden Ordner – z. B. so: cd /home/pi/docker/paperless

Dort angekommen startet man den Container neu: docker compose down && docker compose up -d

Jetzt kann es losgehen

Wenn ein neues Dokument vorliegt mit dem Tag E-Mail-Import (bzw. mit der definierten Tag-ID), dann sollte das Skript feuern und automatisch eine Nachricht an den eigenen Telegram-Account senden:

Ich hatte den Screenshot oben ja bereits gezeigt. Man kann dann auch auf den in der Nachricht enthaltenen Link klicken (daher in der Konfiguration die „PAPERLESS_EXTERNAL_URL“) und gelangt somit sofort zum Bearbeitungsmodus für dieses Dokument.

Ich entferne dort dann den Tag „E-Mail-Import“, denn den benötige ich nicht mehr. Man kann ihn natürlich auch für das Dokument beibehalten, wenn man später wissen muss, woher es kam.

Kurzum: Eine klasse Sache ist das. In meinem E-Mail-Postfach verschwinden (durch Mail-Filter definierte) entsprechende Mails automatisch im Paperless-Unterordner, werden durch Paperless in meinen Dokumentenbestand eingepflegt und dann im E-Mail-Postfach als gelesen markiert. Und damit ich davon in Kenntnis gesetzt werde, macht es „Pling“ auf meinem Smartphone bzw. ich erhalte eine entsprechende Push-Nachricht. Leider wird so etwas nicht mit WhatsApp funktionieren und bei anderen Messengern ggf. viel komplizierter.

Man kann durch so ein „Post-Consume-Skript“ natürlich auch jegliche anderen Befehle an den Rechner senden. Ich könnte z. B. dafür sorgen, dass meine Lichterkette (die am Raspberry angeschlossen ist) kurz aufblinkt, wenn ein neues Dokument vorliegt, oder dass eine Ansage über die Lautsprecher ertönt. Aber das wäre in meinem Fall Spielerei.