mail

Der “mail”-Konnektor dient zum E-Mail-Versand aus niotix heraus und wird in zwei Szenarien eingesetzt:

  • Regeleditor im Digitalen Zwilling: Im Regeleditor können Regeln erstellt werden, die beim Eintreten bestimmter Wert-Entwicklungen E-Mails versenden.
  • Systemmails: Der Konnektor kann auf Konto-Ebene als SMTP-Relay für niotix-Systemmails konfiguriert werden (z. B. Passwort-Reset, Willkommens-E-Mail, Benachrichtigungen). Die Zuordnung erfolgt in der Konto-Verwaltung unter E-Mail-Einstellungen → Mail-Konnektor verwenden.

Details zur Funktion:

  • Protokoll: SMTP via Nodemailer; unterstützte Felder je Nachricht: from, to, cc, bcc, subject, text, html, Anhänge
  • Authentifizierung: Benutzername/Passwort oder OAuth2 — automatische Token-Erneuerung nur für Outlook365(OAuth2.0) implementiert (inkl. einmaligem Retry bei Authentifizierungsfehler 535); alle anderen Dienste verwenden Nodemailer-Standard-Auth
  • TLS: Secure → implizites TLS ab Verbindungsaufbau (typischerweise Port 465); Unsecure → Verbindung beginnt unverschlüsselt, STARTTLS wird vom Server angeboten; IgnoreTLS → STARTTLS-Aushandlung wird deaktiviert (rein unverschlüsselte Übertragung)
  • Verbindungs-Timeout: 2.000 ms (TCP-Verbindung zum SMTP-Server); Gesamttimeout des Sendevorgangs: 15 Sekunden
  • Retry: Kein automatischer Retry (außer Outlook 365 OAuth2: ein Retry nach Token-Erneuerung bei Fehler 535)
  • Rate Limiting: Optional pro Stunde konfigurierbar; ohne Angabe gilt kein Limit

Einstellungen

  • Instanz-Name: Individueller, einfach zu erschließender Name des Konnektors.
  • Beschreibung: Kurze Beschreibung.
  • Fallback “from’-mail: Eine Absendeadresse die angezeigt wird, falls z. B. in einer Regel im Digitalen Zwilling keine Absendeadresse hinterlegt wird
  • Service: E-Mail-Service-Provider (falls verfügbar; konfiguriert die Authentifizierung automatisch)
  • Host: Adresse des SMTP-Servers.
  • Port: Port des SMTP-Servers.
  • User: Benutzername des Servers.
  • Pass: Passwort des Benutzers.
  • Secure/Unsecure: Legt fest, ob eine gesicherte Verbindung (TLS) verwendet wird.
  • Ignore/UnignoreTLS: Steuert die STARTTLS-Aushandlung bei unverschlüsselten Verbindungen (Secure: false). IgnoreTLS deaktiviert STARTTLS vollständig; UnignoreTLS lässt die Aushandlung zu.
  • Self-signed certificate: accept erlaubt selbstsignierte Zertifikate; reject lehnt sie ab.
  • Rate limit (per hour): Maximale Anzahl E-Mails pro Stunde, die über diesen Konnektor gesendet werden dürfen. Bei Überschreitung verwirft niotix weitere Mails und schreibt einen Eintrag in das Konnektor-Log.

Hinweise zur Einrichtung eines Mail-Konnektors mit Service Outlook365(OAuth2)

Vorbedingungen

Folgende Schritte müssen innerhalb von Entra-ID und Exchange erfolgt sein, um diesen Konnektor verwenden zu können:

  1. Es ist eine Entra-ID-Anwendung eingerichtet und mit den benötigten Berechtigungen ausgestattet.
    Zur Microsoft Dokumentation: Authentifizieren einer IMAP-, POP- oder SMTP-Verbindung mithilfe von OAuth
  2. Die authentifizierte Client-SMTP-Übermittlung (SMTP AUTH) in Exchange Online ist aktiviert.
    Zur Microsoft Dokumentation: Aktivieren oder Deaktivieren der authentifizierten Client-SMTP-Übermittlung (SMTP AUTH) in Exchange Online

Einrichtung

Zunächst muss in der angelegten Entra-ID-App die Redirect URI für den sogenannten Callback hinterlegt werden. Diese wird auf der Frontend-Domain der Instanz konfiguriert und folgt dem Muster
https://{yourdomain}/api/v1/oauth2/office365/callback,
für die Digimondo SaaS-Instanz „niotix.io” entsprechend
https://niotix.io/api/v1/oauth2/office365/callback [1]

Als Nächstes wird in der angelegten Entra-ID-App das Client Secret angelegt [2].

Nun liegen alle Informationen vor, um den Konnektor einzurichten:

  • Fallback „from"-Mailadresse: E-Mail-Adresse, die als Absender verwendet werden soll.
    Bitte beachten: Dieser Absender muss für die authentifizierte Client-SMTP-Übermittlung (SMTP AUTH) in Exchange Online aktiviert sein.
  • service: Hier wird Outlook365(OAuth2.0) ausgewählt.
  • host: Host des Services, z.B. smtp.office365.com
  • port: Port, der für den Service freigeschaltet ist, z.B. 587
  • User: E-Mail-Adresse des Benutzers, der verwendet werden soll.
    Bitte beachten: Dieser Absender muss für die authentifizierte Client-SMTP-Übermittlung (SMTP AUTH) in Exchange Online aktiviert sein.
  • Client ID: Client-ID der Entra-ID-App [3]
  • Client Secret: Secret, das in der Entra-ID-App angelegt wurde [2]
  • Tenant ID: Tenant-ID der Entra-ID-App [4]

Fehlerbehebung Outlook365(OAuth2)

Die meisten Einrichtungsprobleme mit diesem Konnektor werden durch die Entra-ID-App-Registrierung oder die Postfach-Einstellungen in Exchange Online verursacht – nicht durch niotix selbst. Die folgenden Symptome sind nach Häufigkeit geordnet.

Wichtig – das Speichern des Konnektors ist kein Nachweis, dass er funktioniert.
Nach dem Speichern eines Outlook365(OAuth2.0)-Konnektors wird der Browser zur Anmeldung und Einwilligung an Microsoft weitergeleitet. Der Konnektor kann erst dann E-Mails versenden, wenn diese Weiterleitung erfolgreich abgeschlossen wurde. Wird die Weiterleitung nicht ausgeführt, die Microsoft-Anmeldung abgebrochen oder der Tab vorher geschlossen, existiert der Konnektor zwar, besitzt aber kein Access-Token und kann nicht versenden. In diesem Zustand kann der Konnektor dennoch gültig erscheinen – öffnen Sie ihn erneut und schließen Sie die Microsoft-Anmeldung ab, um die Einrichtung zu vervollständigen.

Der Versand schlägt mit 535 Authentication unsuccessful fehl (oder E-Mails werden ohne Fehlermeldung nicht zugestellt).
Dies ist die mit Abstand häufigste Ursache. Die authentifizierte Client-SMTP-Übermittlung (SMTP AUTH) ist in Exchange Online standardmäßig deaktiviert und muss aktiviert werden – sowohl auf Organisationsebene als auch, falls dort deaktiviert, explizit für das als User / Fallback “from” verwendete Postfach. Aktivieren Sie sie gemäß der Microsoft-Dokumentation und planen Sie einige Minuten ein, bis die Änderung wirksam wird.

Die Microsoft-Anmeldung endet mit AADSTS50011: redirect URI … does not match.
Die in der Entra-ID-App hinterlegte Redirect URI muss der Callback-URL Ihrer Instanz exakt entsprechen – gleiches Schema (https), gleicher Host, gleicher Pfad und kein abschließender Schrägstrich:
https://{yourdomain}/api/v1/oauth2/office365/callback
Für die Digimondo SaaS-Instanz lautet sie https://niotix.io/api/v1/oauth2/office365/callback. Typische Ursache ist eine Abweichung zwischen dem Host, über den niotix geöffnet wird, und dem in Entra-ID hinterlegten Host.

Die Microsoft-Anmeldung schlägt mit einem Tenant-Fehler fehl (z. B. AADSTS90002 / „tenant not found").
Tragen Sie als Tenant ID die GUID des Mandanten aus der Entra-ID-App ein. Verwenden Sie common nur, wenn die App-Registrierung ausdrücklich als mandantenübergreifend (multi-tenant) konfiguriert ist.

Der Versand schlägt fehl, obwohl er zuvor funktioniert hat, oder die Validierung meldet einen OAuth2-Fehler.
Access-Tokens sind kurzlebig (~1 Stunde) und werden automatisch erneuert. Die Erneuerung nutzt das Client Secret, das in Entra-ID abläuft (max. 24 Monate). Läuft das Secret ab – oder wird die Einwilligung für die App entzogen –, schlägt die Token-Erneuerung fehl. Legen Sie in der Entra-ID-App ein neues Client Secret an und aktualisieren Sie das Feld Client Secret des Konnektors. Wurde die Einwilligung entzogen, öffnen Sie den Konnektor erneut und schließen Sie die Microsoft-Anmeldung noch einmal ab.

Der Einwilligungsdialog meldet fehlende Berechtigungen.
Die Entra-ID-App benötigt die delegierte Berechtigung SMTP.Send (Scope https://outlook.office365.com/SMTP.Send offline_access, wobei offline_access das Refresh-Token liefert). Stellen Sie sicher, dass die Berechtigung hinzugefügt und – je nach Mandanten-Richtlinie – die Administrator-Einwilligung erteilt wurde.

E-Mails werden mit SendAsDenied abgewiesen oder ein falscher Absender wird verwendet.
Die Adressen Fallback “from” und User müssen das Postfach sein, das die Einwilligung erteilt hat und für das SMTP AUTH aktiviert ist. Der Versand im Namen einer anderen Adresse wird von Exchange Online abgewiesen.

Es wird nichts versendet, obwohl der Service ausgewählt ist.
Bei der OAuth2.0-Variante füllt der service-Name den Server nicht automatisch aus. Stellen Sie sicher, dass host = smtp.office365.com, port = 587 und Secure/Unsecure = Unsecure (STARTTLS auf 587) explizit gesetzt sind.