Outlook Connector

The Outlook connector provides full access to Microsoft Outlook mailboxes via the Microsoft Graph API, enabling AI agents and automations to read, search, send, and manage emails.

Read Operations

List folders, messages, and attachments with filtering and pagination

Send Operations

Send, reply, reply-all, forward emails with HTML support

Manage Messages

Move, copy, delete, and update message properties

Prerequisites

An Azure AD Application registered in your tenant
Application permissions granted (not Delegated):
- Mail.Read - Read mail in all mailboxes
- Mail.ReadWrite - Create drafts, update, delete, move, copy
- Mail.Send - Send, reply, reply-all, forward
- MailboxSettings.Read - Read mailbox settings
Admin consent granted for these permissions

Minimal permissions: If you only need read access, Mail.Read and MailboxSettings.Read are sufficient. Add Mail.Send and/or Mail.ReadWrite only if you use write tools.

Usage as App
Usage as MCP

Installation

Go to Apps in your workspace
Search for Outlook App and install it
Configure the app instance with your Azure AD credentials

Configuration

Field	Value
Azure Client ID	Application (client) ID from Azure AD
Azure Client Secret	Client secret value
Azure Tenant ID	Directory (tenant) ID
Default User ID	Email address or user object ID of the target mailbox

Available Automations

Read Operations

Automation	Description	Permission
`listMailFolders`	List all mail folders with message counts	Mail.Read
`getMailFolder`	Get folder details by ID or well-known name	Mail.Read
`listMessages`	List messages with filtering, pagination, sorting	Mail.Read
`getMessage`	Get full message content and metadata	Mail.Read
`searchMessages`	Search messages using KQL syntax	Mail.Read
`listAttachments`	List all attachments for a message	Mail.Read
`getAttachment`	Get attachment content as base64	Mail.Read
`getMailboxSettings`	Get timezone, locale, automatic replies	MailboxSettings.Read

Send Operations

Automation	Description	Permission
`sendMail`	Send an email (to/cc/bcc, HTML/text, importance)	Mail.Send
`sendDraft`	Send an existing draft message	Mail.Send
`replyMessage`	Reply to a message	Mail.Send
`replyAllMessage`	Reply-all to a message	Mail.Send
`forwardMessage`	Forward a message to recipients	Mail.Send

Write Operations

Automation	Description	Permission
`createDraft`	Create a draft email in Drafts folder	Mail.ReadWrite
`updateMessage`	Update properties (read status, importance)	Mail.ReadWrite
`deleteMessage`	Soft-delete (move to Deleted Items)	Mail.ReadWrite
`moveMessage`	Move message to another folder	Mail.ReadWrite
`copyMessage`	Copy message to another folder	Mail.ReadWrite

DSUL Examples

List Messages

- Outlook App.listMessages:
    userId: user@company.com
    folderId: inbox
    top: 10
    filter: "isRead eq false"
    output: messages

Send an Email

- Outlook App.sendMail:
    userId: user@company.com
    to: recipient@example.com
    subject: Meeting Follow-up
    body: "<p>Thank you for the meeting today.</p>"
    contentType: HTML
    output: result

Search Messages

- Outlook App.searchMessages:
    userId: user@company.com
    query: "from:john@example.com subject:project"
    top: 20
    output: results

Reply to a Message

- Outlook App.replyMessage:
    userId: user@company.com
    messageId: "{{messageId}}"
    comment: "Thanks for the update!"
    output: result

MCP Setup

Open your AI Knowledge project
Go to Advanced > Tools
Click Add and select the MCP tab
Enter the MCP endpoint URL
In the Headers field, add your credentials:

{
  "mcp-api-key": "your-mcp-api-key",
  "azure-client-id": "your-client-id",
  "azure-client-secret": "your-client-secret",
  "azure-tenant": "your-tenant-id"
}

The mcp-api-key value must match the MCP API Key secret configured in the workspace secrets (mcpApiKey).

Authentication

The MCP server resolves credentials in priority order:

Bearer token in Authorization header (pre-resolved)
Azure credentials in custom headers (azure-client-id, azure-client-secret, azure-tenant)
Workspace secrets (azureClientId, azureClientSecret, azureTenant)

Workspace Secrets

Secret	Description
`azureClientId`	Azure AD client ID
`azureClientSecret`	Azure AD client secret
`azureTenant`	Azure AD tenant ID
`defaultUserId`	Default mailbox email or user object ID
`mcpApiKey`	API key for authenticating MCP requests

Mailbox Targeting

The userId parameter identifies which mailbox to access:

User Principal Name: user@yourdomain.com
User Object ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Resolved in order: tool argument userId > workspace secret defaultUserId. If neither is set, the request fails.

Available Tools

Read Operations

Tool	Description	Permission
`listMailFolders`	List all mail folders with message counts	Mail.Read
`getMailFolder`	Get folder details by ID or well-known name	Mail.Read
`listMessages`	List messages with filtering, pagination, sorting	Mail.Read
`getMessage`	Get full message content and metadata	Mail.Read
`searchMessages`	Search messages using KQL syntax	Mail.Read
`listAttachments`	List all attachments for a message	Mail.Read
`getAttachment`	Get attachment content as base64	Mail.Read
`getMailboxSettings`	Get timezone, locale, automatic replies	MailboxSettings.Read

Send Operations

Tool	Description	Permission
`sendMail`	Send an email (to/cc/bcc, HTML/text, importance)	Mail.Send
`sendDraft`	Send an existing draft message	Mail.Send
`replyMessage`	Reply to a message (comment or full body)	Mail.Send
`replyAllMessage`	Reply-all to a message	Mail.Send
`forwardMessage`	Forward a message to recipients	Mail.Send

Write Operations

Tool	Description	Permission
`createDraft`	Create a draft email in Drafts folder	Mail.ReadWrite
`updateMessage`	Update properties (read status, importance, categories)	Mail.ReadWrite
`deleteMessage`	Soft-delete (move to Deleted Items)	Mail.ReadWrite
`moveMessage`	Move message to another folder	Mail.ReadWrite
`copyMessage`	Copy message to another folder	Mail.ReadWrite

JSON-RPC Examples

List Messages

{
  "name": "listMessages",
  "arguments": {
    "userId": "user@company.com",
    "folderId": "inbox",
    "top": 10,
    "filter": "isRead eq false"
  }
}

Send an Email

{
  "name": "sendMail",
  "arguments": {
    "userId": "user@company.com",
    "to": "recipient@example.com",
    "subject": "Meeting Follow-up",
    "body": "<p>Thank you for the meeting today.</p>",
    "contentType": "HTML"
  }
}

Search Messages

{
  "name": "searchMessages",
  "arguments": {
    "userId": "user@company.com",
    "query": "from:john@example.com subject:project",
    "top": 20
  }
}

Output Formats

All tools support an outputFormat parameter:

verbose (default) - Human-readable text for LLM consumption
structured - Machine-readable JSON in structuredContent
both - Both text and structured content

Security: Restrict to One Mailbox

Application permissions grant access to all mailboxes in the tenant by default. To restrict this connector to a single mailbox, use an Application Access Policy in Exchange Online:

# 1. Connect to Exchange Online
Connect-ExchangeOnline

# 2. Create a mail-enabled security group with only the target mailbox
New-DistributionGroup -Name "OutlookMCP-Allowed" -Type Security -Members user@yourdomain.com

# 3. Restrict the Azure AD app to only access that group's mailboxes
New-ApplicationAccessPolicy -AppId "<your-azure-client-id>" `
  -PolicyScopeGroupId "OutlookMCP-Allowed" `
  -AccessRight RestrictAccess `
  -Description "Restrict Outlook connector to single mailbox"

# 4. Verify (may take up to 30 minutes to propagate)
Test-ApplicationAccessPolicy -AppId "<your-azure-client-id>" -Identity user@yourdomain.com
# Expected: Granted

The PowerShell commands above are provided as general guidance. Always refer to the official Microsoft documentation for the most up-to-date syntax.

Error Handling

HTTP Status	Error	Solution
401	Unauthorized	Verify clientId, clientSecret, tenant
403	Forbidden	Grant admin consent or check Application Access Policy
404	Not Found	Verify user email/ID exists in tenant
429	Rate Limited	Wait and retry

Common Issues

AADSTS700016 - App not found in the directory. Check tenant ID matches the app registration. MailboxNotEnabledForRESTAPI - The user needs an Exchange Online license assigned. ErrorAccessDenied with Application Access Policy - The target mailbox is not in the allowed security group. Takes up to 30 minutes to propagate after policy changes.

External Resources

Microsoft Graph Mail API

Official API documentation

Application Access Policies

Restrict mailbox access per application

Graph Explorer

Test API calls interactively

MCP Specification

Model Context Protocol specification

Integration Overview

Apps Marketplace

Read Operations

Send Operations

Manage Messages

Prerequisites

Installation

Configuration

Available Automations

Read Operations

Send Operations

Write Operations

DSUL Examples

List Messages

Send an Email

Search Messages

Reply to a Message

MCP Setup

Authentication

Workspace Secrets

Mailbox Targeting

Available Tools

Read Operations

Send Operations

Write Operations

JSON-RPC Examples

List Messages

Send an Email

Search Messages

Output Formats

Security: Restrict to One Mailbox

Error Handling

Common Issues

External Resources

Microsoft Graph Mail API

Application Access Policies

Graph Explorer

MCP Specification

Integration Overview

Apps Marketplace

Read Operations

Send Operations

Manage Messages

​Prerequisites

​Installation

​Configuration

​Available Automations

​Read Operations

​Send Operations

​Write Operations

​DSUL Examples

​List Messages

​Send an Email

​Search Messages

​Reply to a Message

​MCP Setup

​Authentication

​Workspace Secrets

​Mailbox Targeting

​Available Tools

​Read Operations

​Send Operations

​Write Operations

​JSON-RPC Examples

​List Messages

​Send an Email

​Search Messages

​Output Formats

​Security: Restrict to One Mailbox

​Error Handling

​Common Issues

​External Resources

Microsoft Graph Mail API

Application Access Policies

Graph Explorer

MCP Specification

Prerequisites

Installation

Configuration

Available Automations

Read Operations

Send Operations

Write Operations

DSUL Examples

List Messages

Send an Email

Search Messages

Reply to a Message

MCP Setup

Authentication

Workspace Secrets

Mailbox Targeting

Available Tools

Read Operations

Send Operations

Write Operations

JSON-RPC Examples

List Messages

Send an Email

Search Messages

Output Formats

Security: Restrict to One Mailbox

Error Handling

Common Issues

External Resources