DocsMicrosoft Integration

Microsoft Integration

Send emails via Outlook and read calendar events from your AI agents. 30-second setup.

Download

Quick Start

Terminal

$co auth microsoft

What happens:

Opens browser to Microsoft OAuth consent screen
You authorize Mail + Calendar permissions
Credentials saved to .env (both local and global ~/.co/keys.env)
Ready to use Outlook and Calendar tools immediately

That's it. Your agents can now send emails via Outlook and read your Microsoft calendar.

Prerequisites

Before running co auth microsoft, you must authenticate with OpenOnion:

Terminal

$co auth

This creates your OPENONION_API_KEY which is required for Microsoft OAuth to work.

What Gets Saved

After successful authentication, your .env file contains:

.env

# Microsoft OAuth Credentials
MICROSOFT_ACCESS_TOKEN=eyJ0eXAi...
MICROSOFT_REFRESH_TOKEN=0.ATcA...
MICROSOFT_TOKEN_EXPIRES_AT=2025-12-31T23:59:59
MICROSOFT_SCOPES=Mail.Read,Mail.Send,Calendars.Read,Calendars.ReadWrite
MICROSOFT_EMAIL=your.email@outlook.com

Security notes

•Credentials are saved to both local .env and ~/.co/keys.env
•File permissions set to 0600 (read/write for owner only) on Unix systems
•Access tokens expire, but refresh tokens allow automatic renewal
•You can revoke access anytime via Microsoft Account settings

Permissions Requested

When you run co auth microsoft, we request these Microsoft Graph API scopes:

Scope	Purpose	What agents can do
Mail.Read	Read user emails	Read inbox, search emails
Mail.Send	Send emails on your behalf	Send emails via Outlook
Calendars.Read	Read calendar events	Read your calendar to check availability
Calendars.ReadWrite	Create/modify events	Create and update calendar events
User.Read	Get your profile	Identify which Microsoft account is connected

Privacy First

We only request the permissions needed. We cannot:

✕Delete your emails
✕Access your OneDrive or other services
✕Access your contacts beyond basic profile

Using Microsoft OAuth in Agents

Once authenticated, your agents can use Microsoft-powered tools:

Send Email via Outlook

outlook_agent.py

from connectonion import Agent, Outlook

outlook = Outlook()

agent = Agent(
    "Outlook Assistant",
    tools=[outlook]
)

agent.input("Send an email to alice@example.com saying hello")

Read Calendar Events

calendar_agent.py

from connectonion import Agent, MicrosoftCalendar

calendar = MicrosoftCalendar()

agent = Agent(
    "Calendar Assistant",
    tools=[calendar]
)

agent.input("What's on my calendar this week?")

Outlook Tool Methods

The Outlook tool provides these capabilities:

outlook_methods.py

from connectonion import Outlook

outlook = Outlook()

# Reading emails
outlook.read_inbox(last=10, unread=False)  # Get recent inbox emails
outlook.get_sent_emails(max_results=10)    # Get sent emails
outlook.search_emails("quarterly report")   # Search all emails
outlook.get_email_body(email_id)           # Get full email content

# Sending emails
outlook.send(to="alice@example.com", subject="Hello", body="Hi there!")
outlook.send(to="alice@example.com", subject="Hello", body="Hi!", cc="bob@example.com")
outlook.reply(email_id, body="Thanks for your message")

# Actions
outlook.mark_read(email_id)     # Mark email as read
outlook.mark_unread(email_id)   # Mark email as unread
outlook.archive_email(email_id) # Move to archive folder

# Stats
outlook.count_unread()          # Count unread emails in inbox
outlook.get_my_email()          # Get connected Microsoft email address

Microsoft Calendar Tool Methods

The MicrosoftCalendar tool provides:

calendar_methods.py

from connectonion import MicrosoftCalendar

calendar = MicrosoftCalendar()

# Reading events
calendar.list_events(days_ahead=7, max_results=20)  # Get upcoming events
calendar.get_today_events()                          # Get today's events
calendar.get_event(event_id)                         # Get event details

# Creating events
calendar.create_event(
    title="Team Meeting",
    start_time="2025-01-15 14:00",
    end_time="2025-01-15 15:00",
    description="Weekly sync",
    attendees="alice@example.com,bob@example.com",
    location="Conference Room A"
)

# Create Teams meeting (with auto-generated meeting link)
calendar.create_teams_meeting(
    title="Project Sync",
    start_time="2025-01-15 14:00",
    end_time="2025-01-15 15:00",
    attendees="alice@example.com,bob@example.com"
)

# Updating & deleting
calendar.update_event(event_id, title="Updated Title")
calendar.delete_event(event_id)

# Meetings & availability
calendar.get_upcoming_meetings(days_ahead=7)   # Get events with attendees
calendar.find_free_slots("2025-01-15", duration_minutes=60)  # Find free time
calendar.check_availability("2025-01-15 14:00")  # Check if specific time is free

Troubleshooting

"Not authenticated with OpenOnion"

You need to run co auth first to get your OPENONION_API_KEY:

Terminal

$co auth

$co auth microsoft

Authorization Timeout

If the browser window doesn't complete authorization within 5 minutes:

Terminal

$co auth microsoft

The command polls the backend every 5 seconds waiting for your authorization.

Credentials Not Working

Check if credentials are properly saved:

terminal

# Check local .env
cat .env | grep MICROSOFT_

# Check global keys
cat ~/.co/keys.env | grep MICROSOFT_

If credentials exist but don't work, re-authenticate:

Terminal

$co auth microsoft

Revoke Access

To disconnect your Microsoft account:

1.Go to Microsoft Account Permissions
2.Find "OpenOnion" and click "Remove"

Google vs Microsoft

Both integrations follow the same CLI pattern:

Feature	Google	Microsoft
Command	co auth google	co auth microsoft
Email	Gmail	Outlook
Calendar	Google Calendar	Microsoft Calendar
API	Google APIs	Microsoft Graph API

Google Integration

WebFetch