Outlook (Microsoft 365)
Agenten mit eingehenden E-Mails in einem Microsoft-365-Postfach starten und ihre Antworten oder Benachrichtigungen von dort versenden, über deine eigene Entra-ID-App.
Auf dieser Seite
| Modi | Inbound, Outbound |
| YAML-Typ | outlook |
| Zugangsdaten | Ein Kontozugang (Connection) vom Typ outlook mit Tenant-ID, Client-ID und Clientgeheimnis deiner eigenen Entra-ID-App. |
| Postfächer | Geschäfts- und Schulpostfächer in Microsoft 365. Outlook.com-Konten werden nicht unterstützt. |
| Bridge | Nicht unterstützt |
| Custom Domain | Nicht unterstützt |
| Verknüpfte Agenten | Einer oder mehrere. Jede E-Mail startet alle verknüpften Agenten. |
| Während der Pause | Inbound prüft den Ordner nicht mehr. E-Mails, die in der Zeit ankommen, werden nach Resume verarbeitet. Outbound sendet nichts. |
Einrichtung
Registriere die Entra-ID-App mit den Anwendungsberechtigungen
Mail.ReadWriteundMail.Sendsamt Administratorzustimmung und erstelle ein Clientgeheimnis. Soll die App keine anderen Postfächer erreichen, beschränke sie auf bestimmte Postfächer.Öffne den Agenten. Klicke im Connector Flow für Inbound auf Add inbound connector oder für Outbound auf Add outbound connector. Klicke dann auf Create New Connector und wähle Outlook (Microsoft 365).
Wähle den Modus. Wähle unter Connection einen gespeicherten Kontozugang oder lege einen mit Tenant-ID, Client-ID und Clientgeheimnis der App an.
Gib die Mailbox ein. Lege für Inbound den Folder und Mark as Read fest. Gib für Outbound optional Default Recipients ein.
Klicke auf Create. Eine Inbound-Verbindung beginnt dann, den Ordner zu prüfen. Bei Outbound legst du fest, wie der Agent die Verbindung nutzt, und klickst auf Link connector.
Im Code
Deklariere die Verbindung in connectors/*.yaml. connection nennt den Kontozugang mit den Zugangsdaten der App.
type: outlook
mode: inbound
connection: contoso-m365 # Kontozugang mit der Entra-ID-App
config:
mailbox: support@contoso.com
folder: Inbox
agents:
- support-triagetype: outlook
mode: outbound
connection: contoso-m365
config:
mailbox: support@contoso.com
agents:
- name: support-triage
outbound: { usage: automatic }Konfiguration
Die Felder einer Outlook-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Die Beschreibungen nennen die passende Einstellung im Dashboard. Verbindungen im Code beschreibt die Felder, die alle Verbindungen gemeinsam haben, etwa agents und environments.
| Feld | Typ | Status | Beschreibung |
|---|---|---|---|
| type | string | Required | outlook. |
| mode | string | Required | inbound oder outbound. Dashboard: Mode. |
| connection | string | Required | Name oder ID eines Kontozugangs vom Typ outlook. Siehe Entra-ID-App. Dashboard: Connection. |
| config | object | Required | Einstellungen der Outlook-Verbindung. |
| mailbox | string | Required | Der Benutzerprinzipalname des Postfachs, das die E-Mails empfängt oder versendet, etwa support@contoso.com. Ein freigegebenes Postfach geht auch. Dashboard: Mailbox. |
| folder | string | Optional | Inbound. Der zu prüfende Ordner: Inbox, Archive, ein anderer Ordner der obersten Ebene mit seinem Namen oder ein Unterordner als Pfad wie Inbox/Support. Dashboard: Folder.Default: Inbox |
| mark_as_read | boolean | Optional | Inbound. Eine E-Mail als gelesen markieren, sobald alle verknüpften Agenten sie erhalten haben. Dashboard: Mark as Read.Default: true |
| default_to | string | Optional | Outbound. Empfänger einer E-Mail, die weder to setzt noch auf eine eingehende Outlook-E-Mail antwortet: eine Adresse oder mehrere durch Kommas getrennte Adressen. Dashboard: Default Recipients. |
Agent-Input
Modi: Inbound
Eine Inbound-Verbindung prüft den Ordner über Microsoft Graph und startet mit jeder neuen E-Mail einen Run für jeden verknüpften Agenten. Sie beginnt mit den E-Mails, die nach ihrer ersten Prüfung ankommen; was schon im Ordner liegt, verarbeitet sie nicht. connic merkt sich, wie weit es gekommen ist, und verarbeitet keine E-Mail zweimal, auch wenn Mark as Read aus ist. Ein anderes Postfach oder ein anderer Ordner beginnt ab diesem Zeitpunkt neu. Der Run erhält die E-Mail im selben Format wie bei der E-Mail-Verbindung, sodass ein Agent Input aus beiden verarbeiten kann:
{
"subject": "Hilfe zu Bestellung #12345",
"from": "Jana Schmidt <jana@example.com>",
"from_address": "jana@example.com",
"to": "Contoso Support <support@contoso.com>",
"date": "Mon, 12 Oct 2026 08:30:00 +0000",
"message_id": "<AM0PR01MB1234.eurprd01.prod.outlook.com>",
"body_text": "Hallo, meine Bestellung ist noch nicht angekommen...",
"body_html": "<html><body><p>Hallo, meine Bestellung ist noch nicht angekommen...</p></body></html>",
"has_attachments": true,
"attachments": [
{
"filename": "beleg.pdf",
"content_type": "application/pdf",
"size_bytes": 45678,
"content": "JVBERi0xLjQK...",
"encoding": "base64"
}
],
"_outlook": {
"connector_id": "550e8400-e29b-41d4-a716-446655440000",
"mailbox": "support@contoso.com",
"folder": "Inbox",
"message_id": "AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0A...",
"timestamp": "2026-10-12T08:30:05.123456"
}
}fromundtonennen Name und Adresse;from_addressist die reine Absenderadresse.dateist der Zeitpunkt, zu dem das Postfach die E-Mail empfangen hat, in UTC.message_idist der HeaderMessage-IDder E-Mail.body_textundbody_htmlsind der Text als Klartext und als HTML. Microsoft 365 wandelt zwischen beiden um, deshalb sind immer beide gefüllt._outlooknennt die Verbindung, das Postfach, den Ordner und die Microsoft-Graph-ID der E-Mail, die gleich bleibt, wenn die E-Mail in einen anderen Ordner verschoben wird.
Anhänge
Für Anhänge gelten die Regeln der E-Mail-Verbindung: dieselben übernommenen Typen, dieselben übersprungenen Tracking-Bilder und eingebetteten Bilder unter 50 KB und dieselbe Kodierung. Text-, JSON- und XML-Dateien enthalten ihren Inhalt als Text ("encoding": "text"), alle anderen Dateien Base64-kodiert ("encoding": "base64").
Eine E-Mail nimmt bis zu 50 Anhänge auf, höchstens 32 MiB zusammen. Beim ersten Anhang über einem Limit behält connic die Anhänge davor und lässt diesen und alle folgenden aus. Dateien anderer Typen werden ebenfalls ausgelassen, ebenso angehängte Outlook-Elemente wie eine weitergeleitete E-Mail oder eine Termineinladung und Links auf Dateien in der Cloud. Ein ausgelassener Anhang hat "content": null und ein file_issue, und die Payload führt alle Auslassungen unter file_issues auf:
{
"filename": "archiv.rar",
"content_type": "application/vnd.rar",
"size_bytes": 20480,
"content": null,
"content_omitted": true,
"file_issue": {
"code": "unsupported_file_type",
"message": "File type is not supported.",
"retryable": false,
"name": "archiv.rar",
"size_bytes": 20480
}
}Der Agent erhält die E-Mail auch dann, wenn kein Anhang übernommen wurde. Aktivierst du im Detailbereich der Verbindung Files required für einen Agenten oder setzt files_required: true an seiner Verknüpfung in YAML, schlägt der Run schon vor dem Start fehl, wenn ein Anhang fehlt oder ausgelassen wurde.
Entra-ID-App
connic meldet sich bei Microsoft Graph als App an, die in deinem Microsoft-Entra-ID-Tenant registriert ist, ohne einen Benutzer. Ihre Zugangsdaten liegen im Kontozugang, nicht in der Verbindung, und connic speichert sie verschlüsselt. Verwalte Kontozugänge unter Project Settings → Connections; eine Änderung gilt für alle Verbindungen, die den Kontozugang nutzen. Ein Kontozugang kann Inbound- und Outbound-Verbindungen für mehrere Postfächer bedienen.
Öffne im Microsoft Entra Admin Center die App-Registrierungen und klicke auf Neue Registrierung. Wähle Nur Konten in diesem Organisationsverzeichnis. Eine Umleitungs-URI braucht die App nicht.
Füge unter API-Berechtigungen die Microsoft-Graph-Anwendungsberechtigungen
Mail.ReadWritehinzu, um E-Mails zu lesen und als gelesen zu markieren, undMail.Send, um E-Mails und Antworten zu senden. Klicke dann auf Administratorzustimmung erteilen.Erstelle unter Zertifikate & Geheimnisse ein Clientgeheimnis und kopiere seinen Wert. Läuft das Geheimnis ab, erstelle ein neues und trage es im Kontozugang ein.
| Einstellung | Beschreibung |
|---|---|
| Directory (tenant) ID | Von der Übersichtsseite der App, oder die Domain des Tenants, etwa contoso.onmicrosoft.com. |
| Application (client) ID | Von der Übersichtsseite der App. |
| Client secret | Der Wert eines Clientgeheimnisses unter Zertifikate & Geheimnisse, nicht seine Geheimnis-ID. |
Änderst du bei einem gespeicherten Kontozugang die Tenant-ID oder die Client-ID, gib das Clientgeheimnis erneut ein. Sonst lehnt connic die Änderung ab.
Auf bestimmte Postfächer beschränken
Mit der Administratorzustimmung in Entra ID kann die App in jedem Postfach des Tenants E-Mails lesen und senden. Um sie auf die Postfächer zu beschränken, die connic nutzen soll, weist ein Exchange-Administrator die Berechtigungen mit RBAC für Anwendungen in Exchange Online PowerShell zu. Die Objekt-ID stammt aus dem Eintrag der App unter Unternehmensanwendungen, nicht aus den App-Registrierungen:
New-ServicePrincipal -AppId <Client-ID> -ObjectId <Objekt-ID der Unternehmensanwendung> -DisplayName "connic"
New-ManagementScope -Name "connic mailboxes" -RecipientRestrictionFilter "PrimarySmtpAddress -eq 'support@contoso.com'"
New-ManagementRoleAssignment -App <Client-ID> -Role "Application Mail.ReadWrite" -CustomResourceScope "connic mailboxes"
New-ManagementRoleAssignment -App <Client-ID> -Role "Application Mail.Send" -CustomResourceScope "connic mailboxes"
Test-ServicePrincipalAuthorization -Identity <Client-ID> -Resource support@contoso.comEntferne danach Mail.ReadWrite und Mail.Send aus den API-Berechtigungen der App in Entra ID. Microsoft rechnet die Berechtigung aus Entra ID und die Zuweisung in Exchange zusammen. Solange die Berechtigung für den ganzen Tenant bestehen bleibt, wirkt die Beschränkung auf Postfächer also nicht. Exchange braucht 30 Minuten bis 2 Stunden, bis eine Änderung greift; Test-ServicePrincipalAuthorization zeigt das Ergebnis sofort.
Outbound-Zustellung
Modi: Outbound
Eine Outbound-Outlook-Verbindung sendet bei jeder Nutzung eine E-Mail aus der Mailbox: wenn der Run eines verknüpften Agenten abgeschlossen ist, wenn das Modell sie als Tool aufruft oder wenn Middleware sie aufruft, je nach Nutzung der Verknüpfung. Die E-Mail landet in den gesendeten Elementen des Postfachs. Diese Felder steuern sie:
| Feld | Beschreibung |
|---|---|
| to | Empfänger: eine Adresse, mehrere durch Kommas getrennte Adressen oder eine Liste. Jeder Eintrag kann adresse oder Name <adresse> sein. Sendet eine neue E-Mail, auch wenn eine eingehende Outlook-E-Mail den Run gestartet hat. |
| cc | Empfänger einer Kopie, in denselben Formaten wie to. Gilt auch für Antworten. |
| bcc | Empfänger einer Blindkopie, in denselben Formaten wie to. Gilt auch für Antworten. |
| subject | Der Betreff einer neuen E-Mail. Antworten behalten den Betreff des Verlaufs. |
| body | Der Text als Klartext. |
| html_body | Ein HTML-Text. Ist er gesetzt, enthält die E-Mail nur ihn, und body wird ignoriert. |
| reply_to | Die Adresse, an die Antworten auf diese E-Mail gehen. |
Hat eine Inbound-Outlook-Verbindung den Run gestartet und setzt die Ausgabe kein to, wird die E-Mail eine Antwort auf die eingehende E-Mail, im selben Verlauf. Dafür muss die Outbound-Verbindung dasselbe Postfach und denselben Kontozugang nutzen wie die Inbound-Verbindung. Die Antwort geht an den Absender der eingehenden E-Mail oder an deren Antwortadresse, falls sie eine hat. Sonst kommen die Empfänger aus to, danach aus den Default Recipients der Verbindung; fehlt beides, schlägt der Versand mit missing_recipient fehl. Eine neue E-Mail nimmt ihren Betreff aus subject, ohne ihn lautet er Agent Response. Ausgehende E-Mails haben keine Anhänge.
Automatische Ausgabe
Eine automatische Verknüpfung macht aus der finalen Ausgabe des Runs eine E-Mail. Klartext und jede andere Ausgabe, die kein JSON-Objekt ist, werden zum Text der E-Mail. Ein JSON-Objekt setzt die Felder oben und nimmt außerdem message statt body und html statt html_body an. Mit einem Output Schema gibt der Agent diese Felder zuverlässig zurück. Diese Ausgabe antwortet auf die eingehende E-Mail, mit einer Kopie an das Bestellteam:
{
"body": "Deine Bestellung wurde heute Morgen verschickt.",
"html_body": "<p>Deine Bestellung wurde heute Morgen verschickt.</p>",
"cc": ["orders@contoso.com"]
}Payload für Agent-Tool und Middleware
Das Modell oder die Middleware übergibt die Felder oben als Payload. body ist Pflicht, alle anderen Felder sind optional; message, html und alle anderen Felder werden abgelehnt. Postfach, Anmeldung und Wiederholungen ergänzt connic, das Modell sieht davon nichts.
{
"body": "Deine Anfrage ist erledigt.",
"to": ["jana@example.com"],
"subject": "Deine Support-Anfrage",
"html_body": "<p>Deine Anfrage ist erledigt.</p>",
"cc": ["manager@contoso.com"],
"bcc": ["archiv@contoso.com"],
"reply_to": "support@contoso.com"
}Zustellung und Wiederholungen
connic meldet sich als App an und übergibt die E-Mail an Microsoft Graph, das sie an alle Adressen in to, cc und bcc sendet. Ist Graph nicht erreichbar oder drosselt es die Anfrage, versucht connic es erneut, insgesamt dreimal, und wartet so lange, wie Graph es verlangt. Jeder andere Fehler beendet die Zustellung ohne weiteren Versuch. Bricht die Netzwerkverbindung ab, nachdem die E-Mail übergeben wurde, oder antwortet Graph mit einem Serverfehler, weiß connic nicht, ob die E-Mail verschickt wurde, und versucht es nicht erneut, damit sie nie doppelt ankommt. Prüfe dann die gesendeten Elemente des Postfachs. Die Runs der Verbindung zeigen jede Zustellung mit ihrem Fehler.
Limits und Fehler
| Limit | Wert |
|---|---|
| Ordnerprüfung | Etwa alle 30 Sekunden |
| E-Mails pro Prüfung | Jeweils 10 auf einmal, bis der Ordner aufgeholt ist oder 60 Sekunden vergangen sind. Der Rest folgt bei der nächsten Prüfung. |
| Anhänge pro E-Mail | 50, höchstens 32 MiB zusammen |
| Zustellversuche | 3, nur wenn Microsoft Graph nicht erreichbar ist oder die Anfrage drosselt |
| Versandlimits von Microsoft | 30 Nachrichten pro Minute und 10.000 Empfänger pro Tag je Postfach, festgelegt von Exchange Online |
| Limits von Microsoft Graph | 4 gleichzeitige Anfragen und 10.000 Anfragen in 10 Minuten je App und Postfach, laut den Drosselungslimits von Microsoft Graph. Andere Anwendungen, die dieselbe App-Registrierung für dasselbe Postfach nutzen, zählen mit. |
Lehnt Microsoft Entra ID die Anmeldung ab, etwa weil das Clientgeheimnis abgelaufen ist, oder gibt es das Postfach oder den Ordner nicht, zeigen die Logs der Verbindung Polling stopped mit dem Grund. connic prüft dann nicht weiter, bis du die Verbindung oder ihren Kontozugang erneut speicherst. Fehlende Berechtigungen, ein Postfach außerhalb der Beschränkung der App, Drosselung und Netzwerkfehler erscheinen als Poll error. connic versucht es weiter und wartet nach jedem Fehler länger, bis zu 15 Minuten. So läuft die Verbindung wieder an, sobald Exchange eine geänderte Berechtigung übernommen hat. Lässt sich eine E-Mail nicht als gelesen markieren, zeigen die Logs eine Warnung, und die E-Mail gilt trotzdem als verarbeitet.
Jede verarbeitete E-Mail erscheint in den Runs der Verbindung mit der Zahl der gestarteten Agenten. Lässt sich ein Run nicht starten, liest connic die E-Mail bei der nächsten Prüfung erneut. Agenten, die sie schon erhalten haben, bekommen dabei keinen zweiten Run. Nach 3 fehlgeschlagenen Leseversuchen, die an der E-Mail selbst liegen, etwa weil das Herunterladen länger als 20 Sekunden dauert, überspringt connic die E-Mail, damit spätere E-Mails nicht warten müssen. Eine übersprungene E-Mail erscheint in den Runs der Verbindung als fehlgeschlagen.