Outlook (Microsoft 365)
Start agents from incoming email in a Microsoft 365 mailbox and send their replies or notifications from it, through your own Entra ID app.
On this page
| Modes | Inbound, outbound |
| YAML type | outlook |
| Credentials | A Connection of type outlook with the tenant ID, client ID, and client secret of your own Entra ID app. |
| Mailboxes | Microsoft 365 work or school mailboxes. Outlook.com accounts aren't supported. |
| Bridge | Not supported |
| Custom domain | Not supported |
| Linked agents | One or more. An email starts every linked agent. |
| While paused | Inbound stops checking the folder. Email that arrives meanwhile is processed after Resume. Outbound sends nothing. |
Set up
Register the Entra ID app with the
Mail.ReadWriteandMail.Sendapplication permissions and admin consent, and create a client secret. To keep the app out of other mailboxes, limit it to certain mailboxes.Open the agent. In Connector Flow, click Add inbound connector for inbound or Add outbound connector for outbound. Then click Create New Connector and choose Outlook (Microsoft 365).
Choose the mode. Under Connection, pick a saved Connection or create one with the tenant ID, client ID, and client secret of the app.
Enter the Mailbox. For inbound, set the Folder and Mark as Read. For outbound, optionally enter Default Recipients.
Click Create. An inbound connector starts checking the folder. For outbound, choose how the agent uses the connector and click Link connector.
In code
Declare the connector in connectors/*.yaml. connection names the Connection that holds the app's credentials.
type: outlook
mode: inbound
connection: contoso-m365 # Connection with the 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 }Configuration
The fields of an Outlook connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.
| Field | Type | Status | Description |
|---|---|---|---|
| type | string | Required | outlook. |
| mode | string | Required | inbound or outbound. Dashboard: Mode. |
| connection | string | Required | Name or ID of a Connection of type outlook. See Entra ID app. Dashboard: Connection. |
| config | object | Required | Outlook settings. |
| mailbox | string | Required | The user principal name of the mailbox that receives or sends the email, such as support@contoso.com. A shared mailbox works too. Dashboard: Mailbox. |
| folder | string | Optional | Inbound. The folder to check: Inbox, Archive, another top-level folder by its name, or a subfolder as a path such as Inbox/Support. Dashboard: Folder.Default: Inbox |
| mark_as_read | boolean | Optional | Inbound. Mark an email as read once every linked agent received it. Dashboard: Mark as Read.Default: true |
| default_to | string | Optional | Outbound. Recipients of an email that neither sets to nor replies to an incoming Outlook email: one address or comma-separated addresses. Dashboard: Default Recipients. |
Agent input
Modes: Inbound
An inbound connector checks the folder through Microsoft Graph and starts a run for every linked agent with each new email. It starts with the email that arrives after its first check; email that was already in the folder isn't processed. connic remembers how far it got, so an email isn't processed twice, even with Mark as Read off. Changing the mailbox or the folder starts again at that moment. The run receives the email in the same shape as the Email connector, so an agent can take input from both:
{
"subject": "Help with order #12345",
"from": "Jane Doe <jane@example.com>",
"from_address": "jane@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": "Hi, my order hasn't arrived yet...",
"body_html": "<html><body><p>Hi, my order hasn't arrived yet...</p></body></html>",
"has_attachments": true,
"attachments": [
{
"filename": "receipt.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"
}
}fromandtolist name and address;from_addressis the bare sender address.dateis the time the mailbox received the email, in UTC.message_idis the email'sMessage-IDheader.body_textandbody_htmlare the body as plain text and as HTML. Microsoft 365 converts between the two, so both are filled._outlooknames the connector, the mailbox, the folder, and the email's Microsoft Graph ID, which stays the same when the email moves to another folder.
Attachments
Attachments follow the rules of the Email connector: the same included types, the same skipped tracking images and inline images under 50 KB, and the same encoding. Text, JSON, and XML files carry their content as text ("encoding": "text"), all other files as base64 ("encoding": "base64").
An email takes up to 50 attachments, at most 32 MiB combined. At the first attachment over a limit, connic keeps the attachments before it and omits that one and all later ones. Files of other types are omitted too, and so are attached Outlook items, such as a forwarded email or a calendar invitation, and links to files in the cloud. An omitted attachment has "content": null and a file_issue, and the payload lists every omission in file_issues:
{
"filename": "archive.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": "archive.rar",
"size_bytes": 20480
}
}The agent receives the email even when no attachment was accepted. Turn on Files required for an agent in the connector's details drawer, or set files_required: true on its link in YAML, to fail the run before it starts when an attachment is missing or was omitted.
Entra ID app
connic signs in to Microsoft Graph as an app registered in your Microsoft Entra ID tenant, without a user. Its credentials live on the Connection, not on the connector, and connic stores them encrypted. Manage Connections under Project Settings → Connections; a changed Connection applies to every connector that uses it. One Connection can serve inbound and outbound connectors on several mailboxes.
In the Microsoft Entra admin center, open App registrations and click New registration. Choose Accounts in this organizational directory only. The app needs no redirect URI.
Under API permissions, add the Microsoft Graph application permissions
Mail.ReadWrite, to read email and mark it as read, andMail.Send, to send email and replies. Then click Grant admin consent.Under Certificates & secrets, create a client secret and copy its value. When the secret expires, create a new one and enter it in the Connection.
| Setting | Description |
|---|---|
| Directory (tenant) ID | From the overview page of the app, or the tenant's domain, such as contoso.onmicrosoft.com. |
| Application (client) ID | From the overview page of the app. |
| Client secret | The value of a client secret from Certificates & secrets, not its secret ID. |
When you change the tenant ID or the client ID of a saved Connection, enter the client secret again; connic refuses the change otherwise.
Limit to certain mailboxes
With admin consent in Entra ID, the app can read and send email in every mailbox of the tenant. To limit it to the mailboxes connic should use, an Exchange administrator assigns the permissions with RBAC for Applications in Exchange Online PowerShell. Take the object ID from the app's entry under Enterprise applications, not from App registrations:
New-ServicePrincipal -AppId <client ID> -ObjectId <enterprise application object ID> -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.comThen remove Mail.ReadWrite and Mail.Send from the app's API permissions in Entra ID. Microsoft adds the Entra ID grant and the Exchange assignment together, so as long as the tenant-wide grant stays, the mailbox scope has no effect. Exchange can take 30 minutes to 2 hours to apply a change; Test-ServicePrincipalAuthorization shows the result right away.
Outbound delivery
Modes: Outbound
An outbound Outlook connector sends one email from the Mailbox each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. The email is saved in the mailbox's Sent Items. These fields control it:
| Field | Description |
|---|---|
| to | Recipients: one address, comma-separated addresses, or a list. Each can be address or Name <address>. Sends a new email even when the run came from an incoming Outlook email. |
| cc | Copy recipients, in the same formats as to. Also used for replies. |
| bcc | Blind copy recipients, in the same formats as to. Also used for replies. |
| subject | The subject of a new email. Replies keep the subject of the conversation. |
| body | The plain-text body. |
| html_body | An HTML body. When set, the email has only this body and body is ignored. |
| reply_to | The address that replies to this email go to. |
When an inbound Outlook connector started the run and the output sets no to, the email is a reply to the incoming email, in the same conversation. That needs the outbound connector to use the same mailbox and Connection as the inbound one. The reply goes to the sender of the incoming email, or to its reply-to address if it has one. Otherwise, the recipients come from to, then the connector's Default Recipients; without either, the send fails with missing_recipient. A new email takes its subject from subject, or Agent Response without one. Outbound emails have no attachments.
Automatic output
An automatic link turns the run's final output into an email. Plain text, and any output that isn't a JSON object, becomes the body. A JSON object sets the fields above, and also accepts message for body and html for html_body. Give the agent an output schema to make it return these fields. This output replies to the incoming email with a copy to the orders team:
{
"body": "Your order shipped this morning.",
"html_body": "<p>Your order shipped this morning.</p>",
"cc": ["orders@contoso.com"]
}Agent-tool and middleware payload
The model or middleware passes the fields above as the payload. body is required and all other fields are optional; message, html, and any other field are rejected. connic adds the mailbox, the sign-in, and the retries, none of which the model sees.
{
"body": "Your request has been resolved.",
"to": ["jane@example.com"],
"subject": "Your support request",
"html_body": "<p>Your request has been resolved.</p>",
"cc": ["manager@contoso.com"],
"bcc": ["archive@contoso.com"],
"reply_to": "support@contoso.com"
}Delivery and retries
connic signs in as the app and hands the email to Microsoft Graph, which sends it to every address in to, cc, and bcc. When Graph can't be reached or throttles the request, connic tries again, 3 times in total, waiting as long as Graph asks. Any other error fails the delivery without a retry. If the connection breaks after the email was handed over, or Graph answers with a server error, connic can't tell whether the email went out and doesn't retry, so it's never sent twice; check the mailbox's Sent Items. The connector's runs show each delivery with its error.
Limits and errors
| Limit | Value |
|---|---|
| Folder checks | About every 30 seconds |
| Emails per check | Read 10 at a time until the folder is caught up or 60 seconds have passed. The rest follow in the next check. |
| Attachments per email | 50, at most 32 MiB combined |
| Delivery attempts | 3, only when Microsoft Graph can't be reached or throttles the request |
| Microsoft sending limits | 30 messages per minute and 10,000 recipients per day per mailbox, set by Exchange Online |
| Microsoft Graph limits | 4 concurrent requests and 10,000 requests per 10 minutes per app and mailbox, per Microsoft Graph throttling limits. Other apps that use the same app registration on the same mailbox count too. |
When Microsoft Entra ID rejects the sign-in, for example after the client secret expired, or when the mailbox or folder doesn't exist, the connector's logs show Polling stopped with the reason, and connic stops checking until you save the connector or its Connection again. Missing permissions, a mailbox outside the app's scope, throttling, and network errors appear as Poll error; connic keeps trying and waits longer after each failure, up to 15 minutes, so the connector picks up once Exchange applies a permission change. If an email can't be marked as read, the logs show a warning and the email still counts as processed.
Every processed email appears in the connector's runs with the number of agents it started. If a run can't be started, connic reads the email again on the next check; agents that already received it don't get a second run. connic skips an email after 3 failed reads caused by the email itself, such as one that takes longer than 20 seconds to download, so later email isn't held up. A skipped email appears in the connector's runs as failed.