KeyHelp: Mail-Warteschlange verwalten, hängende Mails finden und erneut zustellen
So finden Sie hängende Mails in der KeyHelp-Warteschlange, lesen den Fehlergrund, stellen Mails erneut zu, halten sie an, schicken sie an den Absender zurück oder löschen sie gezielt, im Panel und mit postsuper.
Werbung Mit * markierte Links sind Werbelinks: Bei einem Kauf erhalten wir eine Provision, der Preis bleibt gleich. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen. Mehr dazu

Mails, die Ihr KeyHelp-Server nicht sofort zustellen kann, landen in der Warteschlange von Postfix. Dort werden sie tagelang erneut versucht, ohne dass Absender oder Admin davon erfahren. Diese Anleitung zeigt, wie Sie hängende Mails im Panel und auf der Kommandozeile finden, die Ursache aus der Fehlermeldung ablesen, einzelne Mails anhalten, erneut zustellen oder löschen und KeyHelp eine Warnschwelle für die Warteschlange setzen lassen. Grundlage ist ein Server wie in KeyHelp installieren und absichern. Getestet mit KeyHelp 26.1.1 auf Debian 12.
Voraussetzungen
- KeyHelp-Server mit Administratorzugang, getestet mit KeyHelp 26.1.1 (Build 3698) auf Debian 12.15 mit Postfix 3.7.11. KeyHelp verlangt laut Hersteller ein 64-Bit-System (amd64 oder arm64) und mindestens 2 GB RAM.
- SSH-Zugang als root für die Befehle
postqueue,postsuperundpostcat. Für die reinen Panel-Funktionen reicht der Admin-Login. - Eine hängende Mail zum Üben: Im Test haben wir Mails an Adressen geschickt, deren Zielserver nicht erreichbar ist. So bleiben die Mails mit einem vorübergehenden Fehler in der Warteschlange.
Schritt 1: Hängende Mails erzeugen und verstehen, wie KeyHelp sie weiterreicht
Für den Test haben wir zwei Mails an eine Adresse mit IP-Literal geschickt, also direkt an einen Server ohne DNS-Umweg. Der Zielserver ist nicht erreichbar, Postfix stellt die Mail deshalb zurück:
for i in 1 2; do printf "Subject: Testmail $i an nicht erreichbares Ziel\nFrom: info@kunde1.example.de\nTo: kunde@[192.0.2.10]\n\nTest $i\n" | sendmail -f info@kunde1.example.de "kunde@[192.0.2.10]"; done
postqueue -p-Queue ID- --Size-- ----Arrival Time---- -Sender/Recipient-------
12B3D42B62 1142 Thu Oct 1 17:32:38 info@kunde1.example.de
(connect to 192.0.2.10[192.0.2.10]:25: Network is unreachable)
kunde@[192.0.2.10]Im Log fällt auf, dass jede ausgehende Mail zwei Queue-IDs bekommt. KeyHelp setzt default_transport = smtp:127.0.0.1:10027. Postfix reicht jede Mail nach außen zuerst an einen zweiten lokalen SMTP-Dienst auf Port 10027 weiter, der die Absenderadresse für SRS umschreibt (siehe E-Mail-Weiterleitungen mit SRS). Erst die zweite ID versucht die echte Zustellung und bleibt in der Warteschlange stehen:
postfix/smtp[5773]: 6F30042B37: to=<kunde@[192.0.2.10]>, relay=127.0.0.1[127.0.0.1]:10027, delay=0.67, delays=0.54/0.07/0.02/0.03, dsn=2.0.0, status=sent (250 2.0.0 Ok: queued as 12B3D42B62)
postfix/smtp[5773]: 12B3D42B62: to=<kunde@[192.0.2.10]>, relay=none, delay=0.04, delays=0.03/0/0.01/0, dsn=4.4.1, status=deferred (connect to 192.0.2.10[192.0.2.10]:25: Network is unreachable)Folgen Sie im Log also der Kette „queued as …“. Die Wiederholungsabstände stehen in der Postfix-Konfiguration. Im gezeigten Beispiel gelten diese Werte: Postfix versucht es frühestens nach fünf Minuten erneut, höchstens im Abstand von 4000 Sekunden, und gibt nach fünf Tagen auf.
maximal_queue_lifetime = 5d
bounce_queue_lifetime = 5d
queue_run_delay = 300s
minimal_backoff_time = 300s
maximal_backoff_time = 4000spostqueue -p listet die Mail mit Fehlergrund in Klammern, im Log steht status=deferred mit dsn=4.4.1, also ein vorübergehender Fehler.
Schritt 2: Die Warteschlange im Panel ansehen
Die Seite erreichen Sie als Admin über „Systemstatus“ und dann „E-Mail-Warteschlange“. Schneller geht es über das Dashboard: Dort steht „E-Mails in Warteschlange“ mit der aktuellen Anzahl und einem Link „Verwalten“. Die Tabelle zeigt ID, Status, Absender, Empfänger, Ankunftsdatum, Alter und Größe. Im Test lagen fünf Mails darin, vier mit Status „Zurückgestellt“ und eine mit „Halten“.

Die kleinen Symbole sind die eigentliche Diagnose. Fahren Sie mit der Maus über das Info-Symbol neben dem Status, zeigt KeyHelp den Grund des letzten Fehlversuchs, im Test „connect to 198.51.100.20[198.51.100.20]:25: Network is unreachable“. Das Symbol in der Spalte ID blendet die Kopfzeilen der Mail ein. Dazu ruft das Panel im Hintergrund postcat -qh mit der Queue-ID auf, das zeigt das Systemjournal mit einem sudo-Eintrag des Benutzers keyhelp.

Laut Hinweistext auf der Seite kann die Zeile X-ORIGINATING-SCRIPT zeigen, welche Datei die Mail verschickt hat. Bei Mails, die per sendmail auf der Konsole verschickt werden, fehlt sie.
Die Zahl unter „Nachrichten in Warteschlange“ entspricht der letzten Zeile von postqueue -p, im Test „-- 5 Kbytes in 5 Requests.“
Schritt 3: Ursache auf der Konsole eingrenzen
Auf der Konsole bekommen Sie die Warteschlange maschinenlesbar und nach Zielen gruppiert. postqueue -j gibt je Mail eine JSON-Zeile mit Grund aus, qshape zählt Mails pro Zieldomain und Alter. Fällt ein einziger Empfängerserver aus, sehen Sie das sofort. Die beiden Ausgaben stammen aus zwei Testläufen:
postqueue -j | head -1
qshape deferred{"queue_name": "deferred", "queue_id": "12B3D42B62", "arrival_time": 1790875958, "message_size": 1142, "forced_expire": false, "sender": "info@kunde1.example.de", "recipients": [{"address": "kunde@[192.0.2.10]", "delay_reason": "connect to 192.0.2.10[192.0.2.10]:25: Network is unreachable"}]}
T 5 10 20 40 80 160 320 640 1280 1280+
TOTAL 3 3 0 0 0 0 0 0 0 0 0
[192.0.2.77] 3 3 0 0 0 0 0 0 0 0 0Die Vorgeschichte einer Mail steht im Log. Im gezeigten Beispiel gibt es kein /var/log/mail.log. Postfix schreibt ins Systemjournal:
ls: cannot access '/var/log/mail*': No such file or directorySuchen Sie deshalb mit journalctl nach der Queue-ID, im Panel alternativ unter „Systemstatus“, „E-Mail-Protokoll“. Diese Seite zeigt die letzten 1000 Zeilen und hat ein Suchfeld. Mit dem Suchbegriff deferred bleiben nur die Fehlversuche übrig.
$ journalctl -u postfix@- --since "-1h" --no-pager | grep 12B3D42B62
Eine Eigenheit der Protokollseite: Adressen in spitzen Klammern zeigt sie nicht an. In der Spalte „Nachricht“ steht „to=,“, obwohl im HTML-Quelltext die Adresse steht. Für die Empfängeradresse nutzen Sie die Warteschlange oder journalctl.
Der Grund in postqueue -j (Feld delay_reason) stimmt mit dem Tooltip im Panel und der letzten status=deferred-Zeile im Journal überein.
Schritt 4: Mails anhalten, erneut zustellen oder an den Absender zurückgeben
Im Panel gibt es für die Zustellung nur „Warteschlange abarbeiten“. Nach Bestätigung meldet KeyHelp „Abarbeitung der Warteschlange eingeleitet.“ und Postfix versucht alle zurückgestellten Mails sofort erneut. Der Dialog warnt selbst davor, das zu oft hintereinander zu tun. Ist die Ursache nicht behoben, landen die Mails sofort wieder in der Warteschlange. Mails im Status „Halten“ fasst die Schaltfläche nicht an, im Test stand die angehaltene Mail danach unverändert da.
Anhalten, Freigeben und einzelne Mails erneut zustellen geht nur auf der Konsole. Anhalten lohnt sich, wenn Sie eine verdächtige Mail erst prüfen wollen:
postsuper -h 1503442B63
postsuper -H 1503442B63
postqueue -i 12B3D42B62
postqueue -fpostsuper: 1503442B63: placed on hold
postsuper: Placed on hold: 1 message
postsuper: 1503442B63: released from hold
postsuper: Released from hold: 1 message-h hält an (in postqueue -p steht dann ein ! hinter der ID), -H gibt frei, postqueue -i versucht eine einzelne Mail sofort, postqueue -f alle. postsuper -r schickt eine Mail noch einmal durch die komplette Verarbeitung. Sie bekommt dabei eine neue ID, im Log steht die alte als orig_id:
postfix/pickup[5334]: 9208A42B37: uid=107 from=<info@kunde1.example.de> orig_id=1503442B63Steht fest, dass eine Mail nie ankommen wird, ist Löschen nicht immer die beste Wahl, denn der Absender erfährt davon nichts. postsuper -e lässt die Mail sofort ablaufen. Postfix schickt beim nächsten Versuch einen Unzustellbarkeitsbericht an den Absender, im Test landete er im Postfach info@kunde1.example.de:
postsuper: 12B3D42B62: expired
postsuper: Force-expired: 1 message
postfix/qmgr[1144]: 12B3D42B62: from=<info@kunde1.example.de>, status=force-expired, returned to sender
postfix/bounce[6524]: 12B3D42B62: sender non-delivery notification: E71FE42B37Nach postsuper -e und postqueue -i ist die ID aus postqueue -p verschwunden, und der Absender hat eine Mail „Undelivered Mail Returned to Sender“ im Posteingang.
Schritt 5: Einzelne Mails oder die ganze Warteschlange löschen
Im Panel markieren Sie die Mails per Checkbox, wählen unter „- Mehrfachaktionen -“ den Eintrag „Auswahl löschen“ und klicken „Übernehmen“. Nach der Rückfrage meldet KeyHelp „Die gewählten Elemente wurden gelöscht.“ Die rote Schaltfläche „Gesamte Warteschlange löschen“ entfernt alles. Das Journal zeigt, was im Hintergrund passiert:
sudo[6807]: keyhelp : PWD=/home/keyhelp/www/keyhelp ; USER=root ; COMMAND=/usr/sbin/postsuper -d ALL
postfix/postsuper[6808]: Deleted: 2 messagesWichtig: Laut Postfix-Dokumentation löscht postsuper -d ohne Angabe einer Warteschlange auch aus „hold“, also angehaltene Mails. Wer nach einem Spamvorfall gezielt aufräumen will, löscht auf der Konsole nur die Mails an ein bestimmtes Ziel. postqueue -j liefert dafür die IDs, postsuper -d - liest sie von der Standardeingabe:
postqueue -j | python3 -c 'import sys,json; [print(m["queue_id"]) for m in map(json.loads,sys.stdin) if any("198.51.100.20" in r["address"] for r in m["recipients"])]' | postsuper -d -postsuper: 99E7142B73: removed
postsuper: A671342B72: removed
postsuper: Deleted: 2 messagesMit postsuper -d ALL deferred beschränken Sie das Löschen auf die Warteschlange „deferred“, also die zurückgestellten Mails. Im Test entfernte der Befehl drei zurückgestellte Mails („Deleted: 3 messages“).
postqueue -p meldet „Mail queue is empty“, im Panel steht „Nachrichten in Warteschlange: 0“.
Schritt 6: Warnschwelle für die Warteschlange festlegen
Unter „Konfiguration“, „E-Mail-Server“ gibt es das Feld „Warnschwelle für E-Mail-Warteschlange“. Laut Beschreibung ist das die Anzahl Mails, ab der KeyHelp Warnungen in der Oberfläche anzeigt und Benachrichtigungen sendet. Ab Werk steht der Wert auf 200. Wir haben ihn zum Testen auf 3 gesetzt, KeyHelp bestätigte mit „Die Einstellungen wurden aktualisiert. Die Änderungen werden in wenigen Augenblicken wirksam.“ und speicherte den Wert in der Tabelle settings:
286 email mail_queue_warning_threshold 3Mit fünf Mails in der Warteschlange geht im gezeigten Beispiel in den folgenden rund sechs Minuten keine Benachrichtigungsmail ein. Verlassen Sie sich deshalb nicht allein darauf und prüfen Sie die Zahl im Dashboard regelmäßig oder per Monitoring.
Nach dem Speichern steht der neue Wert im Feld, und mysql keyhelp -e "select * from settings where name like '%queue%'" zeigt ihn.
Typische Fehler
- „Network is unreachable“ beim Verbindungsaufbau zu Port 25
Der Server kommt nicht zum Empfängerserver durch. Prüfen Sie Netzwerk, Firewall und ob Ihr Hoster ausgehende Verbindungen auf Port 25 zulässt. „Warteschlange abarbeiten“ hilft hier nicht, im Test standen die Mails danach mit demselben Grund wieder in der Liste.
- „Host or domain name not found. Name service error for name=kunde2.example.de type=A: Host not found“
Die Empfängerdomain existiert im DNS nicht. Diese Mail bleibt nicht in der Warteschlange, Postfix schickt sofort einen Bounce mit Status 5.4.4 an den Absender.
- „connect to server.example.de[private/dovecot-lmtp]: Connection refused“
Lokale Mails hängen, weil Dovecot nicht läuft. Im Test haben wir Dovecot gestoppt, die Mail an das eigene Postfach blieb zurückgestellt. Nach dem Start von Dovecot und
postqueue -fwurde sie zugestellt.- Falsche Queue-ID beim Löschen
postsuper -dmit einer nicht vorhandenen ID meldet keinen Fehler, nur „Deleted: 0 messages“. Prüfen Sie die IDs vorher mitpostqueue -p.- Angehaltene Mails versehentlich gelöscht
„Gesamte Warteschlange löschen“ ruft
postsuper -d ALLauf. Das betrifft laut Postfix-Dokumentation auch Mails im Status „Halten“.
Häufige Fragen
Wie lange bleibt eine Mail in der Warteschlange?
Im gezeigten Beispiel bleibt eine Mail fünf Tage in der Warteschlange (maximal_queue_lifetime = 5d). Mit postsuper -e lassen Sie eine Mail sofort ablaufen.
Warum finde ich kein /var/log/mail.log?
Im gezeigten Beispiel schreibt Postfix nur ins Systemjournal. Nutzen Sie journalctl -u postfix@- oder im Panel „Systemstatus“, „E-Mail-Protokoll“. Die KeyHelp-Dokumentation nennt noch /var/log/mail.log. Diese Datei ist im gezeigten Beispiel nicht vorhanden.
Ist eine kleine Zahl Mails in der Warteschlange ein Problem?
Nicht unbedingt. Laut KeyHelp-Dokumentation ist es nicht ungewöhnlich, dass sich immer ein paar Mails in der Warteschlange befinden. Steigt die Zahl ohne erklärbaren Grund wie ein Massenmailing stark an, deutet das laut Dokumentation auf Spamversand hin.
Hilft „Warteschlange abarbeiten“ bei Spam?
Nein, es beschleunigt nur die Zustellung. Bei Spam halten Sie die Mails an oder löschen sie gezielt und suchen die Quelle, etwa über die Kopfzeilen. Die Spamprüfung eingehender Mails behandelt Rspamd in KeyHelp einrichten.
Fazit
Das Panel reicht für den Alltag: Es zeigt Fehlergrund und Kopfzeilen, stößt neue Versuche an und löscht. Für gezielte Eingriffe wie Anhalten, Löschen nach Ziel oder eine saubere Rückmeldung an den Absender brauchen Sie postsuper auf der Konsole. Lesen Sie vor jeder Aktion den Fehlergrund, er hilft bei der Entscheidung, ob Warten, Reparieren oder Löschen der richtige Weg ist.


