Outlook Calendar and Email

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.

Outlook Calendar tools

Enable agents to list, create, update, and delete calendar events 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 john@example.com 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 sarah@example.com 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."

Outlook Email tools

Twenty tools, grouped below by what they do. Most take an email_id returned by one of the listing or search tools.

Reading and finding

• list_emails — list recent emails from a folder. Takes folder (default inbox), max_results (default 20, max 100), unread_only, and skip for pagination. Returns id, subject, from, date, and a snippet.
• list_email_headers — a much lighter listing that returns only id, subject, from, and date. No body preview, CC, or attachment info. Use it when scanning a large mailbox.
• get_email — full content of one email. Optionally mark_as_read.
• get_email_bodies — truncated plain-text bodies for up to 10 emails in one call, with max_body_length (default 3000 chars). Saves a round trip per message.
• get_email_thread — every message in a conversation, oldest first, with HTML stripped. Up to 50.
• search_emails — search with KQL syntax, for example from:user@example.com, subject:report, or hasAttachments:true.
• match_emails — fuzzy match against subject and sender using local scoring, consuming no LLM tokens. Cheaper than asking an agent to sift results itself.
• get_unread_count — unread and total count for a folder.

Sending and replying

• send_email — requires to, subject, and body. Optional cc, bcc, is_html, importance (low/normal/high), save_to_sent (default true), and attachment_urls (up to 10 file URLs).
• reply_email — reply to a message. Optional reply_all, plus extra cc and bcc.
• forward_email — forward to new recipients, with an optional comment added above the forwarded content.

Drafts

• create_draft — save an email without sending it. Same fields as send_email.
• list_drafts — list saved drafts, paginated.
• send_draft — send an existing draft by draft_id.

Attachments

• list_attachments — list the attachments on an email.
• download_attachment — download attachment content as base64. Limited to 25MB by default (MAX_ATTACHMENT_DOWNLOAD_SIZE_MB).

Organising the mailbox

• mark_emails — bulk mark up to 50 emails read or unread.
• move_email — move to another folder, by well-known name (inbox, archive, deleteditems, junkemail) or a folder ID.
• delete_email — move an email to Deleted Items.
• list_folders — list folders with unread and total counts. Use the returned IDs with move_email.

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. List existing events with the Outlook calendar tool to see what is already booked
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 john@example.com and sarah@example.com
sometime next week to discuss Q1 planning. Make it a Teams meeting.

The agent will:

1. Use list_events over next week to see what is already on the calendar
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: ["john@example.com"]
• 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

Next steps