IMAP-Trigger einrichten

Ein IMAP-Trigger fragt ein Postfach ab, das dir gehört, und startet für jede neue Nachricht einen Workflow-Run. Nutze ihn, wenn die Mail ohnehin schon dort ankommt, wo du die Kontrolle hast — ein gemeinsames rechnungen@, eine Lieferanten-Benachrichtigungsadresse, ein Ticket-Alias.

Unsicher, welcher E-Mail-Trigger der richtige ist?

Wenn du noch kein Postfach hast, nimm besser den workspace-verwalteten E-Mail-Trigger: SupaCloud gibt dir eine Adresse wie triggers+acme-wf-abcdefghij@…, und du konfigurierst weder Server noch Zugangsdaten noch Polling. Zum IMAP-Trigger greifst du nur, wenn die Mail in deinem Postfach landen muss.

Hinweis

IMAP-Postfächer und IMAP-Trigger sind ein Feature der bezahlten Pläne. Wird das Anlegen der Ressource mit einem Plan-Fehler abgelehnt, enthält dein Plan sie nicht.

Voraussetzungen

• Ein IMAP-Server, der von deiner SupaCloud-Instanz erreichbar ist, sowie Host, Port, Benutzername und Passwort.
• Ein Workspace, in dem du Ressourcen anlegen und einen Workflow bearbeiten darfst.
• Ein Workflow, der gestartet werden soll. Falls du noch keinen hast, arbeite Deinen ersten Workflow bauen durch.

Schritte

1. Postfach-Ressource anlegen.

   Unter Ressourcen → Neu wähle IMAP-Postfach (E-Mail empfangen / pollen) und trage IMAP-Host, Port (993 für implizites TLS), Benutzername und Passwort ein. Lass TLS verwenden aktiviert, es sei denn, dein Server spricht ausschließlich unverschlüsseltes IMAP auf Port 143.

   Das Passwort wird als Secret gespeichert und nie wieder angezeigt.

2. Trigger zum Workflow hinzufügen.

   Öffne den Workflow, zieh IMAP aus der Gruppe Messaging der Trigger-Palette und wähle die eben angelegte Postfach-Ressource aus.

3. Ordner und Abfragetakt festlegen.

   • Ordner — INBOX, sofern du eingehende Mail nicht vorher in einen Unterordner sortierst. Ein Unterordner ist oft die sauberere Variante: deine Mail-Regeln entscheiden dann, was der Workflow überhaupt zu sehen bekommt.
   • Abfrageintervall (Sekunden) — wie oft SupaCloud nachsieht, zwischen 10 und 3600 Sekunden (Standard 60).
   • Claim-Scope — lass ihn auf default. Ändere ihn nur, wenn zwei Trigger dasselbe Postfach bewusst unabhängig voneinander verarbeiten sollen; jeder Scope führt seine eigene Buchhaltung darüber, was er schon erledigt hat.

4. „Erkennung neuer Nachrichten” auf dem UID-Cursor lassen.

   Damit entscheidet der Trigger, welche Nachrichten neu sind — und der Standard UID-Cursor (empfohlen) ist der, den du willst. Was die andere Option kostet, steht unter Wie neue Nachrichten erkannt werden.

   Mit dem UID-Cursor wählst du außerdem Cursor starten bei:

   • Anfang des Ordners (Standard) — alles, was schon im Ordner liegt, wird zugestellt, älteste zuerst. Nichts wird übersprungen.
   • Nur neue Mails ab jetzt — der vorhandene Bestand wird übergangen, und nur Mail, die nach dem Speichern ankommt, wird zugestellt. Nimm das, wenn du einen Trigger an ein großes Archiv hängst.

   Die Wahl gilt nur für den ersten Abruf. Danach steuert sich der Trigger selbst.

5. Festlegen, wie viele Nachrichten ein Abruf mitnimmt.

   Nachrichten pro Abruf (1–200, Standard 8) begrenzt, wie viel Rückstand ein einzelner Abruf abarbeitet. Ein größerer Rückstand wird schlicht von den folgenden Abrufen erledigt — die Einstellung wägt also Aufholtempo gegen die Zeit ab, die ein Abruf den Scheduler belegt. Beim Import eines großen Ordners höher setzen; im Normalbetrieb bei 8 lassen.

6. Speichern und den ersten Run prüfen.

   Speichere den Workflow. Innerhalb eines Abfrageintervalls startet die erste passende Nachricht einen Run. Öffne Runs und prüfe, dass der Trigger-Kontext Absender, Betreff und Text wie erwartet enthält.

Wie neue Nachrichten erkannt werden

Beim UID-Cursor führt SupaCloud pro Trigger und Ordner eine eigene Aufzeichnung: die Generation des Postfachs plus die höchste Nachrichtennummer, die fertig verarbeitet ist. Ein Abruf fragt den Server nach allem oberhalb dieser Marke und liest die Nachrichtentexte, ohne sie zu öffnen.

Warum die Gelesen-Markierung nicht taugt — ein Postfach ist geteilt

Die ältere Option Gelesen-Markierung (veraltet) entscheidet „neu” daran, ob eine Nachricht noch als ungelesen gilt, und markiert jede dabei als gelesen.

Diese Markierung ist geteilter Postfach-Zustand. Jede und jeder — du, eine Kollegin, eine Handy-App, die den Ordner nur vorschaut — kann sie setzen. In dem Moment, in dem ein Mensch das Postfach in einem Mail-Programm öffnet, sieht jede berührte Nachricht für den Trigger schon erledigt aus und wird nie zugestellt. Eine produktive Windmill-Installation hat auf genau diesem Weg über Monate hinweg rund 1.000 Nachrichten verloren — lautlos.

Ein Delta-Indikator muss etwas sein, das ausschließlich das System schreibt. Genau das ist der UID-Cursor. Nie eine Markierung verwenden, die auch ein Mensch setzen kann.

Gelesen-Markierung existiert nur noch, damit Trigger, die vor der Umstellung angelegt wurden, sich unverändert verhalten; für Neues sollte sie niemand verwenden. Findest du sie an einem bestehenden Trigger, ist das Umstellen auf den UID-Cursor gefahrlos: Der Trigger setzt am aktuellen Stand des Ordners auf, und bereits verarbeitete Nachrichten werden erkannt und nicht doppelt ausgeführt.

Was passiert, wenn das Postfach neu aufgebaut wird

Nachrichtennummern sind nur innerhalb einer Generation eines Postfachs aussagekräftig. Legt dein Anbieter den Ordner neu an — eine Rücksicherung aus dem Backup, eine Migration zwischen Servern, ein nach einem Defekt neu aufgebautes Postfach — meldet der Server eine neue Generation, und jede gespeicherte Nummer wird bedeutungslos.

SupaCloud bemerkt das, protokolliert es und liest den Ordner von vorn. Bereits zugestellte Nachrichten werden an ihrer dauerhaften Nachrichten-ID erkannt und nicht erneut ausgeführt; alles wirklich Neue wird zugestellt. Du musst nichts tun — ein Trigger, der sich ständig zurücksetzt, ist aber ein Grund, auf der Mailserver-Seite nachzusehen.

Die Nachricht im Workflow lesen

Jeder nachgelagerte Node liest die Nachricht über ${{ trigger.… }}:

Feld	Inhalt
from / to	Absender- / Empfängerzeile, wortgetreu
subject	der Betreff, oder eine leere Zeichenkette
body_text / body_html	der Textteil; der HTML-Teil, falls vorhanden
message_id	die dauerhafte ID der Nachricht
date	die Date:-Zeile, wortgetreu
folder / uid	woher die Nachricht gelesen wurde, und ihre Nummer
headers	alle Header, kleingeschrieben als Schlüssel
attachments	filename, content_type und size_bytes je Anhang

Der Inhalt von Anhängen bleibt auf dem Server; in den Workflow gelangt nur die Zusammenfassung, damit ein großer Anhang keinen Run aufbläht.

Verwandt

• Deinen ersten Workflow bauen — die Trigger-Spur, die Palette und ${{ trigger.… }}-Templating
• Support-Konversationskanal verbinden — der andere Trigger für eingehende Nachrichten
• Secrets in der Oberfläche verwalten — wo das Postfach-Passwort liegt