Skip to main content
On self-hosted OneCLI, Outlook Mail needs your own Microsoft app first. See Self-hosted.

​
Overview

OneCLI connects AI agents to Outlook Mail through Microsoft’s OAuth flow. Agents can read your inbox, send emails, manage folders, and search messages. The gateway injects OAuth credentials into requests to the Microsoft Graph API automatically. This is useful for agents working in Microsoft 365 environments that need to process emails, send notifications, or automate inbox management.

​
What you will set up

  • An Outlook Mail connection through Microsoft OAuth
  • Automatic token injection on requests to Microsoft Graph
  • Per-agent, per-tool access, such as read freely and approve sends

​
Setup

1

Go to Connections

Open the OneCLI dashboard and navigate to Connections > Outlook Mail.
2

Authorize

Click Connect Outlook. You’ll be redirected to Microsoft to sign in and authorize OneCLI. Review the permissions and click Accept.
OneCLI connect window for Outlook Mail on Cloud, showing the Connect to Outlook Mail button.

The Outlook Mail connect window on OneCLI Cloud.

​
Self-hosted: use your own Microsoft app

Skip this section on OneCLI Cloud. It’s only for self-hosted OneCLI without MICROSOFT_CLIENT_ID and MICROSOFT_CLIENT_SECRET set. One Microsoft app serves Outlook Mail, Outlook Calendar, Microsoft Word, and Microsoft OneNote, so you set it up once.

1. Register the app

In the Microsoft Entra admin center, open Entra ID > App registrations > New registration. Name it OneCLI and, under Supported account types, choose Any Entra ID Tenant + Personal Microsoft accounts.
In OneCLI, open Connections > Outlook Mail > Custom credentials and copy the Redirect URI. In the registration form, set the platform to Web, paste the URI, and select Register.
Microsoft Entra Register an application form with the name OneCLI, Supported account types set to Any Entra ID Tenant + Personal Microsoft accounts, and a Web redirect URI.

The registration form: account type and the Web redirect URI.

OneCLI Custom credentials card for Outlook Mail with the setup guide link, the Redirect URI and its copy button, and the client ID and secret fields.

Copy the Redirect URI from Custom credentials in OneCLI.

Open API permissions > Add a permission > Microsoft Graph > Delegated permissions and add:
Microsoft Entra API permissions page listing Microsoft Graph delegated permissions including Mail.ReadWrite, Mail.Send, Calendars.ReadWrite, Files.ReadWrite, the Notes permissions, offline_access, and User.Read, all granted.

API permissions after adding the Microsoft Graph delegated permissions. Extra ones such as openid and email are harmless.

Copy the Application (client) ID from Overview. Open Certificates & secrets > New client secret and copy its Value (shown once). Paste both into Connections > Outlook Mail > Custom credentials, select Save & Connect, and accept in Microsoft.

​
What agents can do

  • Search messages by sender, subject, body content, date range, or folder
  • Read the full content of emails, including attachments
  • Send new emails with recipients, subject, body, and attachments
  • Reply to or forward messages
  • Create, rename, and delete mail folders
  • Move messages between folders
  • Mark messages as read or unread
  • Flag messages for follow-up
  • List and manage inbox rules
  • Read and manage focused inbox preferences

​
Controlling access

Access is per agent: grant the connection to each agent that needs it, choosing per tool what runs freely, what needs human approval, and what stays blocked — a read-only agent is a single grant. Organization rules add guardrails on top, like rate limits and blanket blocks. Everything is checked before credential injection, so a blocked request never reaches Microsoft Graph.

​
FAQ

Yes. When you grant the connection, allow the read tools and block or require approval for sending.
No. The token stays in OneCLI, and the gateway adds it to Microsoft Graph requests at the proxy. See How it works.
Yes, on self-hosted. One Microsoft app serves Outlook Mail, Outlook Calendar, Microsoft Word, and Microsoft OneNote. See Self-hosted.
Open Connections > Outlook Mail and connect again. Agents with access use the new connection automatically.