> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Microsoft Outlook
> Connect Circuit to Microsoft 365 Outlook so agents can read mail and prepare drafts on your behalf.
The Microsoft Outlook integration lets agents read your Outlook mail through Microsoft Graph, search messages, and prepare drafts in your Drafts folder. Circuit creates drafts only. It never sends mail.
## What you can do
* **List and search mail**: agents can list messages with OData `$filter` or run full-text searches with Graph's `$search`.
* **Read a specific message**: agents can fetch a single message by ID, including attachments.
* **Draft a new message**: agents can create a draft in your Drafts folder with To, Cc, Bcc, subject, and body (HTML or plain text).
* **Draft a reply**: agents can create a reply draft for an existing message, preserving the original thread.
* **Work in shared mailboxes**: agents can target a shared or delegated mailbox you already have access to in Exchange.
Circuit never sends a message. Every draft lands in your Drafts folder for you to review and send from Outlook yourself.
## Before you start
* A Microsoft work or school account with an Exchange Online mailbox.
* To act against a shared mailbox, you must already have delegated or Full Access permission on it in Exchange. Microsoft Graph returns `403` otherwise.
* For Microsoft Entra ID tenants that restrict third-party apps, your Entra administrator may need to grant tenant-wide admin consent for Circuit before you can connect. See [For IT and security teams](#for-it-and-security-teams) below.
## Connect Outlook
In Circuit, open **Settings** > **Integrations** and choose **Microsoft Outlook**.
Click **Connect Outlook**. Microsoft opens its sign-in page in a new window. Sign in with the work or school account whose mailbox you want Circuit to use.
Microsoft shows a consent screen listing the Graph permissions Circuit requests. Review them (see [What Circuit accesses](#what-circuit-accesses) below) and click **Accept**.
If you see a "Need admin approval" message instead, your tenant requires admin consent. Forward the page to your Entra administrator.
Microsoft redirects you back to Circuit. The integration status changes to **Connected**. Agents that include the Outlook tool can now read your mail and prepare drafts.
## What Circuit accesses
Circuit requests the following delegated Microsoft Graph scopes:
```
offline_access
openid
email
profile
User.Read
Mail.Read
Mail.ReadWrite
Mail.Read.Shared
Mail.ReadWrite.Shared
```
| Scope | Why Circuit needs it |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `offline_access` | Issue a refresh token so Circuit can keep the connection alive in the background. Microsoft access tokens are short-lived (about an hour), so without this scope you would need to reconnect frequently. |
| `openid`, `email`, `profile` | Standard OpenID Connect scopes that identify the signed-in user and return their email address and basic profile. Circuit uses these to label your connected account. |
| `User.Read` | Read the signed-in user's profile so Circuit can display your name and email in the integration UI. |
| `Mail.Read` | Read mail in your own mailbox. |
| `Mail.ReadWrite` | Create, read, and update mail in your own mailbox. Required to save drafts to your Drafts folder. |
| `Mail.Read.Shared` | Read mail in shared and delegated mailboxes you already have access to. |
| `Mail.ReadWrite.Shared` | Create and update mail (including drafts) in shared and delegated mailboxes you already have access to. |
Circuit uses the **OAuth 2.0 authorization code flow** against the Microsoft identity platform v2.0 endpoints. Your Microsoft password is never seen, stored, or transmitted to Circuit.
Circuit does not request `Mail.Send` or `Mail.Send.Shared`. The integration cannot send mail on your behalf, even if an agent is instructed to do so. Every outbound message is saved as a draft for you to send manually from Outlook.
## For IT and security teams
The Outlook integration authenticates through a single Circuit-published enterprise application in your Microsoft Entra ID tenant. The same enterprise application also backs Circuit's [Microsoft Dynamics 365](/admin/integrations/agent-tools/microsoft-dynamics), [OneDrive](/admin/integrations/feeds/onedrive), and SharePoint integrations: granting tenant-wide admin consent once covers all of them, although each user still authorizes the scopes they personally need.
In tenants that require admin approval for third-party applications, users will be blocked at the consent screen until a Cloud Application Administrator (or higher) grants tenant-wide consent. The Entra walkthrough, role requirements, direct admin-consent URL, and how to restrict the app to specific users or groups all live in [Integration security and admin consent](/it/integration-security).
## Disconnect or rotate access
* **From Circuit**: open **Settings** > **Integrations** > **Microsoft Outlook** and click **Disconnect**. Circuit deletes the stored refresh token immediately.
* **From Microsoft**: at [myapps.microsoft.com](https://myapps.microsoft.com) > **Manage your applications**, find Circuit and remove its permissions. Circuit loses access on the next API call.
* **Tenant-wide**: an Entra administrator can remove the Circuit enterprise application or revoke its consent in **Entra ID** > **Enterprise apps** > **Circuit** > **Permissions**. This invalidates all users' tokens immediately.
## Troubleshooting
Your Entra tenant requires tenant-wide admin consent for third-party apps. Ask your Entra administrator to grant consent for Circuit. See [Integration security and admin consent](/it/integration-security).
The signed-in user must already have delegated or Full Access permission on the shared mailbox in Exchange. The `Mail.Read.Shared` and `Mail.ReadWrite.Shared` scopes only grant access that Exchange itself has already granted. Ask the mailbox owner or an Exchange admin to assign access, then try again.
Microsoft Graph cannot combine `$search` and `$filter` in a single mail query. Use one or the other. Ask the agent to use `search` for full-text queries or `list` with `filter` for OData filters such as `isRead eq false`.
A refresh token can be invalidated by a password change, an MFA reset, an admin revocation, or a long period of inactivity. Disconnect and reconnect to issue a new token.
By design, Circuit only saves drafts. Open Outlook, find the draft in your Drafts folder, review it, and click **Send** yourself. Circuit will not send mail under any circumstances.
## Reference
* **OAuth flow**: Microsoft identity platform, authorization code (v2.0 endpoints)
* **Authorize endpoint**: `https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize`
* **Scopes requested**: `offline_access`, `openid`, `email`, `profile`, `User.Read`, `Mail.Read`, `Mail.ReadWrite`, `Mail.Read.Shared`, `Mail.ReadWrite.Shared`
* **Redirect URI**: `https://app.circuit.ai/api/outlook-oauth`
* **Application name shown on consent screen**: Circuit
* **Microsoft's own docs**: [Get access on behalf of a user](https://learn.microsoft.com/en-us/graph/auth-v2-user), [Microsoft Graph mail permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#mail-permissions), [Access shared and delegated mail folders](https://learn.microsoft.com/en-us/graph/outlook-share-messages-folders)