IntegrationsMicrosoft Integration
DocsMicrosoft Integration

Microsoft Integration

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

Quick Start

Terminalbash
$co auth microsoft

What happens:

  1. Opens browser to Microsoft OAuth consent screen
  2. You authorize Mail + Calendar permissions
  3. Credentials saved to .env (both local and global ~/.co/keys.env)
  4. 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:

Terminalbash
$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:

ScopePurposeWhat agents can do
Mail.ReadRead user emailsRead inbox, search emails
Mail.SendSend emails on your behalfSend emails via Outlook
Calendars.ReadRead calendar eventsRead your calendar to check availability
Calendars.ReadWriteCreate/modify eventsCreate and update calendar events
User.ReadGet your profileIdentify 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:

Terminalbash
$co auth
$co auth microsoft

Authorization Timeout

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

Terminalbash
$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:

Terminalbash
$co auth microsoft

Revoke Access

To disconnect your Microsoft account:

Google vs Microsoft

Both integrations follow the same CLI pattern:

FeatureGoogleMicrosoft
Commandco auth googleco auth microsoft
EmailGmailOutlook
CalendarGoogle CalendarMicrosoft Calendar
APIGoogle APIsMicrosoft Graph API
Previous
Integrations
Google Integration
Next
Useful Plugins
Useful Plugins

Star us on GitHub

If ConnectOnion saves you time, a ⭐ goes a long way — and earns you a coffee chat with our founder.