Integrationen
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#
| Kanaltyp | EMAIL |
| Eingehend | IMAP-Polling-Worker (npm run email:poll) |
| Ausgehend | SMTP über nodemailer (Kanal-Anmeldedaten) |
| Anmeldedaten | Verschlüsselt gespeichert (AES-256-GCM) pro Kanal |
| Transportsicherheit | IMAP über TLS |
| Polling-Intervall | ~10s (Entwicklung) / ~60s (Produktion) |
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:
- Ruft aktuelle, unverarbeitete E-Mails ab.
- Parst Text, HTML und Anhänge.
- Dedupliziert nach message-id + Vorschau (damit dieselbe E-Mail nicht zweimal erfasst wird).
- Erstellt ein Gespräch, das durch die E-Mail-Adresse des Absenders identifiziert wird.
- Lädt Anhänge in den Speicher hoch.
- Markiert die E-Mail als verarbeitet.
Wie „verarbeitet" nachverfolgt wird
Der Poller bevorzugt ein benutzerdefiniertes IMAP-Schlüsselwort $HelpStackProcessed, das das \Seen-Flag unangetastet lässt (sodass die Nachricht in anderen Clients weiterhin als ungelesen erscheint). Wenn der Server keine benutzerdefinierten Schlüsselwörter unterstützt, fällt er auf das \Seen-Flag zurück.
Empfehlung: Verwenden Sie ein dediziertes Postfach für den Kanal. Wenn der Server keine benutzerdefinierten Schlüsselwörter unterstützt, verlässt sich HelpStack auf
\Seen, um eine erneute Erfassung zu verhindern — wenn das Postfach mit einem menschlichen Leser geteilt wird (der Dinge als gelesen/ungelesen markiert), kann es zu verpassten oder duplizierten Erfassungen kommen.
Threading
Threading-Informationen werden in den Gesprächsmetadaten gespeichert, sodass Antworten korrekt im selben Thread erscheinen:
| Metadatenfeld | Quelle |
|---|---|
emailSubject | Betreff der eingehenden E-Mail |
emailMessageId | Message-ID-Header |
emailReferences | References-/In-Reply-To-Kette |
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#
| Variable | Standard | Zweck |
|---|---|---|
EMAIL_MAX_BODY_BYTES | ~100 KB | Maximale erfasste Body-Größe; längere Inhalte werden abgeschnitten |
EMAIL_MIN_ATTACHMENT_BYTES | ~1 KB | Anhänge kleiner als dieser Wert werden übersprungen (filtert Tracking-Pixel) |
EMAIL_MAX_AGE_DAYS | 5 | E-Mails, die älter als diese Anzahl von Tagen sind, werden ignoriert |
IMAP_ALLOW_SELF_SIGNED | — | Nur Entwicklung — selbstsignierte IMAP-TLS-Zertifikate akzeptieren |
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:
| Kanal-SMTP | System-Benachrichtigungs-SMTP | |
|---|---|---|
| Zweck | Kundenantworten auf einem EMAIL-Kanal | Plattform-/System-Benachrichtigungs-E-Mails |
| Anmeldedaten | Pro Kanal, verschlüsselt | Umgebungsvariablen |
| Konfiguriert über | Kanaleinstellungen | SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_SECURE, SMTP_FROM |
| Standard-Absender | Das from-Feld des Kanals | noreply@helpstack.eu |
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.