E-Mail-Kanal

Verbinden Sie ein Postfach als HelpStack-Kanal: eingehende E-Mails werden per IMAP abgerufen, und Antworten werden per SMTP gesendet.

Kurzüberblick#

Eingehend: IMAP-Polling#

Ein Hintergrund-Poller verbindet sich mit dem IMAP-Server jedes aktiven EMAIL-Kanals (TLS) und führt in jedem Zyklus folgende Schritte aus:

1. Ruft E-Mails ab, die noch nicht verarbeitet wurden, gelesen oder ungelesen, aus den letzten 24 Stunden (dem Rückblickzeitraum des Kanals, siehe unten).
2. Lädt Text, HTML und Anhänge bis zu den Größengrenzen herunter (nicht die ganze Rohnachricht; siehe Anhänge unten) und zerlegt sie.
3. Dedupliziert nach message-id + Vorschau (damit dieselbe E-Mail nicht zweimal übernommen wird).
4. Erstellt eine Konversation, die über die E-Mail-Adresse des Absenders zugeordnet wird (oder, bei einer Kontaktformular-E-Mail von Ihrer eigenen Adresse, über den darin genannten Kunden; siehe unten).
5. Lädt Anhänge in den Speicher hoch.
6. Markiert die E-Mail als verarbeitet.

Wie „verarbeitet" nachverfolgt wird

Der Poller markiert jede übernommene E-Mail mit einem benutzerdefinierten IMAP-Schlüsselwort $HelpStackProcessed und sucht nach E-Mails ohne dieses Schlüsselwort. Die \Seen-Markierung (gelesen) wird bei der Übernahme nie verändert, daher:

• bleibt eine E-Mail in Outlook, Gmail oder Apple Mail ungelesen, bis jemand sie dort liest (oder in HelpStack, bei aktivierter Lesestatus-Synchronisierung), und
• wird eine E-Mail, die jemand vor der nächsten Prüfung von HelpStack in seinem Mailprogramm öffnet, trotzdem übernommen.

Gmail, Google Workspace, Microsoft 365 und die meisten aktuellen IMAP-Server unterstützen benutzerdefinierte Schlüsselwörter. Wenn ein Server das nicht tut, greift der Poller auf die \Seen-Markierung zurück: Er übernimmt nur ungelesene E-Mails und markiert sie nach der Übernahme als gelesen.

Auf einem Server ohne Schlüsselwort-Unterstützung verwenden Sie ein eigenes Postfach für den Kanal. HelpStack verlässt sich dann auf \Seen, um doppelte Übernahmen zu vermeiden, sodass ein Mensch, der das Postfach liest, verpasste E-Mails verursachen kann, und die Lesestatus-Synchronisierung ist nicht verfügbar.

Rückblickzeitraum

Jede Prüfung durchsucht standardmäßig die letzten 24 Stunden. Ein Admin kann das pro Kanal (1 bis 168 Stunden) unter Postfach-Synchronisierung in den Verbindungseinstellungen des Kanals ändern. Der Zeitraum reicht nie vor den Zeitpunkt zurück, an dem das Postfach verbunden wurde, sodass das Verbinden eines Postfachs dessen Verlauf nicht importiert. Import Recent Mail verschiebt diesen Startpunkt nach hinten und hebt den Rückblickzeitraum für eine Stunde auf, damit der Import abgeschlossen werden kann. Konnte HelpStack das Postfach länger als den Rückblickzeitraum nicht prüfen (ein Ausfall), reicht die nächste Prüfung bis einen Tag vor die letzte erfolgreiche Prüfung zurück, höchstens 7 Tage, sodass E-Mails aus dieser Lücke nicht übersprungen werden.

Bereits übernommene E-Mails werden nie zweimal übernommen: Die message-id-Prüfung überspringt sie, auch wenn ein Postfach vom \Seen-Rückfall auf die Schlüsselwort-Nachverfolgung umstellt. Wenn ein bestehender Kanal umstellt, werden E-Mails, die vor der Umstellung im Postfach bereits gelesen waren, nicht importiert (Ihr Team hat sie dort vermutlich schon bearbeitet); ungelesene E-Mails werden wie gewohnt importiert.

Lesestatus-Synchronisierung

Standardmäßig aus. Wenn ein Admin Gelesen-Status synchronisieren aktiviert (Postfach-Synchronisierung, pro Kanal):

• HelpStack zum Postfach: Wenn Sie eine Konversation in HelpStack lesen, werden ihre E-Mails im Postfach als gelesen markiert; Als ungelesen markieren markiert sie wieder als ungelesen. Das läuft einige Sekunden später im Hintergrund.
• Postfach zu HelpStack: HelpStack folgt Änderungen im Postfach. Liest jemand dort eine E-Mail und sind danach alle E-Mails der Konversation aus dem letzten Rückblickzeitraum gelesen, wird die Konversation in HelpStack als gelesen markiert. Markiert jemand eine dieser E-Mails im Postfach als ungelesen, wird die Konversation als ungelesen markiert. Ohne Änderung im Postfach ändert sich nichts, sodass eine Konversation, die Sie in HelpStack als ungelesen markiert haben, ungelesen bleibt, und eine neu eingetroffene ungelesene E-Mail ändert für sich allein nichts.

Nachverfolgt werden nur E-Mails, die HelpStack bei aktiver Schlüsselwort-Nachverfolgung übernommen hat. Auf Servern ohne Schlüsselwort-Unterstützung ist die Lesestatus-Synchronisierung nicht verfügbar.

Dem Postfach folgen (Antworten aus Ihrem Mailprogramm)

Für Teams, die neben HelpStack auch in Outlook, Gmail oder einem anderen Mailprogramm arbeiten. Standardmäßig aus; ein Admin schaltet Dem Postfach folgen ein (Postfach-Synchronisierung, pro Kanal). HelpStack prüft dann alle paar Minuten:

• Antworten aus Ihrem Mailprogramm. HelpStack sucht neue Mails im Ordner Gesendet des Postfachs (gefunden an seiner Standardkennzeichnung, egal wie er heißt, zum Beispiel "Gesendete Elemente" oder "[Gmail]/Gesendet"). Eine Antwort auf eine E-Mail einer Unterhaltung erscheint in dieser Unterhaltung, markiert mit Per E-Mail gesendet, ohne die zitierten früheren Nachrichten. Anhänge einer solchen Antwort werden nicht heruntergeladen. Ist die Antwort neuer als die letzte Nachricht des Kunden, wird die Unterhaltung als gelesen markiert und ein wartender KI-Entwurf zurückgestellt, markiert mit Entwurf nicht gesendet, damit niemand ein zweites Mal antwortet. Ein zurückgestellter Entwurf zählt in der KI-Leistung nicht als abgelehnt.
• Aus dem Posteingang verschobene E-Mails. Sind alle E-Mails einer Unterhaltung aus dem Posteingang verschoben (in einen Ordner abgelegt, archiviert oder gelöscht), wird die Unterhaltung als gelesen markiert. Eine so abgelegte E-Mail gilt auch als erledigt: Ein wartender KI-Entwurf wird zurückgestellt (er zeigt Entwurf nicht gesendet), und die Unterhaltung verlässt den Posteingang der Postfachansicht, bis der Kunde wieder schreibt.

Das Postfach wird dabei nur gelesen: HelpStack markiert, verschiebt oder löscht wegen dieser Einstellung dort nie etwas. (Das Zurückschreiben des Lesestatus ist die separate Einstellung Gelesen-Status synchronisieren oben.) Verfolgt werden Unterhaltungen, die in den letzten 30 Tagen aktiv waren.

Beim Einschalten startet ein einmaliger Abgleich über diese 30 Tage, damit bereits beantwortete oder abgelegte Unterhaltungen nicht mehr als ungelesen erscheinen. Mit Jetzt abgleichen lässt er sich erneut starten; die Zeile neben der Schaltfläche zeigt das Ergebnis des letzten Laufs. Das Abrufen neuer Mails wird dadurch nie verzögert, und wie jede andere Postfachprüfung pausiert er, solange Gmail das Postfach einschränkt.

Eine E-Mail in einen Ordner verschieben

Bei E-Mail-Kanälen, die ihr Postfach über IMAP lesen (auch Gmail), kann ein Agent die E-Mail des Kunden aus HelpStack heraus aus dem Posteingang in einen Ordner des Postfachs verschieben: In Ordner verschieben im ⋮-Menü eines Gesprächs oder in der Auswahlleiste der Postfach-Ansicht für mehrere Gespräche eines Kanals auf einmal (bis zu 100). Die Auswahl zeigt die eigenen Ordner des Postfachs (nie den Posteingang selbst), den zuletzt auf diesem Kanal verwendeten Ordner zuoberst und vorausgewählt, und bei langen Listen ein Suchfeld. Es geschieht nur auf Klick; automatisch wird nichts verschoben.

Die E-Mail wird verschoben, nie gelöscht, und Sie sehen sie auch in Outlook oder Gmail im neuen Ordner. Danach gilt das Gespräch als abgelegt: Es wird als gelesen markiert, ein wartender KI-Entwurf wird zurückgestellt (Entwurf nicht gesendet), es verlässt den Posteingang der Postfach-Ansicht und zeigt Im E-Mail-Programm erledigt, bis der Kunde wieder schreibt. Ein Gespräch, dessen E-Mail nicht mehr im Posteingang liegt (früher verschoben oder ältere Mail), wird als übersprungen gemeldet. Wenn der Mailserver das Postfach einschränkt oder nicht erreichbar ist, sagt HelpStack das und ändert nichts.

Im E-Mail-Programm erledigt erscheint bei jedem offenen Gespräch, das nach der letzten Nachricht des Kunden aus Ihrem Mailprogramm beantwortet oder aus dem Posteingang abgelegt wurde: in der Gesprächsliste, in der Postfach-Ansicht und im Kopf des Gesprächs. Mit der Maus darüber sehen Sie, was und wann. Das Gespräch bleibt offen; die Kennzeichnung verschwindet von selbst, wenn der Kunde wieder schreibt.

Anhänge: Größengrenzen, Speicherung und Abruf aus dem Postfach

HelpStack lädt von jeder E-Mail nur herunter, was es braucht: den Text, das HTML und Anhänge bis 10 MB pro Anhang und 25 MB pro E-Mail. Ein größerer Anhang erscheint trotzdem in der Konversation, mit Name, Größe und der Schaltfläche Aus dem Postfach abrufen; ein Klick lädt genau diese Datei aus Ihrem Postfach und zeigt sie dann wie gewohnt an.

Anhangsdateien bleiben 60 Tage im HelpStack-Speicher. Danach wird die Datei aus dem HelpStack-Speicher entfernt, der Anhang bleibt aufgeführt, und Aus dem Postfach abrufen holt sie wieder aus Ihrem Postfach (eine abgerufene Kopie bleibt weitere 7 Tage erhalten). Wurde die E-Mail inzwischen aus dem Postfach gelöscht, zeigt der Anhang Im Postfach nicht mehr verfügbar. Eine in Gmail archivierte E-Mail wird weiterhin gefunden. Kann HelpStack das Postfach gerade nicht erreichen (zum Beispiel nach einer Passwortänderung), sehen Sie einen entsprechenden Hinweis und können es später erneut versuchen; der Anhang wird dann nicht als nicht verfügbar markiert.

Wenn Gmail das Postfach einschränkt

Gmail begrenzt, wie viel ein Postfach pro Tag über IMAP herunterladen darf. Meldet Gmail, dass ein Postfach diese Grenze überschritten hat, pausiert HelpStack die Abfrage dieses Postfachs (zuerst 30 Minuten, bei Wiederholung länger, höchstens 6 Stunden), statt es jede Minute erneut zu versuchen, was die Sperre nur aufrechterhalten würde. Der Tab Verbindung des Kanals zeigt dann Gmail hat dieses Postfach vorübergehend eingeschränkt; neuer Versuch um HH:MM. Es gehen keine E-Mails verloren: Sobald die Abfrage wieder läuft, holt HelpStack alles nach, was während der Pause eingegangen ist. Bis dahin ist auch der Abruf von Anhängen aus diesem Postfach nicht möglich. Andere E-Mail-Anbieter, die dieselbe Art von Grenze melden, werden genauso behandelt.

Kontaktformulare, die von Ihrer eigenen Adresse gesendet werden

Kontaktformulare auf Websites senden ihre E-Mails oft von Ihrer eigenen Postfachadresse und setzen den Besucher in Reply-To oder in den Nachrichtentext. Wenn die Absenderadresse einer eingehenden E-Mail die eigene Adresse des Kanals ist, behandelt HelpStack sie als weitergeleitet und verwendet der Reihe nach:

1. die erste Reply-To-Adresse, die nicht Ihre eigene ist, oder
2. eine Email:-Zeile im Nachrichtentext.

Die Konversation und jede Antwort gehen dann an diesen Kunden. Sein Name stammt aus einer Zeile Name: (oder Ime in priimek:) im Text, sonst aus dem Anzeigenamen in Reply-To, sonst aus der Adresse. Wird nichts gefunden, wird die E-Mail wie bisher übernommen.

Threading

Threading-Informationen werden in den Gesprächsmetadaten gespeichert, sodass Antworten korrekt im selben Thread erscheinen:

Den Poller ausführen

npm run email:poll

Führen Sie diesen Worker zusammen mit der App (und dem Nachrichtenwarteschlangen-Worker) aus, damit eingehende E-Mails erfasst werden. In der Produktion wird etwa alle 60s gepollt; in der Entwicklung etwa alle 10s.

Umgebungsvariablen#

Verschlüsselung#

Die IMAP/SMTP-Anmeldedaten jedes Kanals werden mit AES-256-GCM verschlüsselt gespeichert. Das Dashboard bietet eine Test-Schaltfläche, die die konfigurierten Anmeldedaten validiert (verbindet sich und authentifiziert sich), bevor Sie sie speichern/verwenden.

Verifizierte Anmeldedatenfelder für einen E-Mail-Kanal (credentials):

host, port, username, password, from,
secure?, imapHost?, imapPort?, imapSecure?, imapAllowSelfSigned?

Ausgehend: SMTP über nodemailer#

Antworten werden per SMTP über nodemailer mit den eigenen SMTP-Anmeldedaten des Kanals gesendet: host, port, secure, user, pass und from. Das Senden von ausgehenden Nachrichten wird durch die Sender der Nachrichtenwarteschlange übernommen.

Kanal-SMTP vs. System-Benachrichtigungs-SMTP

Dies sind zwei separate E-Mail-Pfade — verwechseln Sie sie nicht:

System-Benachrichtigungs-E-Mails (z. B. Konto-/Systemmeldungen) verwenden immer den per Umgebungsvariable konfigurierten SMTP und den Standardabsender noreply@helpstack.eu, unabhängig von einem Kanal.

Verwandte Themen#

• API-Referenz
• Webhooks
• Kanäle-Leitfaden
• Glossar