Dokumentation

Entra ID einrichten

Aktualisiert am 2026-08-13

Das Relay authentifiziert sich als Anwendung, nicht als Benutzer. Es gibt keinen interaktiven Login und kein Refresh-Token. Diese Schritte gehen Sie im Microsoft-365-Tenant Ihres Kunden durch, einmal je Kundentenant.

1. Anwendung registrieren. Entra Admin Center → App-Registrierungen → Neue Registrierung. Single Tenant. Es wird keine Redirect-URI benötigt.
2. Client-Secret erstellen. Zertifikate & Geheimnisse → Neues Client-Secret. Kopieren Sie den Wert sofort, er wird nur einmal angezeigt. Notieren Sie sich das Ablaufdatum - die Zustellung stoppt, wenn es abläuft.
3. Anwendungsberechtigungen hinzufügen unter API-Berechtigungen → Microsoft Graph → Anwendungsberechtigungen:
   • Mail.Send
   • Mail.ReadWrite
4. Administratorzustimmung erteilen. Anwendungsberechtigungen bewirken nichts, solange kein Administrator zugestimmt hat.

Warum Mail.ReadWrite benötigt wird, und wie Sie es eng fassen

Mail.Send allein reicht nicht aus. Jeder Anhang, der groß genug für eine Upload-Session ist, wird als Entwurf angelegt, und einen Entwurf anzulegen erfordert Mail.ReadWrite. In der Praxis ist das bei den meisten Scans der Fall. Der Verbindungstest verwendet denselben Mechanismus.

Mail.ReadWrite tenantweit erteilt bedeutet Lese- und Schreibzugriff auf jedes Postfach dieses Kunden, und das ist nicht, was Sie wollen. Beschränken Sie die Anwendung auf genau die Postfächer, die sie berühren darf:

• RBAC for Applications (aktueller Ansatz): Erstellen Sie einen Verwaltungsbereich (Management Scope), der nur das Postfach umfasst, aus dem gesendet werden soll, und weisen Sie der Anwendung eine Rolle darin zu.
• Application Access Policy (älter, weiterhin unterstützt): Erstellen Sie eine mailaktivierte Sicherheitsgruppe, die nur dieses Postfach enthält, und wenden Sie eine Richtlinie an, die die Anwendung darauf beschränkt.

Tun Sie dies, wenn möglich, bevor Sie die Zustimmung erteilen. Ein unbeschränktes Mail.ReadWrite ist der größte Konfigurationsfehler, den Sie mit diesem Produkt machen können.

Schnellstart

Aktualisiert am 2026-09-28

Ein Standort kommt in drei Schritten dazu: Kunde und Standort in der Plattform anlegen, den Agenten beim Kunden installieren und mit dem im Portal für diesen Standort ausgestellten Aufnahme-Token aufnehmen (letterhop enrol -token <token>), das Gerät umstellen. Sobald das Relay aufgenommen ist, lässt sich fast alles Folgende auch aus dem Portal erledigen statt auf der Kommandozeile - siehe Fernwartung. Diese Seite beschreibt den Weg über die Kommandozeile.

Davor steht die Tenant-Seite: eine App-Registrierung im Microsoft-365-Tenant des Kunden, mit Administratorzustimmung, beschränkt auf das Postfach, aus dem dieser Standort senden soll. Schritt für Schritt steht das unter Entra ID einrichten.

Der Agent speichert alle Daten unter %ProgramData%\Letterhop\Relay\ unter Windows und unter /var/lib/letterhop/ auf anderen Betriebssystemen. Überschreiben Sie das mit LETTERHOP_DATA_DIR.

# 1. Die Zugangsdaten der App-Registrierung aus dem Tenant des Kunden speichern. Das
#    Secret wird von stdin gelesen, damit es weder in der Shell-Historie noch in der
#    Prozessliste auftaucht.
letterhop add-credential -name "Contoso tenant" -tenant <tenant-id> -client-id <client-id>

# 2. Ein Gerätelogin anlegen. Die Absenderadresse wird jeder Nachricht, die dieses
#    Login einliefert, fest zugeordnet - unabhängig davon, was das Gerät angibt.
letterhop add-account -username printer-2og -password <device-password> \
    -from scan@example.com -credential <credential-id>

# 3. Die Tenant-Seite prüfen, bevor Sie einen Drucker anfassen.
letterhop test-credential <credential-id>

# 4. Starten.
letterhop serve

test-credential meldet die Absenderadresse, die Graph tatsächlich auf eine Nachricht stempeln würde. Weicht sie von der konfigurierten Adresse ab - was bei einem Alias statt der primären Postfachadresse passiert -, wird das gemeldet. Prüfen Sie das, bevor Sie Geräte verkabeln, nicht danach.

letterhop status zeigt Instanz-Identität, Konten- und Zugangsdaten-Anzahl sowie den Warteschlangenstatus. letterhop list-credentials zeigt IDs und die Ergebnisse der letzten Prüfung.

Das wiederholen Sie pro Standort. Jeder Standort bekommt seinen eigenen Agenten, mit den Zugangsdaten aus dem Tenant seines eigenen Kunden.

Dasselbe aus dem Portal

Sobald ein Relay aufgenommen ist, lassen sich die Konten, Zugangsdaten und Verbindungen, die diese Befehle anlegen, auch im Portal anlegen, ändern und einsehen, ganz ohne Sitzung an der Maschine - was so beim Relay ankommt und was in jedem Fall lokal bleibt, steht unter Fernwartung.

Gerät konfigurieren

Aktualisiert am 2026-08-13

Richten Sie das Gerät auf die LAN-Adresse des Relays und einen der folgenden Ports:

Port	Transport	Standard
587	STARTTLS	aktiviert - diesen verwenden
465	implizites TLS	aktiviert - für Geräte, die nur SMTPS können
25	keine Verschlüsselung	deaktiviert - nur in einem vertrauenswürdigen LAN bewusst aktivieren

Verwenden Sie den lokalen Benutzernamen und das Passwort aus add-account als SMTP-Zugangsdaten. AUTH LOGIN und AUTH PLAIN werden beide angeboten; die meisten älteren Geräte benötigen LOGIN.

Das Relay erzeugt beim ersten Start ein selbstsigniertes Zertifikat, das seinen Hostnamen, seine LAN-Adressen und Loopback abdeckt. Geräte, die Zertifikate prüfen, benötigen dieses Zertifikat importiert, oder Sie hinterlegen Ihr eigenes.

Welche Absenderadresse auch immer am Gerät eingestellt ist, wird ignoriert. Stattdessen wird die Adresse des Kontos verwendet. Das ist Absicht: Ein falsch konfiguriertes oder kompromittiertes Gerät kann dadurch nicht als jemand anderes in der Domain des Kunden senden.

Zustellung

Aktualisiert am 2026-08-09

Das Relay antwortet erst dann mit 250 OK, wenn die Nachricht mit einem fsync auf der Festplatte liegt und ihr Warteschlangeneintrag committet ist. Ab diesem Moment darf das Gerät seine Kopie löschen, denn die Zustellung liegt jetzt in der Verantwortung des Relays.

Die Zustellung läuft danach im Hintergrund mit einem eskalierenden Wiederholungsplan. Eine Nachricht, die 24 Stunden lang fehlschlägt, wird aussortiert (Dead-Lettering) statt endlos weiterversucht, und ihr Inhalt bleibt 30 Tage erhalten, damit sie nach Behebung der Ursache erneut gesendet werden kann. Fehler werden mit dem Klartextgrund erfasst, nicht nur mit einem Statuscode.

Anhänge ab etwa 3 MB durchlaufen automatisch eine Upload-Session. Das Gerät bemerkt den Unterschied nicht.

Hinweise zur Sicherheit

• Gerätepasswörter und Provider-Secrets sind ruhend (at rest) geschützt. Secrets werden mit AES-256-GCM verschlüsselt; unter Windows wird der Schlüssel mit DPAPI auf Maschinenebene verpackt, und das Datenverzeichnis trägt eine ACL, die nur SYSTEM, Administratoren und dem Konto, das es erstellt hat, Zugriff gewährt.
• Das schützt nicht vor einem lokalen Administrator. Alles, was das Relay entschlüsseln kann, kann auch Code entschlüsseln, der als Administrator auf derselben Maschine läuft. Das liegt in der Natur eines Dienstes, der startet, ohne dass jemand eine Passphrase eintippt. Was es schützt, ist eine gestohlene Festplatte, eine kopierte Sicherung oder eine exfiltrierte Datenbankdatei.
• Wiederholte fehlgeschlagene Logins von einer Adresse werden gedrosselt. Geräte mit gespeichertem Passwort lösen das nie aus; ein Techniker, der ein Passwort ein paar Mal von Hand eintippt, könnte es auslösen und muss dann einige Minuten warten.
• Unverschlüsseltes SMTP auf Port 25 ist standardmäßig aus, und Authentifizierung wird auf jedem Listener verweigert, der nicht verschlüsselt ist, sofern Sie den Klartext-Listener nicht ausdrücklich aktivieren.

Benachrichtigungen und Testmail

Aktualisiert am 2026-09-28

Jedes eingerichtete Relay meldet sich alle 60 Sekunden bei der Plattform und berichtet seinen Zustand: die Länge der Warteschlange, das Alter der ältesten wartenden Nachricht, die Zahl aufeinanderfolgender Zustellfehler und den letzten Fehlercode. Die Plattform wertet das für jeden Kunden einmal pro Minute aus und entscheidet daraus, ob eine Meldung fällig ist.

Wann eine Meldung ausgelöst wird

Drei unabhängige Auslöser, mit Voreinstellungen, die Sie im Portal pro Mandant und zusätzlich pro Kunde überschreiben können:

• Kontaktverlust. Das Relay hat sich seit mindestens der eingestellten Zeit nicht mehr gemeldet (Standard 15 Minuten, einstellbar zwischen 5 Minuten und 24 Stunden). Ein Relay, das noch nie eine Meldung gesendet hat - etwa direkt nach der Einrichtung - gilt dabei nicht als stumm; sonst würde jede neue Installation sofort mit einer Ausfallmeldung begrüßt.
• Flattern. Innerhalb eines Zeitfensters (Standard 2 Stunden, 30 Minuten bis 24 Stunden) sind mehrere Kontaktverlust-Meldungen aufgelaufen (Standard 3, einstellbar zwischen 2 und 10). Das erfasst die Leitung, die immer nur kurz aussetzt - für den Endkunden macht sich das als "der Scanner geht manchmal einfach nicht" bemerkbar, ohne dass ein einzelner Aussetzer je die Schwelle für Kontaktverlust reißt.
• Zustellung schlägt fehl. Das Relay meldet mindestens so viele aufeinanderfolgende Zustellfehler wie eingestellt (Standard 3, einstellbar zwischen 1 und 20) und hat gleichzeitig noch etwas in der Warteschlange. Beide Bedingungen zusammen, denn ein Fehlerzähler allein würde schon bei einer einzigen falschen Adresse anschlagen, eine volle Warteschlange allein schon bei einer gewöhnlichen Lastspitze.

Eine Meldung geht genau zweimal heraus: einmal, wenn der Zustand eintritt, und einmal, wenn er sich wieder erledigt hat - nicht wiederholt, solange er anhält. Schalten Sie die Benachrichtigung für einen Kunden ab, während gerade etwas offen ist, bleibt es offen liegen, statt automatisch als erledigt zu gelten: Abschalten heißt "ich schaue gerade nicht hin", nicht "hier ist wieder alles in Ordnung".

Zusätzlich schreibt das Relay dieselben Ereignisse mit einer festen Nummer in das Windows-Ereignisprotokoll, damit ein RMM-Werkzeug eigene Regeln darauf aufbauen kann: unter anderem Konfiguration gesperrt/entsperrt, Zustellung fehlgeschlagen/wiederhergestellt und Testmail gesendet/fehlgeschlagen.

Wer die Meldung bekommt

Ohne eigene Einstellung gehen Meldungen an die Administratoren Ihres eigenen Mandanten in der Plattform - nicht an den Endkunden. Sie können stattdessen bis zu 20 eigene Adressen hinterlegen, für den ganzen Mandanten oder abweichend für einen einzelnen Kunden. Die Schwellenwerte und Empfänger ansehen kann jeder, der in der Plattform Zugriff auf den jeweiligen Kunden hat, auch ohne eigene Änderungsrechte; ändern darf sie nur, wer dafür freigeschaltet ist.

Die Kontaktperson beim Endkunden

Getrennt von den Meldungen an Ihren eigenen Mandanten kennt das Relay eine eigene, lokal auf dem Gerät hinterlegte Kontaktadresse beim Endkunden. Sie hört nichts von einem Zustellproblem - dafür ist die Meldung oben da -, sondern ausschließlich davon, wenn dieses Relay den Kontakt zur Plattform länger verliert und seine Konfiguration deshalb zu sperren droht oder bereits gesperrt ist. Die Warnung läuft über den normalen Postausgang des Kunden, über das Konto, das Sie dafür beim Einrichten benennen: täglich ab zwei Wochen vor der Sperre, einmal am Tag der Sperre selbst, danach wöchentlich, solange die Sperre anhält. Ist keine Kontaktadresse hinterlegt, bleibt diese Warnung schlicht aus; die Zustellung ist davon nicht betroffen.

Was die Testmail beweist

Die Testmail sendet direkt über das eingerichtete Postfach, ohne die Warteschlange zu durchlaufen - ein Erfolg beweist also, dass das Konto in diesem Moment wirklich senden kann, nicht nur, dass die Einrichtung gespeichert wurde. Ein Fehler entsteht aus demselben Grund, aus dem auch echte Post fehlschlagen würde: falsches Secret, fehlende Berechtigung, abgelehntes Postfach.

Es gibt zwei Wege dahin, mit unterschiedlicher Offenheit:

• An der Maschine selbst, über die eigene Oberfläche des Relays: freier Empfänger, Betreff, CC und BCC, und im Fehlerfall die Meldung des Anbieters im Original.
• Aus dem Portal, über eine Fernwartungsanweisung: nur der Empfänger ist frei wählbar (und, falls das Relay mehrere aktive Konten hat, welches Konto gemeint ist); Betreff und Text sind fest vorgegeben und nennen Standort, Kunde und Zeitpunkt, nie frei eintippbar - sonst wäre der Knopf ein Mail-Client, der aus dem Postfach eines Kunden heraus alles Beliebige verschicken könnte. Ein Fehler wird hier nie im genauen Wortlaut des Anbieters gemeldet, sondern immer als eine feste, für Menschen geschriebene Meldung; hat der Anbieter selbst geantwortet, ist das eine von sechs Klassen (Authentifizierung, Berechtigung, Drosselung, Netzwerk, Postfach, sonstiges). Die Testmail aus dem Portal ist auf 10 pro Stunde und Standort begrenzt.

Wenn die Zustellung dauerhaft fehlschlägt

Am Verhalten des Relays selbst ändert eine Meldung nichts: Eine Nachricht wird weiter mit eskalierenden Abständen erneut versucht, bis sie entweder ankommt oder 24 Stunden lang fehlgeschlagen ist. Was danach passiert und wie lange der Inhalt für einen erneuten Versand erhalten bleibt, steht in Zustellung. Die Meldung ist die Benachrichtigung darüber - sie verhindert das Aussortieren nicht und beschleunigt es nicht.

Fernwartung über das Portal

Aktualisiert am 2026-09-28

Die Plattform hält zu jedem Relay eine laufend aktuelle Kopie seiner Konfiguration. Eine Änderung, die Sie im Portal vornehmen, wird als Anweisung an genau dieses Relay geschickt und erst dort ausgeführt - mit derselben Prüfung, derselben Sperre bei abgelaufener Lizenz und demselben Eintrag im Protokoll, den auch eine Änderung an der Maschine selbst bekäme. Ein neues Passwort oder Secret wird schon im Browser mit dem öffentlichen Schlüssel genau dieses Relays verschlüsselt; die Plattform leitet nur das verschlüsselte Paket weiter und kann es selbst nicht lesen. Über eine ständig offene Verbindung erreicht eine Anweisung das Relay in der Regel innerhalb weniger Sekunden; steht diese Verbindung gerade nicht, holt sie das Relay spätestens mit seiner nächsten Statusmeldung nach, höchstens 60 Sekunden später. Die Konfiguration einsehen kann im Portal jeder mit Zugriff auf den jeweiligen Kunden; ändern kann sie nur, wer dafür eigens freigeschaltet ist.

Was aus dem Portal geht, und was an der Maschine bleibt

Aus dem Portal erreichen Sie fast alles, was auch die eigene Oberfläche des Relays anbietet: Konten anlegen, Passwort setzen, aktiv schalten oder löschen, Zustellregeln, Verbindungen, Listener, Zertifikat, die Kontaktperson beim Endkunden, Benutzer, sowie die Warteschlange einsehen und erneut versuchen lassen. Microsoft-365-Verbindungen lassen sich auf diesem Weg vollständig aus der Ferne einrichten: entweder mit einer eigenen App-Registrierung wie jede andere Verbindung, oder per Zustimmung, bei dem ein Kunde selbst einmal zustimmt - Letzteres ist ein eigenes Thema, siehe Microsoft 365 verbinden. Gmail wird noch nicht unterstützt, weder an der Maschine noch aus dem Portal - siehe den Überblick.

Eine Sache bleibt an der Maschine:

• Ein einmal angelegtes Konto lässt sich in keinem der beiden Wege nachträglich bearbeiten, außer im Passwort, ob es aktiv ist, und seinen Zustellregeln. Für alles andere - etwa das Postfach oder die Absenderadresse - gibt es weder lokal noch im Portal ein Bearbeiten; einzige Möglichkeit ist, das Konto zu löschen und neu anzulegen.

Ein Relay, das gerade erst ausgeliefert wurde oder einem Anbieterwechsel unterzogen wird, übernimmt jemand am Gerät selbst, mit dem Einmalcode aus der Einrichtung - das Portal kann kein noch unbeanspruchtes Relay aus der Ferne in Besitz nehmen.

Benutzer und ihre beiden Rollen

Das Relay kennt eigene, namentliche Zugänge zu seiner Oberfläche - unabhängig vom Zugang zum Portal selbst. Jeder Benutzer hat eine von zwei Rollen:

• admin darf alles ändern, was diese Seite beschreibt, und zusätzlich Benutzer anlegen, ihre Rolle ändern, ihr Passwort zurücksetzen und sie löschen.
• reader sieht die meisten Seiten, die ein admin auch sieht, einschließlich der Warteschlange - nicht aber die Benutzerverwaltung und nicht den Download der Konfiguration. Ändern kann reader nur das eigene Passwort; jede andere schreibende Aktion an dieser Anmeldung wird abgelehnt.

Der letzte verbliebene Administrator kann weder gelöscht noch zu reader herabgestuft werden; ein Relay soll nie ganz ohne Administrator dastehen. Die einzige Ausnahme ist die Übernahme eines Relays mit einem Einmalcode: dabei werden alle bisherigen Benutzer ersetzt, damit der Zugriff eines vorherigen Betreuers nicht automatisch erhalten bleibt. Ein über das Portal angelegter Benutzer trägt das entsprechend vermerkt, sodass an der Maschine nachvollziehbar bleibt, dass der Zugang von dort kam.

Die Live-Warteschlange

Sowohl an der Maschine als auch im Portal sehen Sie, was das Relay gerade angenommen und noch nicht zugestellt hat. Was das Portal dabei zeigt, ist bewusst schmaler als das, was an der Maschine zu sehen ist: eine Kennung, wie alt der Eintrag ist, wie oft er schon versucht wurde, wann der nächste Versuch fällig ist, sein Status, eine von sechs Fehlerklassen und ob ein erneuter Versuch überhaupt Sinn hätte - nie an wen die Nachricht geht, von wem, welchen Betreff sie trägt oder wie groß sie ist. Das Portal zeigt höchstens 50 Einträge auf einmal, mit der Gesamtzahl daneben; eine größere Warteschlange sehen Sie in Teilen. An der Maschine selbst zeigt dieselbe Ansicht zusätzlich Empfänger und Betreff, denn wer dort angemeldet ist, sitzt bereits im Netz des Kunden. Ein erneuter Versuch - einzeln oder für alles auf einmal - wird in beiden Fällen mit dem Namen des Benutzers protokolliert, der ihn ausgelöst hat.

Konfiguration exportieren und importieren

Ein Export ist eine JSON-Datei mit dem gesamten Aufbau des Relays: Konten, Verbindungen, Listener, Zertifikate, die Kontaktperson und Benutzer. Er lässt sich an der Maschine herunterladen oder im Portal aus der dort bereits vorliegenden, laufend aktualisierten Kopie erzeugen - eine eigene Anweisung an das Relay braucht es dafür nicht. An der Maschine steht der Download nur der Rolle admin offen; im Portal sieht ihn, wer ohnehin auf die Konfiguration dieses Kunden zugreifen darf.

Was ein Export nie enthält: das Passwort eines Kontos, das Secret einer Verbindung (Client-Secret, SMTP-Passwort oder privater Schlüssel), den privaten Schlüssel oder das PEM eines Zertifikats, und das Passwort eines Benutzers. Für jedes davon steht nur, ob überhaupt eines gesetzt ist, nie welches.

Einen Import können Sie ebenfalls an beiden Stellen anstoßen: die Datei an der Maschine hochladen, oder sie im Portal hochladen, von wo sie als Anweisung an das Relay geht - praktisch gerade dann, wenn ein Relay per Fernwartung neu aufgesetzt werden soll, ohne dass jemand vor Ort sein muss. Ein Import ist nur für ein Relay gedacht, das noch kein einziges Konto und keine einzige Verbindung hat - eine Neueinrichtung oder ein Gerätetausch, nie eine Zusammenführung mit bestehenden Daten; ein Relay mit vorhandenen Konten lehnt ihn ab. Konten kommen zunächst deaktiviert und ohne ihr Passwort zurück, Verbindungen ohne ihr Secret; beides muss einmal neu gesetzt werden, bevor wieder etwas gesendet werden kann. Benutzer, deren Name auf dem Relay schon existiert - typischerweise der Benutzer, der den Import gerade ausführt - werden dabei übersprungen und bleiben mit ihrem echten Passwort unverändert, damit niemand sich durch den eigenen Import aussperrt. Die Datei ist auf 500 Konten und 500 Benutzer begrenzt, und alles wird in einem einzigen Schritt geschrieben: entweder vollständig, oder gar nicht.

Microsoft 365 verbinden

Aktualisiert am 2026-09-28

Für eine Verbindung nach Entra ID einrichten registriert jemand eine eigene Anwendung im Tenant des Kunden. Diese Seite beschreibt den zweiten Weg: Ein Techniker mit der Berechtigung relay.configure startet im Portal eine Microsoft-365-Verbindung für einen Standort und schickt dem Administrator des Kunden einen Link. Der Standort braucht dafür kein Relay am Netz - das Relay kann zu diesem Zeitpunkt noch offline sein. Der Administrator öffnet den Link, meldet sich bei Microsoft an und stimmt einmal zu. Die Anwendung, der dabei zugestimmt wird, ist nicht die des Kunden und nicht die des Systemhauses, sondern eine einzige, von Letterhop selbst betriebene Anwendung je Weg - dieselbe für jeden Kunden, der diesen Weg wählt, unterschieden nur durch den Tenant, der zugestimmt hat. Danach hält die Plattform selbst den Schlüssel dieser Anwendung, und reicht dem Relay laufend kurzlebige Zugangstoken durch. Am Standort landet weder ein Client-Secret noch ein Passwort.

Zwei Wege, eine Wahl pro Verbindung

Der Techniker wählt im Portal zwischen zwei Wegen, bevor der Link überhaupt entsteht:

• Ein Klick, tenantweit. Die Anwendung ist in Entra mit den Anwendungsberechtigungen Mail.Send und Mail.ReadWrite registriert. Der Administrator stimmt einmal zu, danach kann das Relay als jedes Postfach dieses Tenants senden sowie Nachrichten lesen, schreiben und löschen. Es gibt keine Wartezeit.
• Pro Postfach, über Exchange. Eine zweite, eigenständige Anwendung, die in Entra keine einzige Anwendungsberechtigung trägt. Die Zustimmung dafür überträgt praktisch keine Rechte; die eigentliche Freigabe erteilt der Administrator anschließend selbst in Exchange Online, für eine benannte Gruppe von Postfächern, über RBAC for Applications (New-ServicePrincipal, New-ManagementScope, New-ManagementRoleAssignment). Dafür gibt es bei Microsoft weder eine Oberfläche noch einen Weg, es aus dem Portal anzustoßen. Dieser Weg ist bislang auf keinem echten Microsoft-365-Tenant erprobt; sollte er sich nicht bewähren, deklariert die Anwendung stattdessen doch Mail.Send und Mail.ReadWrite, freigegeben über die ältere Application Access Policy statt über RBAC.

Eine einzelne Anwendung kann nicht beides zugleich anbieten. Eine in Entra erteilte Berechtigung und eine in Exchange erteilte Freigabe werden von Microsoft vereinigt, nicht geschnitten: Sobald eine Anwendung tenantweit Mail.ReadWrite trägt, hebt das jede engere Freigabe in Exchange faktisch auf. Deshalb sind es zwei getrennte Anwendungen mit zwei getrennten Links, nicht eine mit einer Option.

Was die Zustimmung tatsächlich anfragt

Auf dem Zustimmungsbildschirm sieht der Administrator, was die jeweilige Anwendung in Entra hinterlegt hat:

• Bei der tenantweiten Anwendung sind das Mail.Send und Mail.ReadWrite, beide als Anwendungsberechtigung - also ohne dass eine Person angemeldet sein muss. Mail.Send erlaubt das Versenden als jedes Postfach im Tenant. Mail.ReadWrite erlaubt zusätzlich, in jedem Postfach Nachrichten zu lesen, zu schreiben und zu löschen; benötigt wird es, weil sowohl der Verbindungstest als auch jeder Anhang oberhalb der Upload-Schwelle intern einen Entwurf anlegt, und das Anlegen eines Entwurfs Mail.ReadWrite verlangt, nicht Mail.Send allein. Mehr als diese beiden Berechtigungen fragt Letterhop nicht an - kein Zugriff auf Kalender, Kontakte, Dateien oder irgendetwas außerhalb von Mail. Keine der beiden Berechtigungen gibt Zugriff auf das Verzeichnis: Es wird nirgends nach User.Read.All gefragt, und über diese Verbindung lässt sich keine Liste der Postfächer des Tenants abrufen.
• Bei der Anwendung für den Weg pro Postfach steht auf dem Bildschirm nichts von alledem, weil die Anwendung keine einzige Anwendungsberechtigung deklariert. Was sie darf, entscheidet ausschließlich die Freigabe, die der Administrator danach in Exchange erteilt.

Weil die tenantweite Berechtigung wörtlich für den ganzen Tenant gilt, ist sie das, was an anderer Stelle dieser Dokumentation als größter Konfigurationsfehler genannt wird, wenn sie unbeschränkt vergeben wird. Für eine einzelne, benannte Adresse ist deshalb der zweite Weg die engere Wahl, auch wenn er mehr Aufwand macht.

Der Herausgeber ist noch nicht verifiziert. Beide Anwendungen laufen bislang ohne Microsoft-Herausgeberverifizierung. Der Zustimmungsbildschirm zeigt sie deshalb als Anwendung eines nicht verifizierten Herausgebers, und manche Tenants blockieren solche Anwendungen von sich aus per Richtlinie. Bricht die Zustimmung deshalb ab, meldet Microsoft das über denselben Rückweg, und das Portal zeigt dem Techniker Microsofts eigene Meldung im Wortlaut.

Ein Postfach wird eingetippt und bewiesen, nicht aus einer Liste gewählt

Es gibt keinen Schritt, der die Postfächer eines Tenants auflistet. Eine solche Liste bräuchte User.Read.All auf dem Zustimmungsbildschirm jedes Kunden und würde ohnehin nicht zeigen, was die Anwendung wirklich senden darf, weil das bei diesem Weg über Exchange und nicht über das Verzeichnis entschieden wird. Stattdessen tippt jemand die Adresse ein, für die dieser Standort senden soll, und das Relay beweist sie mit demselben Test, den auch die eigene App-Registrierung verwendet: Es legt in diesem Postfach einen Entwurf an, liest die Adresse zurück, die Graph dafür tatsächlich einsetzt, und löscht den Entwurf wieder. Drei Ausgänge sind möglich: die Adresse ist erlaubt, mit der von Graph aufgelösten Adresse; sie ist nicht erlaubt, mit Microsofts eigener Fehlermeldung; oder sie lässt sich gerade nicht beurteilen, siehe unten.

Die Freigabe in Exchange kann bis zu zwei Stunden brauchen

Beim Weg über Exchange hält Exchange Online eine neu erteilte Freigabe bis zu zwei Stunden lang in einem Zwischenspeicher, bevor sie überall wirkt. Ein Verbindungstest direkt nach der PowerShell-Freigabe kann deshalb ablehnen, obwohl die Einrichtung korrekt ist. Das Relay unterscheidet diesen Fall von einer echten Ablehnung: Kommt bei einer per Exchange freigegebenen Verbindung ein 403 zurück, meldet es „noch nicht wirksam" statt eines endgültigen Fehlers, und nennt Test-ServicePrincipalAuthorization, das denselben Zwischenspeicher umgeht und sofort sagt, welcher der beiden Fälle vorliegt. Bei der tenantweiten Verbindung gibt es diese Wartezeit nicht, und ein 403 dort ist eine echte Ablehnung.

Wer den Anwendungsschlüssel hält

Für beide Wege hält ausschließlich die Plattform den Schlüssel der jeweiligen Anwendung, nie das Relay. Das Relay speichert für diese Verbindung nur die Tenant-ID des Kunden und welcher der beiden Wege gewählt wurde, kein Secret. Aus ihrem eigenen Schlüssel erzeugt die Plattform bei Bedarf ein kurzlebiges Zugangstoken für genau diesen Tenant und reicht es über dieselbe laufend offene Verbindung durch, über die das Relay auch seine Statusmeldungen sendet; ein Token selbst landet dabei nie in der Datenbank des Relays und nie in dessen Protokoll. Das ist eine Verarbeitungstatsache, die vor der Zustimmung feststehen sollte: Bei dieser Verbindungsart ist die Plattform nicht mehr bloß ein Übermittler verschlüsselter Pakete - sie stellt selbst die Berechtigung aus, mit der als der Mandant des Kunden gesendet wird.

Ein neues Token holt sich das Relay, sobald seinem aktuellen weniger als 30 Minuten Gültigkeit bleiben; solange die Plattform erreichbar ist, hält das Relay dadurch immer einen Puffer von mindestens 30 Minuten. Ein Ausfall der Plattform, der kürzer ist, bleibt am Standort deshalb unsichtbar. Ein längerer Ausfall pausiert die Zustellung nur für diese Verbindungsart: Mail sammelt sich in der Warteschlange des Relays und wird zugestellt, sobald wieder Token ankommen. Nichts geht verloren und nichts wird abgewiesen - Verbindungen mit eigener App-Registrierung oder mit SMTP sind davon nicht betroffen und liefern auch dann durchgehend weiter, wenn die Plattform ganz ausfällt.

Wird die Zustimmung beim Kunden widerrufen, bemerkt die Plattform das beim nächsten Versuch, ein Token zu holen. Zu beachten: Ein Widerruf allein in der Übersicht der Unternehmensanwendungen in Entra löscht keine bereits erteilte Freigabe in Exchange. Wer den Zugriff wirklich vollständig entfernen will, muss die Unternehmensanwendung selbst löschen - das nimmt die zugehörige Exchange-Freigabe automatisch mit.

Lese-API

Aktualisiert am 2026-09-28

Ein Endpunkt: GET /api/v1/msp/platform-health. Er beantwortet nicht den Zustand eines Kunden oder Standorts, sondern den der Plattform selbst - Datenbank-Pool, offene Wartepositionen laufender Anfragen und die Befehlsverbindung. Gedacht für das eigene Monitoring eines Systemhauses, das die Plattform regelmäßig abfragt, nicht für ein Dashboard, das ein Endkunde sieht.

Zugang

Der Aufruf braucht einen API-Schlüssel im Authorization-Header als Bearer-Token. Anders als jeder andere schlüsselgeschützte Endpunkt dieser Plattform schränkt platform-health sich nicht auf den Mandanten des Schlüssels ein: Ein gültiger Schlüssel irgendeines Mandanten genügt, weil die Antwort ohnehin nichts über einen einzelnen Kunden aussagt, sondern über die Plattform als Ganzes. Ein Schlüssel eines gesperrten oder gekündigten Mandanten wird trotzdem abgelehnt (403), ein unbekannter oder falscher mit 401, und ein Schlüssel ist auf 60 Aufrufe pro Minute begrenzt.

Einen Schlüssel legt ein Administrator Ihres Mandanten im Portal unter Integrationen an - nicht ein Techniker mit einzelnen Berechtigungen, sondern jemand mit vollem administrativem Zugriff, aus demselben Grund, aus dem auch ein Webhook-Ziel dort liegt: Beides sind Zugangsdaten. Der volle Schlüssel wird genau einmal angezeigt, direkt bei der Erstellung; danach zeigt das Portal nur noch Name, ein Präfix sowie Erstellungs- und letztes Nutzungsdatum, nie den Schlüssel selbst erneut.

Was die Antwort enthält

{
  "status": "ok",
  "live_waits": 3,
  "pool": {
    "acquired_conns": 4,
    "idle_conns": 6,
    "empty_acquire_count": 0
  },
  "hub_reconnects": 12
}

• status steht immer auf "ok", sobald die Anfrage überhaupt beantwortet wird - der Endpunkt kennt keinen anderen Wert.
• live_waits ist die Zahl der Anfragen, die die Plattform gerade offen hält, weil ein Relay über die ständig offene Verbindung auf eine Anweisung wartet.
• pool sind drei Kennzahlen des Datenbank-Verbindungspools: belegte Verbindungen, freie Verbindungen, und wie oft ein Aufruf auf eine freie Verbindung warten musste, weil der Pool gerade leer war. Das Feld fehlt vollständig, wenn die verwendete Datenbankanbindung diese Kennzahlen nicht liefert.
• hub_reconnects zählt, wie oft sich die Befehlsverbindung insgesamt neu aufbauen musste. Das Feld fehlt, wenn diese Verbindung nicht konfiguriert ist.

Kein Feld nennt einen Mandanten, einen Kunden oder einen Standort - das ist Absicht, nicht Auslassung: Für den Zustand einzelner Standorte gibt es die eigenen, mandantengebundenen Endpunkte dieser API (/api/v1/msp/sites, /api/v1/msp/incidents), die denselben Schlüssel verlangen, aber ausschließlich die Daten des eigenen Mandanten liefern.

Warum /readyz nichts davon zeigt

/readyz ist unauthentifiziert und aus dem Internet erreichbar - gedacht für einen Container-Orchestrator, der nur wissen muss, ob die Instanz gerade Anfragen bedienen kann, nicht für ein Systemhaus. Er prüft die Datenbankverbindung mit einem Timeout von zwei Sekunden und antwortet ausschließlich mit {"status":"ok"}, {"status":"database unavailable"} oder {"status":"no database configured"} - nie mit den Kennzahlen oben. Die trugen /readyz früher tatsächlich einmal; sie sind hinter die Schlüsselprüfung von platform-health gewandert, weil Kapazitäts- und Lastzahlen einer ganzen Flotte von Relays nichts sind, was ein unauthentifizierter Aufruf aus dem Internet sehen sollte.

/healthz daneben prüft noch weniger: Er antwortet, solange der Prozess überhaupt läuft, ohne die Datenbank anzufassen.