E-Mails mit der Microsoft Graph API

Die Microsoft Graph API bietet eine moderne und sichere Möglichkeit, E-Mails direkt aus Microsoft 365-Postfächern zu empfangen und zu versenden.
Im Gegensatz zu den klassischen Protokollen POP3, IMAP und SMTP erfolgt der Zugriff über eine REST-basierte Schnittstelle, die speziell für Cloud-Anwendungen optimiert ist.
Dadurch lassen sich Postfächer gezielt ansprechen, mehrere Benutzer gleichzeitig verwalten und Delta-basierte Synchronisationen realisieren.

Schemaobjekte

In Syncler stehen für den Zugriff auf Microsoft 365-Postfächer über die Graph API zwei Schemaobjekte zur Verfügung:

Empfangen von E-Mails

Grundlagen

Die Basis für den Abruf von E-Mails ist immer ein Benutzerkonto bzw. dessen Postfach.
Welche Postfächer verfügbar sind, wird im zugehörigen Microsoft 365-Konnektor festgelegt.
Der Konnektor bietet verschiedene Verfahren zur Auswahl der Benutzer:

• Filterbasierte Auswahl (z. B. alle Mitglieder einer bestimmten Gruppe)
• Manuelle Benutzerliste
• Benutzerauswahl über Gruppe oder Zustimmung

Weitere Informationen finden Sie unter: Microsoft 365 Konnektor

Postfach- und Benutzerfilter

Standardmäßig durchsucht der Konnektor alle festgelegten Benutzerpostfächer.
Das kann beim Abrufen von E-Mails über eine eindeutige ID zu längeren Antwortzeiten führen, da die ID in jedem Postfach geprüft wird.

Zur gezielten Eingrenzung kann der Filterparameter user verwendet werden.
Damit wird ein konkretes Postfach angegeben – auch unabhängig von der im Konnektor hinterlegten Benutzerliste.

Beispiel:

user|:|my-user@example.com|;|

Dieser Parameter ist besonders hilfreich, um gezielte E-Mail-Abfragen oder Teilprozesse (z. B. pro Benutzer) zu realisieren.

Ordnerstruktur und Verzeichnisse

Das Standardverzeichnis für den E-Mail-Abruf ist der Posteingang (Inbox).
Über das Schemaobjekt mailFolder können alle vorhandenen Ordner des Postfachs abgefragt werden.
Jeder Ordner verfügt über eine eindeutige ID, die beim Abruf von E-Mails als Filterparameter verwendet werden kann.

Beispiel:

mailfolderid|:|<Ordner-ID>|;|

Damit kann der Abruf gezielt auf ein bestimmtes Verzeichnis, z. B. „Gesendet“, „Archiv“ oder „Benutzerdefinierte Ordner“, eingeschränkt werden.

Verwendung im Universal Sync

Für die Verarbeitung eingehender Nachrichten steht der Sync-Typ „Universal Sync für Microsoft Nachrichten“ zur Verfügung.
Dieser Sync bietet spezielle Parameter für die Auswahl und Nachbearbeitung:

Wenn Postfach und Verzeichnis angegeben sind, kann die Graph API die Delta-Überwachung (Delta Query) aktivieren.
Damit werden nur neue oder geänderte Nachrichten seit dem letzten Sync abgerufen.

Ohne Angabe von Postfach und Verzeichnis liest der Sync alle E-Mails, wodurch doppelte Verarbeitungen vermieden werden müssen – z. B. durch Lösch- oder Verschiebeaktionen nach erfolgreicher Verarbeitung.

Verarbeitung von Anhängen

Anhänge werden im Standard-Mail-Sync nicht direkt verarbeitet.
Hierfür stehen spezielle Folge-Syncs zur Verfügung, z. B.:

• Microsoft Nachrichten-Anhänge nach Sage CRM Dokument

Für eine vollständige E-Mail-Ablage empfiehlt sich die Kombination aus E-Mail- und Anhangs-Sync in einem Ablauf (Flow).

Der eigentliche Dateiinhalt eines Anhangs steht im Feld contentBytes als Base64-kodierter Wert zur Verfügung.
Eine vollständige EML-Datei (inklusive MIME-Struktur) wird über die Graph API derzeit nicht bereitgestellt.

Versand von E-Mails

E-Mails können über das Schemaobjekt message auch versendet, weitergeleitet oder bearbeitet werden.
Die Konfiguration erfolgt in der Regel über einen Universal Sync mit Schreiboperation.

Steuerungsfelder

Zur Steuerung des Verhaltens stehen zwei boolesche Felder zur Verfügung:

Zusätzlich muss im Feld user das Postfach angegeben werden, über das der Versand erfolgen soll.

Beispiel:

{
  "user": "my-user@example.com",
  "subject": "Testmail über Microsoft Graph API",
  "body": {
    "contentType": "HTML",
    "content": "<p>Hallo Welt!</p>"
  },
  "toRecipients": [
    {
      "emailAddress": {
        "address": "empfaenger@example.com"
      }
    }
  ],
  "send": true
}

Hinweis:
Eine Weiterleitung (forward = true) erfordert, dass die Nachricht im selben Benutzerpostfach vorhanden ist.
Es ist nicht möglich, eine E-Mail mit einem abweichenden Postfach weiterzuleiten.

Best Practices

• Verwenden Sie den user-Filter, um gezielt einzelne Postfächer anzusprechen.
• Nutzen Sie die Delta-Abfrage, um nur neue oder geänderte Nachrichten abzurufen.
• Kombinieren Sie E-Mail- und Anhangs-Syncs, um vollständige Ablagen zu realisieren.
• Verwenden Sie den Universal Sync für Microsoft Nachrichten für eingehende E-Mails und den Universal Sync für den Versand.
• Aktivieren Sie Nachbearbeitungsaktionen (z. B. Verschieben oder Löschen), um doppelte Verarbeitung zu vermeiden.

Zusammenfassung

• Die Graph API bietet einen modernen Ersatz für klassische E-Mail-Protokolle.
• Mit den Objekten message und mailFolder lassen sich Nachrichten und Ordner präzise verwalten.
• Über Delta Queries werden nur Änderungen abgerufen, was Ressourcen spart.
• Der Versand erfolgt direkt über das definierte Benutzerpostfach.
• Für Anhänge steht das Feld contentBytes zur Verfügung.
• Eine vollständige E-Mail-Verwaltung gelingt durch die Kombination spezialisierter Syncs in einem automatisierten Ablauf.