Konnektoren
Schemaobjekte
Die SQL- und Dateibrücke
Das OAuth 2.0 Verfahren
Gesperrte Datensätze

E-Mail Konnektor

Der E-Mail-Konnektor verbindet Syncler mit einem E-Mail-Server zum Lesen eingehender Nachrichten und zum Versenden von E-Mails. Er unterstützt IMAP und POP3 für den Eingang, SMTP für den Versand sowie (optional) die Anmeldung über Microsoft 365 (OAuth 2.0).

Neu seit 27.11.2024 (Georg Bergholz):
Das Schema wurde um UserData-Felder erweitert, damit Daten im Ablauf (Mailmerge/Templating) übergeben werden können.

Funktionsumfang

  • Lesen von Nachrichten über IMAP oder POP3
  • Versenden von E-Mails über SMTP ( optional mit OAuth 2.0 / M365 )
  • Abruf-Filter: per UID, per Datum („delivered after“), per Liste vorgegebener UIDs
  • Anhänge lesen (inkl. Base64-Inhalt & Größenangabe)
  • Inline-Bilder automatisch auflösen (CID → Dateiname in HtmlBodyInlineImages)
  • Templating/Mailmerge mit UserData1..3 und beliebigen Datenobjekten
  • Verschieben/Löschen von Nachrichten (IMAP) bzw. Löschen (POP3)
  • Proxy-Unterstützung (HTTP-Proxy aus globaler Konfiguration)

Voraussetzungen

  • Erreichbarer E-Mail-Server (IMAP oder POP3 für Eingang, SMTP für Versand)
  • Zugangsdaten (Benutzername/Passwort) oder Microsoft 365-App (OAuth 2.0)
  • Bei M365: App-Registrierung mit passenden Scopes (siehe unten)

Einrichtung & Konfiguration

Eingang (IMAP/POP3)

Einstellung Beschreibung
IncomingProtocol IMAP oder POP3
IncomingAddress Hostname des Servers, z. B. imap.example.com
IncomingPort Port (IMAP häufig 993, POP3 häufig 995)
IncomingUsername Benutzername für den Eingangsserver
IncomingPassword Passwort (nur bei klassischer Anmeldung)
IncomingSsl TLS/SSL verwenden
IncomingFolder (IMAP) Zu öffnender Ordner; leer = Posteingang

Hinweis: Bei IMAP wird der angegebene Ordner ReadOnly geöffnet, es erfolgt kein automatisches Löschen oder Verschieben – das steuern Sie explizit über Aktionen (siehe unten).

Versand (SMTP)

Einstellung Beschreibung
SmtpServer SMTP-Host, z. B. smtp.example.com
SmtpPort Port (STARTTLS oft 587, SMTPS oft 465)
SmtpUser SMTP-Benutzername (oder M365-Konto)
SmtpPassword SMTP-Passwort (bei klassischer Anmeldung)
SmtpSsl STARTTLS/SSL verwenden
SmtpSender Standard-Absenderadresse (falls keine „From“-Adresse im Datensatz)
SmtpSenderName Anzeigename des Absenders

Für Microsoft 365 kann der SMTP-Login ohne Passwort per OAuth 2.0 erfolgen (siehe nächstes Kapitel).

Microsoft 365 (optional)

Einstellung Beschreibung
O365TenantId Mandanten-ID (GUID)
O365ClientId App-Client-ID
O365ClientSecret App-Geheimnis (optional, je nach Flow)
O365UseClientCredentials Client-Credentials-Flow (Server-zu-Server)
O365RedirectUrl Redirect-URI der App
O365Scopes Standard: offline_access https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/POP.AccessAsUser.All https://outlook.office.com/SMTP.Send

  • User-Delegated (Authorization Code + Refresh Token):
    Verwenden Sie O365ClientId, ggf. O365ClientSecret, O365RedirectUrl und O365Scopes inkl. offline_access.
    Der Konnektor holt/aktualisiert Access/Refresh Token automatisch.

  • Client Credentials (Server-zu-Server):
    Aktivieren Sie O365UseClientCredentials. Scopes anpassen (kein offline_access).
    Hinweis: IMAP/POP/SMTP unterstützen diesen Flow nicht in allen Tenants/Setups; prüfen Sie Ihre M365-Anforderungen.

Datenmodell (Schema)

Objekt: MimeMessage

Wichtige Felder:

Feld Typ Beschreibung
Uid (ID-Spalte) String Eindeutige UID (IMAP: UniqueId.Id, POP3: GetMessageUid)
MessageId String MIME-Message-ID
Subject String Betreff
Date Datetime Versand-/Empfangszeit (auch UpdatedInfoColumn)
TextBody String Nur-Text-Inhalt
HtmlBody String HTML-Inhalt
HtmlBodyInlineImages String HTML mit aufgelösten CIDs → Dateinamen
InReplyTo, ResentMessageId String Antwort/Weiterleitung
Priority, Importance String Priorität/Importance
FileContent String Komplette E-Mail als EML (Base64)
Response String SMTP-Serverantwort nach Versand
UserData1..3 String Freie Felder für Laufzeitdaten/Templating

Gruppen

  • MailboxAddress (Address), LinkTypes: To, From, Cc, Bcc, ReplyTo, Sender
    Felder: Address, Name
  • Attachment (Attachment), LinkType list
    Felder: FileName, ContentId, FileSize, FileContent (Base64)
  • AddAttachment (zum Versand)
    Felder: FileName, FileContent (Base64), FileUrl (Download), TemplateId (Ablage/Template)
  • Data (beliebige Datenquelle für Platzhalter im Templating. Wird von Syncs automatisch gefüllt.)

E-Mails abrufen

  • Alle Nachrichten: ohne weitere Filter lädt der Konnektor alle Nachrichten (IMAP: Ordner; POP3: Liste).
  • Nach Datum: Verwenden Sie den Parameter GETDATA_DELIVERED (z. B. „ab letztem Sync“).
  • Gezielt per UID:
    • IMAP: Liste von UIDs übergeben (Where-Liste)
    • POP3: GetMessageUid(i) als Where-Wert
  • Ad-hoc (Einzel-ID): Übergabe der ID (UID) lädt genau diese Nachricht.

Bei IMAP wird das Postfach nur lesend geöffnet. Senden, Verschieben, Löschen sind separate Schritte.

E-Mails versenden

Zum Senden erstellen Sie ein MimeMessage-Objekt mit:

  • MailboxAddress-Einträgen (mindestens To; optional From/Cc/Bcc/ReplyTo/Sender).
  • Subject, TextBody und/oder HtmlBody.
  • Optionalen AddAttachment-Einträgen (Datei anhängen, s. u.).
  • Optionalen UserData-Feldern für Abläufe oder Data-Gruppe für Platzhalter.

Nach dem Versand wird die SMTP-Response im Feld Response abgelegt.

Anhänge & Inline-Bilder

  • Anhänge senden:
    • AddAttachment.FileContent (Base64) oder
    • AddAttachment.FileUrl (der Konnektor lädt die Datei herunter) oder
    • AddAttachment.TemplateId (Datei aus der Vorlagen-/Ablage)
  • Inline-Bilder in HTML:
    • HtmlBody kann data:image/...;base64,... enthalten → wird automatisch als LinkedResource eingebettet und src → cid:<ContentId> ersetzt.
    • Bildnamen ohne http werden in der Template-Ablage gesucht und ebenfalls eingebettet.

Nachrichten verschieben oder löschen

Diese Operationen werden über SetData mit Parametern gesteuert:

  • Verschieben (IMAP):
    • MoveMessage (Flag) und TargetFolder (Zielordner)
    • Voraussetzung: Die Nachricht ist im System vorhanden (enthält Uid).
  • Löschen:
    • IMAP: Nachricht per UID mit MessageFlags.Deleted markieren und Expunge.
    • POP3: Nachricht per GetMessageUid(i) finden und löschen.
  • Die Ausführung wird durch spezielle Sync-Typen automatisch vorgenommen.

Bei POP3 ist Verschieben nicht möglich (Protokoll-bedingt).