Enduser

Geschätzte Lektüre: 11 Minuten 5 Ansichten

Diese Anleitung führt Endkunden vollständig durch die Einrichtung des E-Mail Controllers. Als Beispiele werden eine private Gmail-Adresse meinname@gmail.com und eine private Outlook.com-Adresse meinname@outlook.com verwendet.

Die tabellarische Aufführung aller Parameter, Eingänge und Ausgänge einschließlich GPA-Porttyp, KNX-DPT, Beispiel-Gruppenadresse, Pflichtstatus, Standardwert und Beschreibung befindet sich in der Port- und Parameterreferenz. Sie ist Bestandteil dieser Endanwenderdokumentation.

Für Google Workspace oder Microsoft 365 in einem Unternehmen können zusätzliche Freigaben durch den Administrator notwendig sein. Die technischen Hintergründe und Unternehmensvarianten stehen in der ausführlichen OAuth-Dokumentation und in der Administrator-Dokumentation.

1. Was der Baustein macht

Beim Wechsel von Trigger auf 1 versendet der X1 eine E-Mail. OAuth bedeutet, dass nicht das normale Kontokennwort auf dem X1 gespeichert wird. Stattdessen erhält der Baustein einen langfristigen Refresh-Token und tauscht ihn vor jeder Nachricht gegen einen kurzlebigen Access-Token. Mit diesem meldet er sich über XOAUTH2 am SMTP-Server an.

Die einmalige Kontoanmeldung und Zustimmung erfolgen aus Sicherheitsgründen an einem PC mit Browser. Der X1 selbst zeigt keine Anmeldeseite an.

2. Welche Variante soll ich verwenden?

E-Mail-Konto	Passendes Beispiel
`@gmail.com`	Kapitel 4: Gmail
private Google-Workspace-Adresse	Gmail-Anleitung; eventuell Freigabe durch Workspace-Administrator
`@outlook.com`, `@hotmail.com`, `@live.com`	Kapitel 5: privates Outlook.com
Microsoft-365-Firmenkonto	Administrator-Dokumentation; nicht mit privatem Outlook.com verwechseln
anderer Provider	Provider muss SMTP-XOAUTH2 und Refresh-Tokens unterstützen; Administrator fragen

3. Vorbereitung im GPA

Den Logikbaustein in eine Logikseite einfügen. Zunächst nur folgende Felder vorbereiten:

To: Zieladresse für die Testmail
From: sendende Adresse
From name: beispielsweise Gira X1
Subject: beispielsweise Test vom Gira X1
Body: beispielsweise Der OAuth-Versand funktioniert.
Timeout: zunächst 30

Trigger erst anschließen oder betätigen, nachdem alle Providerfelder vollständig eingetragen sind. Client-Secret und Refresh-Token niemals in Subject, Body oder Gruppenadressen kopieren.

4. Beispiel A: private Gmail-Adresse

In diesem Beispiel sendet meinname@gmail.com eine Testmail an empfaenger@example.net.

4.1 Google-Projekt und Zustimmungsbildschirm erstellen

Am PC die Google Cloud Console öffnen.
Mit meinname@gmail.com anmelden.
Oben ein neues Projekt anlegen, beispielsweise Gira X1 Email.
Im Projekt Google Auth Platform öffnen.
Unter Branding einen App-Namen wie Gira X1 Email und die eigene Support-E-Mail eintragen.
Unter Audience für ein privates Gmail-Konto External wählen.
Solange die App im Testmodus ist, meinname@gmail.com als Testnutzer hinzufügen.
Unter Data Access den folgenden Scope ergänzen:

https://mail.google.com/

Dieser Scope ist notwendig, weil Gmail SMTP-XOAUTH2 nicht mit dem Gmail-API-Scope gmail.send, sondern mit dem vollständigen Mail-Scope arbeitet.

4.2 OAuth-Client erstellen

In Google Auth Platform Clients öffnen.
Create client wählen.
Als Typ Web application auswählen.
Als Namen beispielsweise Gira X1 OAuth Playground eintragen.
Unter Authorized redirect URIs exakt hinzufügen:

https://developers.google.com/oauthplayground

Client erstellen.
Die angezeigte Client ID und das Client secret vorübergehend in einem sicheren Passwortmanager speichern.

4.3 Gmail-Refresh-Token erzeugen

Den offiziellen Google OAuth 2.0 Playground öffnen.
Oben rechts auf das Zahnrad OAuth 2.0 configuration klicken.
Use your own OAuth credentials aktivieren.
Client-ID und Client-Secret aus dem vorherigen Schritt eintragen.
Access type auf Offline stellen.
Force prompt auf Consent Screen stellen.
Die Konfiguration schließen.
Links unter Input your own scopes exakt eingeben:

https://mail.google.com/

Authorize APIs anklicken.
Mit meinname@gmail.com anmelden und die Berechtigung bestätigen.
Nach der Rückleitung in Schritt 2 auf Exchange authorization code for tokens klicken.
Den angezeigten Refresh token sicher kopieren. Der Access-Token wird nicht benötigt.

Wichtig: Im Playground müssen die eigenen Clientdaten verwendet werden. Die vom Playground selbst bereitgestellten Standard-Clientdaten eignen sich nicht für einen dauerhaften Betrieb. Bei einem externen Google-Projekt im Teststatus kann ein Refresh-Token nach sieben Tagen ablaufen. Für dauerhaften Betrieb muss die OAuth-App passend veröffentlicht bzw. durch den Workspace-Administrator freigegeben werden.

4.4 Gmail-Werte im GPA

GPA-Feld	Beispielwert
`SMTP server`	`smtp.gmail.com`
`SMTP port`	`587`
`Encryption`	`STARTTLS`
`Authentication`	`OAuth2 Refresh Token`
`SMTP user`	`meinname@gmail.com`
`From`	`meinname@gmail.com`
`OAuth client ID`	Client-ID aus Google Cloud
`OAuth client secret`	Client-Secret aus Google Cloud
`OAuth refresh token`	Refresh-Token aus dem Playground
`OAuth token endpoint`	`https://oauth2.googleapis.com/token`
`OAuth scope (optional)`	leer lassen
`OAuth client authentication`	`Form`
`Timeout`	`30`

Alternativ unterstützt Gmail Port 465 mit SSL/TLS. Port 587 und STARTTLS sind die empfohlene Grundeinstellung für dieses Beispiel.

4.5 Gmail testen

To = empfaenger@example.net setzen.
Projekt auf den X1 übertragen.
Warten, bis LicenseInfo eine gültige Lizenz meldet.
Trigger einmal von 0 auf 1 setzen.
Status beobachten:
- Sending...: Versand läuft.
- Message sent: Versand erfolgreich.
Success muss anschließend 1 sein.
Posteingang und gegebenenfalls Spamordner des Empfängers prüfen.

5. Beispiel B: private Outlook.com-Adresse

Dieses Kapitel gilt für private Adressen wie:

meinname@outlook.com
meinname@hotmail.com
meinname@live.com

Es gilt nicht unverändert für ein Firmenkonto in Microsoft 365. Private Outlook.com-Konten verwenden smtp-mail.outlook.com; Microsoft-365-Firmenkonten verwenden üblicherweise smtp.office365.com und benötigen häufig eine Administratorfreigabe.

5.1 Microsoft-App registrieren

Am PC das Microsoft Entra Admin Center öffnen.
Mit dem Microsoft-Konto anmelden.
Identity > Applications > App registrations öffnen.
New registration wählen.
Als Namen Gira X1 Email Controller eintragen.
Bei Supported account types eine Option wählen, die personal Microsoft accounts ausdrücklich einschließt.
Registrierung abschließen.
Die Application (client) ID kopieren.
Unter API permissions > Add a permission nach Office 365 Exchange Online suchen.
Delegated permissions wählen und SMTP.Send hinzufügen.
Unter Authentication > Advanced settings die Option Allow public client flows aktivieren.

Für dieses Beispiel wird kein Client-Secret erstellt. Wenn die App-Registrierung mit einem privaten Microsoft-Konto nicht verfügbar ist, muss ein Administrator bzw. Integrator eine passende Multi-Tenant-App bereitstellen. Ohne registrierte Client-ID kann Outlook.com-OAuth nicht eingerichtet werden.

5.2 Outlook.com-Refresh-Token erzeugen

Windows PowerShell an einem vertrauenswürdigen PC öffnen.
Im folgenden Skript <CLIENT-ID> durch die Application-ID ersetzen.
Das Skript vollständig ausführen:

$clientId = '<CLIENT-ID>'
$scope = 'offline_access https://outlook.office.com/SMTP.Send'
$base = 'https://login.microsoftonline.com/consumers/oauth2/v2.0'

$device = Invoke-RestMethod -Method Post -Uri "$base/devicecode" -Body @{
    client_id = $clientId
    scope = $scope
}

Write-Host $device.message
$deadline = (Get-Date).AddSeconds([int]$device.expires_in)
$interval = [Math]::Max(5, [int]$device.interval)
$token = $null

while (-not $token -and (Get-Date) -lt $deadline) {
    Start-Sleep -Seconds $interval
    try {
        $token = Invoke-RestMethod -Method Post -Uri "$base/token" -Body @{
            grant_type = 'urn:ietf:params:oauth:grant-type:device_code'
            client_id = $clientId
            device_code = $device.device_code
        }
    }
    catch {
        $oauthError = $null
        try { $oauthError = $_.ErrorDetails.Message | ConvertFrom-Json } catch { }
        if ($oauthError.error -eq 'authorization_pending') { continue }
        if ($oauthError.error -eq 'slow_down') { $interval += 5; continue }
        throw
    }
}

if (-not $token -or -not $token.refresh_token) {
    throw 'Kein Refresh-Token empfangen.'
}

Write-Host 'Refresh-Token (vertraulich):'
Write-Host $token.refresh_token

PowerShell zeigt eine Microsoft-Adresse und einen kurzen Anmeldecode an.
Die angezeigte Adresse im Browser öffnen; normalerweise ist dies https://microsoft.com/devicelogin.
Den Code eingeben.
Mit meinname@outlook.com anmelden.
Den Zugriff für SMTP-Versand bestätigen.
Zur PowerShell zurückkehren.
Den ausgegebenen Refresh-Token sicher kopieren.
PowerShell-Verlauf und Bildschirmaufzeichnungen schützen; der Refresh-Token ist wie ein Kennwort zu behandeln.

Der Scope offline_access sorgt dafür, dass Microsoft einen Refresh-Token liefert. https://outlook.office.com/SMTP.Send erlaubt den delegierten SMTP-Versand. Der Graph-Scope Mail.Send ist für diesen SMTP-Baustein nicht der richtige Scope.

5.3 Outlook.com-Werte im GPA

GPA-Feld	Beispielwert
`SMTP server`	`smtp-mail.outlook.com`
`SMTP port`	`587`
`Encryption`	`STARTTLS`
`Authentication`	`OAuth2 Refresh Token`
`SMTP user`	`meinname@outlook.com`
`From`	`meinname@outlook.com`
`OAuth client ID`	Application (client) ID
`OAuth client secret`	leer
`OAuth refresh token`	Ausgabe des PowerShell-Skripts
`OAuth token endpoint`	`https://login.microsoftonline.com/consumers/oauth2/v2.0/token`
`OAuth scope (optional)`	`https://outlook.office.com/SMTP.Send`
`OAuth client authentication`	`None`
`Timeout`	`30`

Für private Outlook.com-Postfächer existiert kein Microsoft-365-Admin-Center-Schalter Authenticated SMTP. Dieser Schalter gehört zu Exchange-Online-Unternehmenspostfächern. Outlook.com verlangt laut Microsoft moderne Authentifizierung/OAuth2 und verwendet für SMTP Port 587 mit STARTTLS.

5.4 Outlook.com testen

To auf eine andere erreichbare Adresse setzen.
Projekt auf den X1 übertragen.
Gültigen Lizenzstatus abwarten.
Trigger einmal setzen.
Bei Message sent und Success = 1 Posteingang/Spamordner prüfen.
Bei Fehler 535, 5.7.3 oder AuthenticationException zuerst Client-ID, Scope, SMTP-Benutzer und den Server smtp-mail.outlook.com prüfen.

6. Dynamische Werte in Betreff und Nachricht

Mit Number of values werden zwischen 1 und 99 String-Eingänge erzeugt. Sie erscheinen als variabler Block ganz unten in der Eingangsliste:

Value1
Value2
Value3
...

In Subject und Body werden die passenden Platzhalter verwendet:

Subject: Alarm von {{Value1}}
Body: Der Sensor {{Value1}} meldet {{Value2}} bei {{Value3}} °C.

Beim Trigger übernimmt der Baustein Nachricht und Werte als gemeinsamen Snapshot. Spätere Änderungen verändern eine bereits laufende E-Mail nicht. Nicht verbundene Eingänge ergeben leeren Text. Die Schreibweise ist exakt einzuhalten: {{Value1}} funktioniert, {{value1}} nicht.

6.1 Werteingänge im GPA anlegen

Den Parameter Number of values auf die benötigte Anzahl stellen.
Bei 3 erzeugt der Baustein unten in der Eingangsliste genau diese Ports:

Value1
Value2
Value3

Jeden Port mit einer Gruppenadresse oder dem Ausgang eines anderen Logikbausteins verbinden.
Merken oder dokumentieren, welcher reale Wert an welcher Nummer liegt.

Beispielzuordnung:

Eingang	Verbundener Wert	Beispielwert zur Laufzeit
`Value1`	Name der Anlage	`Pooltechnik`
`Value2`	Wassertemperatur als Text	`27,4`
`Value3`	Störungsstatus als Text	`Filterdruck zu hoch`

Die Werteingänge sind String-Eingänge. Zahlen, Binärwerte oder Datumswerte müssen bei Bedarf vorher mit einem passenden Konverter in Text umgewandelt und formatiert werden. Der E-Mail Controller fügt keine Einheit und keine Rundung automatisch hinzu.

6.2 Platzhalter in den Betreff schreiben

Für jeden Eingang wird dieselbe Nummer in doppelten geschweiften Klammern verwendet:

Eingang	Platzhalter
`Value1`	`{{Value1}}`
`Value2`	`{{Value2}}`
`Value3`	`{{Value3}}`
`Value12`	`{{Value12}}`

Mit der Beispielzuordnung kann Subject so aussehen:

Störung an {{Value1}}: {{Value3}}

Zur Laufzeit entsteht daraus:

Störung an Pooltechnik: Filterdruck zu hoch

Ein Platzhalter darf mehrfach vorkommen:

{{Value1}} meldet eine Störung – Anlage: {{Value1}}

6.3 Platzhalter in den Nachrichtentext schreiben

Der Parameter Body kann normalen Text, Zeilenumbrüche, Einheiten und beliebig viele vorhandene Platzhalter kombinieren:

Hallo,

die Anlage {{Value1}} hat eine Meldung ausgelöst.

Wassertemperatur: {{Value2}} °C
Status: {{Value3}}

Diese Nachricht wurde automatisch vom Gira X1 versendet.

Das konkrete Ergebnis lautet beispielsweise:

Hallo,

die Anlage Pooltechnik hat eine Meldung ausgelöst.

Wassertemperatur: 27,4 °C
Status: Filterdruck zu hoch

Diese Nachricht wurde automatisch vom Gira X1 versendet.

6.4 Regeln und Sonderfälle

Nur Subject und Body werden ersetzt. In To, Cc, Bcc, From und den OAuth-Feldern sind keine Platzhalter vorgesehen.
Die Schreibweise ist groß-/kleinschreibungsabhängig: {{Value2}} ist korrekt, {{value2}} bleibt unverändert.
Die Nummer muss existieren. Bei Number of values = 3 bleibt {{Value4}} als sichtbarer Text stehen, weil kein vierter Eingang vorhanden ist.
Existiert der Eingang, hat aber noch keinen Wert, wird sein Platzhalter durch leeren Text ersetzt.
Ein Wert wird ohne automatische Maskierung oder Formatierung eingesetzt. Enthält er Zeilenumbrüche, erscheinen diese auch im Nachrichtentext.
Die Ersetzung erfolgt erst beim Sende-Trigger. Dadurch gehören Betreff, Nachricht und Eingangswerte zeitlich zusammen.
Geschweifte Klammern für normalen Text vermeiden, wenn sie exakt dem Muster {{ValueN}} entsprechen.

6.5 Vollständiges Praxisbeispiel

GPA-Konfiguration:

Number of values: 4
Value1: Außenfühler-Name
Value2: Außentemperatur als Text
Value3: Windgeschwindigkeit als Text
Value4: Zeitstempel als Text

Subject: Wetterwarnung {{Value1}} – {{Value2}} °C

Body:
Messstelle: {{Value1}}
Temperatur: {{Value2}} °C
Wind: {{Value3}} km/h
Zeitpunkt: {{Value4}}

Bei den Eingangswerten Nordseite, -3,2, 48 und 17.07.2026 18:30 versendet der Baustein:

Betreff: Wetterwarnung Nordseite – -3,2 °C

Messstelle: Nordseite
Temperatur: -3,2 °C
Wind: 48 km/h
Zeitpunkt: 17.07.2026 18:30

7. Ein- und Ausgänge

Trigger: startet den Versand bei positiver Flanke.
Value1 bis ValueN: dynamische Stringwerte.
Success: Ergebnis des letzten Versands.
Status: aktueller Versandzustand oder Fehler.
LicenseInfo: Zustand der Lizenz.

Ein neuer Trigger während eines laufenden Versands wird mit Send already in progress abgewiesen.

8. Häufige Fehler

Status enthält	Bedeutung und Maßnahme
`OAuth token refresh failed: invalid_client`	Client-ID, Secret oder `Form`/`None` falsch.
`OAuth token refresh failed: invalid_grant`	Refresh-Token abgelaufen/widerrufen oder gehört zu anderem Client; neu erzeugen.
`invalid_scope`	Gmail-Scope bzw. Outlook-SMTP-Scope falsch.
`AuthenticationException`	Access-Token wird vom SMTP-Server abgelehnt; Server, Benutzer, Scope und XOAUTH2-Freigabe prüfen.
`SocketException` oder Timeout	Internetzugang, DNS, Firewall, SMTP-Host, Port und Verschlüsselung prüfen.
`Send already in progress`	Ersten Versand abschließen lassen und Trigger danach erneut setzen.
Gmail-Token funktioniert nur sieben Tage	Google-Projekt steht als externe App im Teststatus. Veröffentlichungs-/Freigabestatus prüfen.
Outlook-Skript liefert keinen Refresh-Token	`offline_access`, persönlicher Kontotyp und Public Client Flow prüfen.

9. Sicherheit

Refresh-Token und Client-Secret niemals an Supportanfragen oder Screenshots anhängen.
Keine echten Tokens in Beispieltexte, Gruppenadressen oder E-Mail-Inhalte kopieren.
Bei Verdacht auf Offenlegung den OAuth-Grant beim Provider widerrufen und neue Werte erzeugen.
Vor Weitergabe eines GPA-Projekts alle Secrets entfernen.
Für den X1 möglichst ein eigenes Absenderkonto verwenden.

10. Offizielle Quellen

Google: OAuth 2.0 Playground
Google: Gmail XOAUTH2 und SMTP-Scope
Google: Gmail SMTP-Server und Ports
Microsoft: Outlook.com SMTP-Einstellungen
Microsoft: SMTP mit OAuth
Microsoft: Device-Code-Flow

Stand: 17. Juli 2026.