Zum Hauptinhalt springen
connic
Starte kostenlos
Verbindungen

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.

Zuletzt aktualisiert
ModiInbound, Outbound
YAML-Typoutlook
ZugangsdatenEin Kontozugang (Connection) vom Typ outlook mit Tenant-ID, Client-ID und Clientgeheimnis deiner eigenen Entra-ID-App.
PostfächerGeschäfts- und Schulpostfächer in Microsoft 365. Outlook.com-Konten werden nicht unterstützt.
BridgeNicht unterstützt
Custom DomainNicht unterstützt
Verknüpfte AgentenEiner oder mehrere. Jede E-Mail startet alle verknüpften Agenten.
Während der PauseInbound prüft den Ordner nicht mehr. E-Mails, die in der Zeit ankommen, werden nach Resume verarbeitet. Outbound sendet nichts.

Einrichtung

  1. Registriere die Entra-ID-App mit den Anwendungsberechtigungen Mail.ReadWrite und Mail.Send samt Administratorzustimmung und erstelle ein Clientgeheimnis. Soll die App keine anderen Postfächer erreichen, beschränke sie auf bestimmte Postfächer.

  2. Ö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).

  3. Wähle den Modus. Wähle unter Connection einen gespeicherten Kontozugang oder lege einen mit Tenant-ID, Client-ID und Clientgeheimnis der App an.

  4. Gib die Mailbox ein. Lege für Inbound den Folder und Mark as Read fest. Gib für Outbound optional Default Recipients ein.

  5. 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.

connectors/support-inbox.yaml
type: outlook
mode: inbound
connection: contoso-m365   # Kontozugang mit der Entra-ID-App
config:
  mailbox: support@contoso.com
  folder: Inbox
agents:
  - support-triage
connectors/support-replies.yaml
type: 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.

FeldTypStatusBeschreibung
typestringRequiredoutlook.
modestringRequiredinbound oder outbound. Dashboard: Mode.
connectionstringRequiredName oder ID eines Kontozugangs vom Typ outlook. Siehe Entra-ID-App. Dashboard: Connection.
configobjectRequiredEinstellungen der Outlook-Verbindung.
mailboxstringRequiredDer Benutzerprinzipalname des Postfachs, das die E-Mails empfängt oder versendet, etwa support@contoso.com. Ein freigegebenes Postfach geht auch. Dashboard: Mailbox.
folderstringOptionalInbound. 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_readbooleanOptionalInbound. Eine E-Mail als gelesen markieren, sobald alle verknüpften Agenten sie erhalten haben. Dashboard: Mark as Read.Default: true
default_tostringOptionalOutbound. 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:

payload.json
{
  "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"
  }
}
  • from und to nennen Name und Adresse; from_address ist die reine Absenderadresse.
  • date ist der Zeitpunkt, zu dem das Postfach die E-Mail empfangen hat, in UTC. message_id ist der Header Message-ID der E-Mail.
  • body_text und body_html sind der Text als Klartext und als HTML. Microsoft 365 wandelt zwischen beiden um, deshalb sind immer beide gefüllt.
  • _outlook nennt 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:

ausgelassener Anhang
{
  "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.

  1. Ö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.

  2. Füge unter API-Berechtigungen die Microsoft-Graph-Anwendungsberechtigungen Mail.ReadWrite hinzu, um E-Mails zu lesen und als gelesen zu markieren, und Mail.Send, um E-Mails und Antworten zu senden. Klicke dann auf Administratorzustimmung erteilen.

  3. Erstelle unter Zertifikate & Geheimnisse ein Clientgeheimnis und kopiere seinen Wert. Läuft das Geheimnis ab, erstelle ein neues und trage es im Kontozugang ein.

EinstellungBeschreibung
Directory (tenant) IDVon der Übersichtsseite der App, oder die Domain des Tenants, etwa contoso.onmicrosoft.com.
Application (client) IDVon der Übersichtsseite der App.
Client secretDer 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:

Exchange Online PowerShell
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.com

Entferne 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:

FeldBeschreibung
toEmpfä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.
ccEmpfänger einer Kopie, in denselben Formaten wie to. Gilt auch für Antworten.
bccEmpfänger einer Blindkopie, in denselben Formaten wie to. Gilt auch für Antworten.
subjectDer Betreff einer neuen E-Mail. Antworten behalten den Betreff des Verlaufs.
bodyDer Text als Klartext.
html_bodyEin HTML-Text. Ist er gesetzt, enthält die E-Mail nur ihn, und body wird ignoriert.
reply_toDie 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:

output.json
{
  "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.

connector-payload.json
{
  "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

LimitWert
OrdnerprüfungEtwa alle 30 Sekunden
E-Mails pro PrüfungJeweils 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-Mail50, höchstens 32 MiB zusammen
Zustellversuche3, nur wenn Microsoft Graph nicht erreichbar ist oder die Anfrage drosselt
Versandlimits von Microsoft30 Nachrichten pro Minute und 10.000 Empfänger pro Tag je Postfach, festgelegt von Exchange Online
Limits von Microsoft Graph4 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.