Microsoft Mail

Prerequisites

Use a Microsoft Entra tenant and an account with permission to create an app registration. Review the official Microsoft Graph mail API, app registration guide, and Entra app registrations. Choose Accounts in any organizational directory for a multi-tenant SaaS, or the single-tenant option for an internal installation.

Self-hosted setup

1. In Microsoft Entra admin center → App registrations, create or open a Web application.
2. Under Authentication, add the exact Web redirect URI https://<your-authlane-host>/api/v1/oauth/microsoft-mail/callback. Do not enable implicit grant.
3. Under API permissions, add the delegated Microsoft Graph permissions listed below. Use read-only or full access to match the service policy you will select in Authlane.
4. Grant administrator consent when required by the tenant's consent policy.
5. Under Certificates & secrets, create a client secret and copy its Value immediately. Authlane needs the value, not the secret ID.

One Entra app can serve all three Microsoft services when every exact Authlane callback URI and every required delegated Graph permission is registered.

Configure authentication

Open Dashboard → Services → Microsoft Mail, enter the Entra Application (client) ID as the Client ID and the client secret Value as the Client Secret, select read_only or full, then enable the service. The secret stays encrypted on the Authlane server and must never be sent to a browser.

Scopes

Full policy requests these delegated scopes:

• offline_access
• openid
• profile
• User.Read
• Mail.ReadWrite
• Mail.Send

Read-only policy replaces Mail.ReadWrite and Mail.Send with Mail.Read. offline_access allows refresh tokens; openid, profile, and User.Read establish the connected identity. See the current Microsoft Graph permissions reference before granting consent.

Execution path

Microsoft now lists a Mail server in the Agent 365 MCP catalog, but that Frontier path is not credential-compatible with a normal delegated Graph token: it requires an Agent 365 blueprint, a separate MCP audience and per-server permission, plus tenant-admin setup. Authlane must not send a Graph token to that endpoint. This generally available connection therefore emits canonical tools whose local adapter calls https://graph.microsoft.com/v1.0 directly from the SaaS runtime. Normal mail inputs and responses never pass through Authlane; only the explicit administrator Sandbox can invoke the same adapter for testing.

Available tools

• microsoft_mail_list_messages
• microsoft_mail_search_messages
• microsoft_mail_get_message
• microsoft_mail_list_folders
• microsoft_mail_list_attachments
• microsoft_mail_get_attachment
• microsoft_mail_create_draft
• microsoft_mail_update_message
• microsoft_mail_send_message
• microsoft_mail_send_draft
• microsoft_mail_reply_to_message
• microsoft_mail_forward_message
• microsoft_mail_move_message
• microsoft_mail_delete_message

Read-only policy exposes only list, search, and get tools. Write and destructive tools carry MCP risk annotations so the SaaS runtime can require approval immediately before execution.

Connection lifecycle

Authlane encrypts OAuth credentials, refreshes access when possible, and reports the effective connection state. Upgrading from the former Microsoft connector expires its stored connection once; reconnect to obtain Microsoft Graph-scoped consent. Changing between read-only and full policy also requires reconnecting so consent and the issued tool set stay aligned.

Troubleshooting

• AADSTS50011 means the redirect URI differs by scheme, host, port, path, or trailing slash.
• Confirm you copied the client secret Value before it expired, not its identifier.
• Verify the connected account has an Exchange Online mailbox and consent for the selected scopes.
• If user consent is disabled, ask an Entra administrator to grant tenant-wide consent.