Microsoft 365 Connector

Connect Outlook mail, calendar, OneDrive and SharePoint

The Microsoft 365 connector gives the agent access to your Outlook mailbox, your calendars, and your OneDrive and SharePoint documents. By default it is read-only. An admin can also allow it to create and update calendar events and edit Excel workbooks, and each person then chooses whether to allow that for their own account. Every change is shown to you for approval before it is made. Email is never sent and files are never deleted.

Setup

Most organizations only need Step 1. The Azure app registration in Advanced setup is optional and only required if your security policy forbids third-party multi-tenant applications.

Step 1: Add the connector

1. Go to Connectors, open the APIs tab, and choose Microsoft 365.

2. Choose who signs in:

   • OAuth (Workspace-level): one Microsoft account is connected and shared with everyone you give access to.
   • OAuth (Per-member): each member who uses the connector signs in with their own Microsoft account.

3. Set each kind of access to Off, Read, or Read & write:

   Access	Read requests	Read & write also requests	What write unlocks
   Outlook mail	Mail.Read	Not available
   Outlook calendar	Calendars.Read	Calendars.ReadWrite	Creating, updating and cancelling events
   OneDrive files	Files.Read.All	Files.ReadWrite.All	Writing cells and adding rows in Excel workbooks
   SharePoint	Sites.Read.All	Files.ReadWrite.All, Sites.ReadWrite.All	The same, for workbooks in SharePoint

   Only the access you enable is requested at sign-in, so you can connect calendar alone without granting mailbox access. Turning on more access later takes effect after the account signs in again. Read & write cannot be combined with Metadata only. Microsoft Graph has no API for editing Word documents, so only Excel workbooks can be changed.

4. Optionally enable Metadata only (see Privacy).

5. Click Connect, sign in, and review the consent screen.

6. Click Save.

The connector is private to you until you share it from the APIs tab. With workspace-level sign-in, everyone you share it with reads the connected account, so share it only with people who should see that mailbox.

Sites.Read.All usually requires a Microsoft 365 administrator to grant consent for the whole tenant. If you are not an administrator and enable SharePoint, sign-in will show an “approval required” prompt. Either ask your administrator to approve it, or leave SharePoint off.

Step 2: Use it in a chat

Ask normally in any chat that can use API connectors. It composes with your warehouse and BI connectors, so you can ask questions that span both.

"What did Finance send me about the Q3 budget?"
"How many hours of meetings did I have last week?"
"Find the pricing deck on the Sales SharePoint site"
"Compare the pipeline numbers in Snowflake to what the forecast doc says"

You can also paste a SharePoint or OneDrive link, including one from Share > Copy link, and Ana opens that file directly. For anything the built-in search and read steps don’t cover, such as listing SharePoint sites, Ana can call Microsoft Graph from Python with the same sign-in. Code can only read: every change goes through the approval described below.

If you turn off mail, calendar, OneDrive or SharePoint after signing in, Ana stops calling Microsoft Graph from code for that account, because Microsoft keeps the earlier permissions on the sign-in. To use it from code again, revoke the app’s permissions and sign in again. If a Microsoft 365 administrator granted them for the whole organization, only an administrator can revoke them.

Making changes

When the connector allows Read & write, each person chooses what Ana may change when they click Connect. Nothing is selected by default, so an account stays read-only unless its owner allows changes. You can change your choice at any time with Change next to your connection on the APIs tab. Because Microsoft keeps permissions you consented to earlier, TextQL also remembers your choice and never makes a change you did not allow, even if the sign-in still carries write permission.

When you ask for a change, Ana shows a card with exactly what will change: the event’s title, time and guests, or the workbook cells being written with their current values, or the rows being added. Nothing happens until you click Approve. Decline, or sending another message instead, leaves everything as it was. Cancelling a meeting you organize notifies its attendees; cancelling one you were invited to removes it from your calendar. If you connected read-only, the card offers Allow changes, which signs you in again with write access.

To skip the card in a chat, turn on Auto-approve workspace changes in the chat’s tools menu. Ana then makes changes your sign-in allows right away and shows what it changed. It is off by default and applies only to chats you started yourself, not to chats with an agent or to messages others send in a chat you shared. Changes are only proposed in the app, with a person present. Scheduled runs, automated runs, Slack and Teams cannot make changes. Every approved change is recorded in the audit log.

Advanced: bring your own Azure application

Use this only if your organization requires that the application registration live in your own tenant.

Azure client secrets expire, typically after 6 to 24 months. When yours does, the connector stops working until you create a new secret and sign in again. Set a calendar reminder before the expiry date. Connectors using the platform application have no such expiry.

Register the application

1. In the Azure Portal, go to Microsoft Entra ID → App registrations → New registration.

2. Name it, choose Accounts in any organizational directory, and click Register.

3. Under Authentication, click Add a platform → Web and add this redirect URI:

   https://app.textql.com/auth/api-oauth/callback
   
   If you run a VPC or custom deployment, replace https://app.textql.com with your own host, for example https://textql.yourcompany.com/auth/api-oauth/callback.

4. Under Certificates & secrets, create a New client secret and copy the Value immediately.

5. Under API permissions, add these Microsoft Graph → Delegated permissions, matching the capabilities you plan to enable:

   • User.Read and offline_access (always required)
   • Mail.Read for Outlook mail
   • Calendars.Read for calendar
   • Files.Read.All for OneDrive
   • Sites.Read.All for SharePoint
   • Calendars.ReadWrite, Files.ReadWrite.All and Sites.ReadWrite.All only if you will set those to Read & write

Use it in the connector form

Click Use your own OAuth app in the connector form and paste the Application (Client) ID and Client Secret before clicking Connect. Leave Tenant as common unless you want to restrict sign-in to a single directory, in which case use your tenant ID or domain.

Privacy

Metadata only mode restricts the connector to non-content fields. When it is on:

• Available: message and file ids, sender and recipient addresses, timestamps, read and attachment flags, file sizes and types, event times and durations.
• Withheld: subjects, message bodies, file names, file contents, event titles, locations and attendee lists.

Content is never requested from Microsoft in this mode, not merely filtered after the fact. Ana also cannot call Microsoft Graph from code with a metadata-only account.

Troubleshooting

AADSTS50011: redirect URI mismatch

The redirect URI registered in Azure does not match the one TextQL uses. It must be exactly https://<your-host>/auth/api-oauth/callback, with no trailing slash. Applications registered for the earlier Microsoft 365 connector need this new redirect URI added. This only applies to bring-your-own-application setups.

The agent says the sign-in has expired

The stored grant is no longer valid. Common causes: the refresh token expired after a long period of inactivity, an administrator revoked consent, the account password changed, or (for bring-your-own-application setups) the Azure client secret expired. Open the connector on the APIs tab and click Connect to sign in again. The connector keeps its id, so chats and agents referencing it keep working.

The agent says access is not enabled

Sign-in succeeded but a specific Graph permission was not consented. The message names the access that is missing. Either have an administrator grant the permission, or turn that access off and sign in again.

Approval required during sign-in

The tenant requires administrator consent for one of the requested permissions, most often Sites.Read.All. Ask a Microsoft 365 administrator to approve the application, or turn off SharePoint and sign in again.

Searches feel incomplete

Results are bounded so a single question cannot pull an entire mailbox. When more matched than were returned, the agent is told the result was truncated and should say so. Narrow the date range or add filters for full coverage.