Skip to main content

​
Overview

Connect your agents to Outlook Calendar and Outlook Email for intelligent scheduling and email automation across Microsoft 365. Agents can manage calendars, schedule meetings, send emails, and interact with your Microsoft ecosystem on your behalf. This integration uses OAuth 2.0 with Azure AD for secure authentication. Users authorize access once, and MagOneAI handles token management and refresh automatically. All credentials are stored in HashiCorp Vault.

​
OAuth setup for Microsoft 365

Before agents can access Microsoft services, you need to configure Azure AD OAuth and users need to authorize access.
1

Configure Microsoft OAuth credentials

In the Admin Portal, navigate to Integrations → Microsoft 365. You’ll need to provide:
  • Azure AD Application (client) ID
  • Azure AD Client Secret
  • Azure AD Tenant ID
These are created by registering an application in the Azure Portal. The platform stores them securely in HashiCorp Vault.
2

Users authorize access through OAuth flow

When a user first uses a Microsoft tool, they’re redirected to Microsoft’s OAuth consent screen. They sign in with their Microsoft account and authorize MagOneAI to access their calendar and email.
3

Platform manages token storage and refresh

After authorization, MagOneAI stores the access token and refresh token in Vault. The platform automatically refreshes tokens before they expire — users never see authentication errors.
4

Agents can now access Microsoft services

Once authorized, agents can call Outlook Calendar and Email tools on behalf of the user. Credentials are injected at runtime when tools execute.
Azure AD app registration required: You need to register an application in Azure Portal with appropriate Microsoft Graph API permissions. See Microsoft’s documentation on app registration for Microsoft Graph.

​
Outlook Calendar tools

Enable agents to manage calendars, schedule meetings, and check availability across Microsoft 365.

​
List events

Retrieve calendar events for a specific date range. Parameters:
  • calendar_id (optional) — defaults to user’s primary calendar
  • start_time — ISO 8601 datetime for range start
  • end_time — ISO 8601 datetime for range end
  • max_results (optional) — maximum number of events to return
Returns: List of events with subject, start time, end time, attendees, location, and meeting details. Example use case: “Show me all my meetings this week so I can prepare.”

​
Create event

Create a new calendar event with title, time, attendees, location, and optional meeting link. Parameters:
  • calendar_id (optional) — defaults to user’s primary calendar
  • subject — event title
  • start_time — ISO 8601 datetime for event start
  • end_time — ISO 8601 datetime for event end
  • attendees (optional) — list of email addresses
  • body (optional) — event description/agenda
  • location (optional) — meeting location or room
  • is_online_meeting (optional) — whether to create a Teams meeting link
Returns: Created event details including event ID and Teams meeting link if requested. Example use case: “Schedule a 30-minute Teams meeting with [email protected] tomorrow at 2pm to discuss the quarterly report.”

​
Update event

Modify an existing calendar event. Parameters:
  • calendar_id (optional) — defaults to user’s primary calendar
  • event_id — ID of the event to update
  • subject (optional) — new event title
  • start_time (optional) — new start time
  • end_time (optional) — new end time
  • attendees (optional) — updated attendee list
  • body (optional) — new description
  • location (optional) — new location
Returns: Updated event details. Example use case: “Move my 3pm meeting to 4pm and add [email protected] as an attendee.”

​
Delete event

Remove a calendar event and send cancellation notices to attendees. Parameters:
  • calendar_id (optional) — defaults to user’s primary calendar
  • event_id — ID of the event to delete
Returns: Confirmation of deletion. Example use case: “Cancel my meeting with the client tomorrow.”

​
Check availability

Find free and busy times for one or more attendees using Microsoft’s availability service. Parameters:
  • attendees — list of email addresses to check
  • start_time — ISO 8601 datetime for range start
  • end_time — ISO 8601 datetime for range end
  • meeting_duration (optional) — required meeting duration in minutes
Returns: Free/busy information for each attendee with occupied time slots and suggested meeting times. Example use case: “When are John and Sarah both free next week for a 1-hour meeting?”
Microsoft Teams integration: When creating events with is_online_meeting: true, Outlook automatically generates a Teams meeting link and adds it to the calendar invite.

​
Outlook Email tools

Enable agents to send, read, search, and manage emails across Microsoft 365.

​
Send email

Compose and send an email with subject, body, recipients, and optional attachments. Parameters:
  • to — list of recipient email addresses
  • subject — email subject line
  • body — email body content (supports HTML)
  • cc (optional) — list of CC recipients
  • bcc (optional) — list of BCC recipients
  • attachments (optional) — list of file paths or URLs to attach
  • importance (optional) — email importance level (low, normal, high)
Returns: Sent message details including message ID. Example use case: “Send an email to the team with subject ‘Weekly Update’ and the report I just generated.”

​
Read email

Retrieve the content of a specific email by message ID. Parameters:
  • message_id — Outlook message ID
  • include_attachments (optional) — whether to include attachment content
Returns: Email content including sender, recipients, subject, body, and attachment metadata. Example use case: “Read the email from [email protected] that I received this morning.”

​
Search emails

Find emails matching specific search criteria using Microsoft Graph query syntax. Parameters:
  • query — search query (e.g., “from:[email protected] AND subject:invoice”)
  • folder (optional) — folder to search (defaults to all folders)
  • max_results (optional) — maximum number of results to return
Returns: List of matching emails with metadata. Example use case: “Find all emails from Sarah in the last week mentioning ‘budget’.”

​
List emails

Retrieve recent emails from inbox or specific folders. Parameters:
  • folder (optional) — folder name or ID (defaults to Inbox)
  • max_results (optional) — maximum number of emails to return
  • filter (optional) — OData filter expression (e.g., “isRead eq false”)
Returns: List of email messages with metadata. Example use case: “Show me the 10 most recent unread emails in my inbox.”

​
Reply to email

Send a reply to an existing email thread. Parameters:
  • message_id — ID of the message to reply to
  • body — reply body content (supports HTML)
  • reply_all (optional) — whether to reply to all recipients (defaults to false)
Returns: Sent reply details. Example use case: “Reply to that email from John saying we’ll have the report ready by Friday.”

​
Usage in workflows

Microsoft tools can be used in both Agent nodes (for intelligent, flexible execution) and Tool nodes (for deterministic execution).

​
Agent node example

System prompt: 
You are a scheduling assistant for Microsoft 365. When asked to schedule meetings:
1. Check the availability of all attendees using the Outlook calendar tool
2. Find a time slot that works for everyone
3. Create the calendar event with Teams meeting link if remote meeting
4. Send confirmation emails to all attendees with meeting details

Always suggest Teams meetings for remote participants.
User message: 
Schedule a 1-hour meeting with [email protected] and [email protected]
sometime next week to discuss Q1 planning. Make it a Teams meeting.
The agent will:
  1. Use check_availability to find when John and Sarah are both free
  2. Select an appropriate time slot
  3. Use create_event with is_online_meeting: true to schedule the meeting
  4. Use send_email to notify attendees with meeting agenda

​
Tool node example

For deterministic email sending, use a Tool node: Tool: Send email Parameters:
  • to: ["[email protected]"]
  • subject: "Weekly Report - {{date}}"
  • body: {{report_content}}
  • importance: high
The tool executes with exactly these parameters every time, using variable values from the workflow context.

​
Security and permissions

​
Microsoft Graph API permissions

The Microsoft 365 integration requires these delegated permissions in your Azure AD app registration:
  • Calendars.ReadWrite — read and write user calendars
  • Mail.Send — send emails on user’s behalf
  • Mail.Read — read user emails
  • Mail.ReadWrite — read and write user emails
  • OnlineMeetings.ReadWrite — create Teams meeting links
Users see these permissions when they authorize access through the OAuth consent screen.

​
Credential storage

All OAuth tokens are stored in HashiCorp Vault with:
  • Encryption at rest using AES-256
  • User-scoped access controls
  • Automatic key rotation
  • Audit logging for all token access
Tokens are retrieved from Vault only during tool execution and immediately discarded from memory after use.

​
Token refresh

Access tokens expire after 1 hour. MagOneAI automatically:
  1. Detects when a token is about to expire
  2. Uses the refresh token to obtain a new access token from Azure AD
  3. Updates the stored token in Vault
  4. Retries the failed tool call with the new token
Users never see “token expired” errors during workflow execution.

​
Multi-tenant considerations

If your organization uses multiple Microsoft 365 tenants, configure a separate integration for each tenant. Each tenant requires its own Azure AD app registration and OAuth configuration.

​
Troubleshooting

Symptoms: Users see error during Microsoft sign-in or authorization fails.Solutions:
  • Verify Azure AD Application ID, Client Secret, and Tenant ID are correct in Admin Portal
  • Check that redirect URIs are configured correctly in Azure AD app registration
  • Ensure the app has required Microsoft Graph API permissions
  • Verify admin consent has been granted if required by your organization
Symptoms: Events created by agents don’t appear in Outlook or Teams.Solutions:
  • Verify the user’s OAuth token has Calendars.ReadWrite permission
  • Check that the correct calendar ID is being used
  • Confirm timezone handling — use ISO 8601 format with explicit timezone
  • Wait a few minutes for sync across Microsoft services
Symptoms: Send email tool returns success but emails don’t arrive or arrive late.Solutions:
  • Check recipient email addresses are valid
  • Verify the user’s OAuth token has Mail.Send permission
  • Look in the user’s Sent Items folder to confirm emails were sent
  • Check recipient spam/junk folders
  • Microsoft may delay emails for security scanning — allow a few minutes
Symptoms: Tools fail with “throttling” or “too many requests” errors.Solutions:
  • Microsoft Graph API has rate limits per user and per application
  • Reduce the frequency of tool calls if hitting limits
  • Implement exponential backoff for retries (MagOneAI does this automatically)
  • Consider caching data instead of repeated queries
  • Request higher service limits from Microsoft if needed

​
Next steps

Google tools

Set up Google Calendar and Gmail integration

Custom MCP tools

Build your own tool integrations

Workflow builder

Design workflows that use Microsoft tools

Agent configuration

Learn how to attach tools to agents