owa-outlook_skill

Overview

This skill reads enterprise Microsoft 365 Outlook calendars and mailboxes so an agent can answer questions about schedules, meetings, tasks, and email status. It integrates with Outlook Web Access flows, handles MFA, and caches tokens and cookies to maintain sessions. The skill is focused on actionable calendar and inbox queries for work contexts.

How this skill works

The skill uses a headless browser flow and API calls to fetch calendar and mail data from Microsoft 365. It stores authentication artifacts (config, cookies, and tokens) outside the skill directory and automatically renews bearer tokens; cookie expiry triggers an MFA re-login where the user approves a number shown in their authenticator. Calendar times are returned in UTC and should be converted to the desired timezone (example: +8 for Shanghai).

When to use it

• Answer 'What's on my calendar today/tomorrow/this week?' questions
• List upcoming meetings, times, and participants for planning
• Check for new or unread emails in Inbox or specific folders
• Search emails by keyword, sender, or date range
• Export recent messages or calendar ranges in JSON for automation

Best practices

• Keep sensitive credentials and cookie/token files under ~/.outlook/ with proper filesystem permissions
• Convert UTC timestamps to local timezone before presenting to users
• Limit mailbox queries (use --limit) to reduce API load for large inboxes
• Use the built-in search and folder flags to scope queries and protect privacy
• Refresh MFA-enabled login only when prompted; approve the authenticator code promptly

Example use cases

• User asks: 'Do I have any meetings this afternoon?' — return calendar items for the afternoon range
• Agent checks: 'Show unread emails from this morning' — list unread messages with sender and subject
• Manager request: 'Get my team's calendar for the week' — aggregate shared calendars or provide user's schedule
• Automation: 'Export March calendar range as JSON' — provide structured events for downstream processing
• Support: 'Search inbox for invoices from vendor@example.com' — return matched messages and dates