Skip to main content
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 below.

​
Connect Outlook

1

Open the Outlook integration in Circuit

In Circuit, open Settings > Integrations and choose Microsoft Outlook.
2

Sign in with Microsoft

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

Review and consent to the requested permissions

Microsoft shows a consent screen listing the Graph permissions Circuit requests. Review them (see 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.
4

Return to Circuit

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
ScopeWhy Circuit needs it
offline_accessIssue 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, profileStandard 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.ReadRead the signed-in user’s profile so Circuit can display your name and email in the integration UI.
Mail.ReadRead mail in your own mailbox.
Mail.ReadWriteCreate, read, and update mail in your own mailbox. Required to save drafts to your Drafts folder.
Mail.Read.SharedRead mail in shared and delegated mailboxes you already have access to.
Mail.ReadWrite.SharedCreate 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, 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.

​
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 > 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

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, Microsoft Graph mail permissions, Access shared and delegated mail folders