Skip to main content

Microsoft Outlook Mail

Microsoft Outlook Mail is a professional email service that's part of Microsoft 365. This connector enables AI assistants to read, send, search, and manage emails, attachments, mail folders, and mailbox settings through the Microsoft Graph API.

Authentication Types​

Microsoft Outlook Mail supports OAuth 2.0 authentication via the Microsoft identity platform:

  • OAuth - Standard OAuth 2.0 authorization flow with PKCE
    • Pros: Secure delegated access, per-user mailbox access, automatic token refresh
    • Cons: Requires Azure app registration, user consent needed
    • Best for: Production applications, user-specific email operations

Setting up OAuth​

1. Register an Application in Azure Portal​

  1. Go to Azure Portal

  2. Navigate to Microsoft Entra ID (formerly Azure Active Directory)

  3. In the left sidebar, click App registrations

  4. Click New registration

  5. Fill in the application details:

    • Name: Choose a descriptive name (e.g., "Webrix Outlook Mail Integration")
    • Supported account types: Select the appropriate option:
      • "Accounts in this organizational directory only" for single-tenant apps
      • "Accounts in any organizational directory" for multi-tenant apps
      • "Accounts in any organizational directory and personal Microsoft accounts" for the widest support
    • Redirect URI: Select "Web" and enter:
      • For SaaS deployments: https://{org}.mcp-s.com/{org}/api/auth/callback
      • For On-Premise deployments: {connectUrl}/{org}/api/auth/callback

  6. Click Register

2. Configure API Permissions​

  1. In your app registration, click API permissions in the left sidebar

  2. Click Add a permission

  3. Select Microsoft Graph

  4. Choose Delegated permissions

  5. Add the following permissions based on your needs:

    Essential permissions:

    • User.Read - Sign in and read user profile
    • Mail.Read - Read user mail
    • offline_access - Maintain access to data (enables refresh tokens)

    For sending emails:

    • Mail.Send - Send mail as a user

    For managing emails (move, delete, drafts, folders):

    • Mail.ReadWrite - Read and write access to user mail

    For mailbox settings (automatic replies, etc.):

    • MailboxSettings.Read - Read user mailbox settings
    • MailboxSettings.ReadWrite - Read and write user mailbox settings

  6. Click Add permissions

  7. Important: Click Grant admin consent for [Your Organization] if you have admin rights.

tip

Some permissions require admin consent. If you see "Admin consent required" next to a permission, ask your tenant administrator to grant consent.

3. Create Client Secret​

  1. In your app registration, click Certificates & secrets in the left sidebar

  2. Under Client secrets, click New client secret

  3. Add a description (e.g., "Outlook Mail Connector Secret")

  4. Choose an expiration period (recommended: 12 months or 24 months)

  5. Click Add

  6. Important: Copy the secret Value immediately - it will only be shown once!

warning

Store the client secret securely. If you lose it, you'll need to create a new one.

4. Get Your Credentials​

You'll need these values to configure the connector:

  1. Application (client) ID: Found on the app registration Overview page
  2. Client Secret: The value you copied in the previous step

5. Configure in Webrix​

  1. In Webrix, paste the Client ID and Client Secret

  2. Select the scopes you need:

    • At minimum: User.Read, Mail.Read, offline_access
    • For sending: Add Mail.Send
    • For full management: Add Mail.ReadWrite
    • For mailbox settings: Add MailboxSettings.Read or MailboxSettings.ReadWrite

  3. Click Save Changes

  4. Click Connect to authorize the integration

Available Scopes​

Read Operations​

  • User.Read - Required for authentication; reads user profile information
  • Mail.Read - Read access to the user's mailbox, including messages and attachments
  • MailboxSettings.Read - Read mailbox settings like automatic replies, language, and time zone

Write Operations​

  • Mail.Send - Send emails on behalf of the user
  • Mail.ReadWrite - Full read/write access to messages, drafts, and mail folders
  • MailboxSettings.ReadWrite - Manage mailbox settings including automatic replies

Essential​

  • offline_access - Enables refresh tokens to maintain long-term access without re-authentication

Common Use Cases​

Read and Search Email​

  • List messages from inbox or any mail folder
  • Search for emails by keywords, sender, or subject
  • Get full email details including body and attachments
  • Filter emails by read status, importance, or other criteria

Send and Respond to Email​

  • Send new emails with HTML formatting to multiple recipients
  • Reply to or reply-all to existing messages
  • Forward emails to other recipients
  • Create draft emails for later review and sending

Manage Email​

  • Mark messages as read or unread
  • Flag messages for follow-up
  • Move messages between folders (inbox, archive, etc.)
  • Delete messages
  • Categorize emails

Organize Folders​

  • List all mail folders with unread/total counts
  • Create custom mail folders and subfolders
  • Rename or delete folders

Configure Mailbox​

  • View mailbox settings (language, time zone, working hours)
  • Set up automatic replies (out of office) with custom messages for internal and external senders
  • Schedule automatic replies for specific date ranges

Troubleshooting​

Insufficient Privileges Error​

Cause: The application doesn't have the required permissions, or admin consent hasn't been granted.

Solution:

  1. Verify that you've added all necessary Microsoft Graph permissions in the Azure portal
  2. Check if any permissions require admin consent
  3. Ask your tenant administrator to grant admin consent
  4. Ensure the user authorizing the app has a valid mailbox

Cannot Send Emails​

Cause: Missing Mail.Send permission or the user's mailbox is restricted.

Solution:

  1. Ensure the app has the Mail.Send permission
  2. Verify the user has a licensed Exchange Online mailbox
  3. Check if there are any transport rules blocking outbound mail
  4. Verify the recipient addresses are valid

Search Returns No Results​

Cause: The search index may not have processed recent messages, or the query syntax is incorrect.

Solution:

  1. Allow a few minutes for newly received messages to be indexed
  2. Use simple keyword searches first before trying KQL syntax
  3. Check that the search query doesn't have syntax errors
  4. Try searching in a specific folder vs. across all folders

Access Token Has Expired​

Cause: The OAuth access token has expired (typically after 1 hour).

Solution:

  • Ensure offline_access scope is included to enable automatic token refresh
  • The connector should automatically refresh tokens using the refresh token

AADSTS65001: User Has Not Consented​

Cause: The user hasn't consented to the requested permissions.

Solution:

  1. If you're an admin, grant admin consent in the Microsoft Entra admin center
  2. If not an admin, contact your IT administrator to grant consent
  3. Reduce the requested scopes to only those you need

Best Practices​

Permissions​

  • Principle of Least Privilege: Only request the scopes your application actually needs
  • Start with Mail.Read and Mail.Send, add Mail.ReadWrite only if you need folder/draft management
  • Use MailboxSettings.Read instead of ReadWrite if you only need to view settings

Rate Limits​

  • Microsoft Graph has throttling limits; implement retry logic for 429 responses
  • Avoid polling for new messages too frequently; consider webhooks for real-time notifications
  • Use $select to request only the fields you need, reducing response size

Security​

  • Never expose client secrets in client-side code or version control
  • Store access tokens and refresh tokens securely
  • Rotate client secrets regularly (before they expire)
  • Audit application access periodically

API Reference​

This connector uses Microsoft Graph API v1.0 to interact with Outlook Mail. The base URL is https://graph.microsoft.com/v1.0.

Key endpoints used:

  • /me/messages - Message operations
  • /me/mailFolders - Folder operations
  • /me/sendMail - Send email
  • /me/mailboxSettings - Mailbox settings

For more information, see the Microsoft Graph Mail API documentation.

Limitations​

  • Attachment Size: File attachments in API requests are limited to 3MB base64-encoded. For larger attachments, use upload sessions (not yet supported)
  • Search Limitations: Full-text search may take a few minutes to index new messages
  • Rate Limiting: Microsoft Graph API has throttling limits; the connector does not currently implement retry logic for 429 responses
  • Shared Mailboxes: Accessing shared mailboxes requires additional configuration and permissions
  • Batch Operations: Bulk operations are executed sequentially; no batch API support currently

Additional Resources​