Skip to main content

Some screenshots show mcp-s.com, which some existing organizations still use. New organizations use withwillow.ai. Copy the URLs shown in your own organization.

Microsoft Outlook Mail

Microsoft Outlook Mail is the email service in Microsoft 365 and Outlook.com. The Willow connector reads, searches, drafts, sends, moves, and organizes messages, and manages mail folders and automatic replies, through the Microsoft Graph API.

Authentication types​

Outlook Mail supports one authentication method:

  • OAuth: Register your own app in Microsoft Entra. You control the app and its scopes. Each user connects with their Microsoft account. Microsoft Entra setup is required.

Before you start​

You will need:

  • A Microsoft account that can register apps in the Microsoft Entra admin center. A personal Microsoft account is enough for testing if it has a directory in the Entra admin center.
  • Your Willow Redirect URL, from the connector's Setup tab.

Users can connect with a personal Microsoft account (Outlook.com, Hotmail, Live) or a work or school account. In most work or school tenants, an admin must grant consent before anyone can connect. See Granting admin consent for your organization.

Setting up OAuth​

1. Register the app in Microsoft Entra​

Sign in to the Microsoft Entra admin center and go to Entra ID → App registrations → New registration. You can also use Microsoft Entra ID → App registrations in the Azure portal. Both open the same form.

Register an application form in the Microsoft Entra admin center, set to Any Entra ID Tenant + Personal Microsoft accounts with a Public client/native redirect URI

  1. Name: Enter a name users will recognize on the consent screen. Microsoft rejects names that contain "Microsoft" for apps that allow personal accounts, so use something like "Willow Connector".
  2. Supported account types: Select Any Entra ID Tenant + Personal Microsoft accounts. If only work or school accounts will connect, Multiple Entra ID tenants also works.
  3. Redirect URI: Set the platform to Public client/native (mobile & desktop) and enter your Willow redirect URL:
    • For SaaS deployments: https://{org}.withwillow.ai/{org}/api/auth/callback
    • For On-Premise deployments: {connectUrl}/{org}/api/auth/callback
  4. Click Register.

Copy the Application (client) ID from the app's Overview page. You will paste it into Willow in step 3.

App registration Overview page showing the Application (client) ID and one public client redirect URI

Prefer a multitenant app

By default Willow signs users in through Microsoft's shared /common endpoint, so a single-tenant app fails at sign-in with AADSTS50194: ... isn't configured as a multitenant application. Choose one of the multitenant options above. If your organization requires a single-tenant app, copy the Directory (tenant) ID from the app's Overview page and paste it into the connector's Setup → Configuration → Tenant ID in Willow. Willow then signs users in through that tenant's endpoint.

Why the public client platform​

Willow's Microsoft connectors use PKCE and do not send a client secret, so the app must be registered as a public client. With the redirect URI under Mobile and desktop applications, you do not need a client secret, and you can leave Allow public client flows (under Authentication → Settings) turned off.

The Web platform is for confidential clients, which must send a client secret when they exchange the authorization code. A redirect URI registered under Web without a secret in Willow fails with AADSTS7000218: The request body must contain ... 'client_assertion' or 'client_secret'.

To check or change the platform later, open the app's Authentication page. The Redirect URI configuration tab lists each URI with its platform type.

Authentication page, Redirect URI configuration tab, listing the Willow callback under Mobile and desktop applications

One app registration can serve several connectors

Every connector in a Willow organization shares the same Redirect URL, so one app registration works for Outlook Mail, Outlook Calendar, and OneDrive. Paste the same Client ID into each connector, then select only the scopes each one needs.

2. Add Microsoft Graph permissions​

Open the app's API permissions page. Microsoft Graph → User.Read is already listed.

API permissions page listing Microsoft Graph User.Read, with Add a permission and Grant admin consent buttons

  1. Click Add a permission → Microsoft Graph → Delegated permissions
  2. Type a permission name in the filter, expand its group, and select it
  3. Repeat for each scope you need, then click Add permissions

Request API permissions panel filtered to Mail with Mail.ReadWrite and Mail.Send selected

Willow's Outlook Mail connector offers these scopes. Add the ones the tools you plan to enable require:

ScopeUse it when
offline_accessAlways. Lets Willow refresh the token without asking the user to reconnect. It's under OpenId permissions.
Mail.ReadThe connector only reads and searches messages, attachments, and folders. This is the recommended starting point.
Mail.ReadWriteTools create drafts, move, update, or delete messages, or create, rename, or delete folders. Includes everything in Mail.Read. It doesn't include sending.
Mail.SendTools send, reply to, reply all to, or forward messages.
MailboxSettings.ReadTools read mailbox settings, such as time zone, language, and automatic replies.
MailboxSettings.ReadWriteTools turn automatic replies on or off. Includes everything in MailboxSettings.Read.
User.ReadTools read the signed-in user's profile.

Willow selects offline_access, Mail.ReadWrite, Mail.Send, and MailboxSettings.ReadWrite by default.

Adding permissions here doesn't change what users are asked for. Willow requests the scopes selected in step 3 every time a user connects. The list here is what an admin grants when consenting for the organization, so keep it the same as the scopes you select in Willow.

Microsoft lists every scope above as Admin consent required: No. That column is only Microsoft's default. Under the default Let Microsoft manage your consent settings policy, users in a work or school tenant can't consent to Mail.Read, Mail.ReadWrite, MailboxSettings.Read, or MailboxSettings.ReadWrite, so an admin has to. Mail.Send and User.Read aren't on Microsoft's restricted list.

3. Finish in Willow​

Open your Microsoft connector in Willow and go to the Setup tab.

  1. Under Authentication, select OAuth.
  2. Paste the Application (client) ID into Client ID.
  3. Leave Client Secret empty. The connector uses PKCE, so a public client app does not need one.
  4. Confirm the Redirect URL shown here exactly matches the URI you registered in step 1.
  5. Under Scopes, click Edit and select the scopes you need. Keep offline_access selected.
  6. Click Save Changes.

Willow Setup tab for a Microsoft connector with Client ID filled in, Client Secret left empty, the Redirect URL, and selected scopes

Willow requests the scopes selected here each time a user connects. Microsoft shows them on the consent screen even if you did not add them to the app in step 2. Adding them in step 2 matters when an admin has to grant consent for the organization. See Granting admin consent for your organization.

offline_access lets Willow get a refresh token. Without it, users have to reconnect each time their short-lived access token expires.

4. Authorize the connection​

Click Check connection. It stays disabled until the credentials are saved.

Willow opens Microsoft's sign-in window. It also shows an Authenticate your MCP dialog with the authorization URL and an Authenticate button in case your browser blocks the window. Sign in, review the permissions, and click Accept. The window shows Authentication Successful when Willow has the tokens. Then click I've authenticated.

Microsoft consent screen asking to let an unverified app access calendars and maintain access to data

"unverified" on the consent screen

Microsoft labels an app unverified until its publisher completes publisher verification, which requires a partner (MPN) ID. The app's Overview page links to it under Add MPN ID to verify publisher. Users with personal Microsoft accounts can still accept. In work or school tenants, an unverified multitenant app usually needs an admin to grant consent. See Granting admin consent for your organization.

Microsoft does not always show a consent screen. If the window goes straight to Authentication Successful, the connection still worked.

Test a read-only tool​

To test the connection, go to the Tools tab, open the row menu for a read-only tool, and choose Test Tool → Run test. A successful run returns data from Microsoft Graph as JSON.

Use a resource that the signed-in account can access. A 401 response indicates an authentication problem; a 403 or 404 can also indicate a missing scope or an inaccessible resource, so an error alone does not confirm a working connection.

Check Guards if a call is blocked

If a tool returns Tool blocked by organization's guardrails, a Willow Guard blocked the call; changing scopes will not fix it. Microsoft Graph responses often include email addresses, and some tools take them as input, so an Email Address Detection guard set to block will stop those calls. Check Guards for the matching rule.

Willow Test List Mail Folders dialog returning mail folders as JSON

Tools​

The connector has 20 tools.

GroupTools
ReadList Messages, Get Message, Search Messages, List Attachments, Get Attachment, List Mail Folders, Get Mail Folder, Get Mailbox Settings
SendSend Mail, Reply to Message, Reply All to Message, Forward Message
ChangeUpdate Message, Move Message, Create Draft, Create Mail Folder, Update Mail Folder, Update Automatic Replies
DeleteDelete Message, Delete Mail Folder

Review the Tools tab before you publish the connector, and turn off the tools your users don't need, especially the delete tools.

Personal Microsoft accounts accept the permissions themselves. Work or school accounts follow their tenant's user consent policy, and the default policy blocks most of the scopes Microsoft 365 connectors use. In that case users see Need admin approval at sign-in, and an admin has to grant consent once for the whole organization.

New tenants use Let Microsoft manage your consent settings (Recommended). Under that setting, users can't consent to Microsoft Graph permissions such as Mail.Read, Mail.ReadWrite, MailboxSettings.Read, MailboxSettings.ReadWrite, all Calendars.* permissions, Files.Read.All, and Files.ReadWrite.All. Microsoft updates the list over time; see Microsoft recommended user consent policy for the current one. To see which setting your tenant uses, go to Entra ID → Enterprise apps → Consent and permissions → User consent settings.

Consent and permissions, User consent settings page with Let Microsoft manage your consent settings selected

Granting consent needs a Cloud Application Administrator, Application Administrator, or Privileged Role Administrator. Pick the option that matches where the app is registered.

The app is registered in your own tenant. Make sure step 2 lists every scope the connector requests, then on the app's API permissions page click Grant admin consent for your tenant, and confirm. Each permission's Status changes to Granted.

The app is registered in another tenant, for example by a partner. The admin consent URL grants the permissions listed on the app's API permissions page, so the app owner must complete step 2 first. Then an admin of your tenant opens this URL, signs in, and accepts:

https://login.microsoftonline.com/{your-tenant-id}/adminconsent?client_id={client-id}

After consent, the app appears under Entra ID → Enterprise apps. To review or re-grant later, open it there and go to Security → Permissions.

If you would rather approve requests one by one than consent up front, turn on the admin consent workflow. Users can then ask for approval from the sign-in screen.

For the full procedure, see Microsoft's guide, Grant tenant-wide admin consent to an application.

Troubleshooting​

SymptomCause
AADSTS50011: The redirect URI ... does not match the redirect URIs configured for the applicationThe Redirect URI in the app registration does not exactly match Willow's Redirect URL.
AADSTS50194: ... isn't configured as a multitenant applicationThe app's supported account types is Single tenant only. Either change it to a multitenant option under Authentication → Supported accounts, or paste the app's Directory (tenant) ID into the connector's Setup → Configuration → Tenant ID in Willow.
AADSTS7000218: The request body must contain ... 'client_assertion' or 'client_secret'The redirect URI is registered under the Web platform, so Microsoft expects a client secret. Move it to Mobile and desktop applications.
A personal Microsoft account can't sign inThe app's supported account types excludes personal accounts. Choose Any Entra ID Tenant + Personal Microsoft accounts.
Need admin approval, or AADSTS90094 / AADSTS65001The tenant's user consent policy doesn't let users accept these scopes. See Granting admin consent for your organization.
The app name is rejected at registrationNames containing "Microsoft" aren't allowed for apps that support personal accounts. Choose another name.
A tool returns 403 for data the user can see in Outlook or OneDriveThe scope that tool needs isn't selected in Willow. Add it under Scopes, save, and reconnect.
Tool call returns {"error":{"type":"Tool Error","message":"Tool blocked by organization's guardrails"}}A Willow Guard blocked the call. Check Guards for the matching rule and result.