New integration: Microsoft outlook 🎉

[mvanders]

Description

Add Microsoft Outlook integration to sync emails, calendar events, contacts, and mail activity into CORE via Microsoft Graph API.

Reference Implementations

Existing Integrations (use as templates)

• integrations/gmail/ - Similar email integration (if exists)
• integrations/github/ - Similar OAuth and event-driven system
• integrations/slack/ - For messaging reference

Required Files Structure

integrations/outlook/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Microsoft Graph API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Microsoft Graph API (Outlook) Integration

OAuth Setup

• Use OAuth 2.0 (Authorization Code Grant) via Microsoft Identity Platform
• Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
• Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token
• Required scopes:
  • Mail.Read - Read user's mail
  • Mail.ReadWrite - Read and write user's mail
  • Mail.Send - Send mail on behalf of user
  • Calendars.Read - Read user's calendars
  • Calendars.ReadWrite - Read and write user's calendars
  • Contacts.Read - Read user's contacts
  • Contacts.ReadWrite - Read and write user's contacts
  • User.Read - Read user's profile
  • offline_access - Refresh token support
  • openid - OpenID Connect sign-in
  • profile - User profile info

Base URL

• https://graph.microsoft.com/v1.0
• Beta endpoint: https://graph.microsoft.com/beta

Key Endpoints

Mail

• GET /me/messages - List messages
• GET /me/messages/{id} - Get a message
• POST /me/messages - Create a draft message
• POST /me/sendMail - Send a message
• PATCH /me/messages/{id} - Update a message
• DELETE /me/messages/{id} - Delete a message
• GET /me/mailFolders - List mail folders
• GET /me/mailFolders/{id}/messages - List messages in a folder
• GET /me/mailFolders/inbox/messages - List inbox messages
• POST /me/messages/{id}/move - Move a message
• POST /me/messages/{id}/reply - Reply to a message
• POST /me/messages/{id}/replyAll - Reply all
• POST /me/messages/{id}/forward - Forward a message
• GET /me/messages?$search="subject:keyword" - Search messages

Calendar

• GET /me/events - List calendar events
• GET /me/events/{id} - Get an event
• POST /me/events - Create an event
• PATCH /me/events/{id} - Update an event
• DELETE /me/events/{id} - Delete an event
• GET /me/calendars - List calendars
• GET /me/calendarView?startDateTime={start}&endDateTime={end} - Get calendar view
• POST /me/events/{id}/accept - Accept event invitation
• POST /me/events/{id}/decline - Decline event invitation
• POST /me/events/{id}/tentativelyAccept - Tentatively accept

Contacts

• GET /me/contacts - List contacts
• GET /me/contacts/{id} - Get a contact
• POST /me/contacts - Create a contact
• PATCH /me/contacts/{id} - Update a contact
• DELETE /me/contacts/{id} - Delete a contact
• GET /me/contactFolders - List contact folders

Subscriptions (Webhooks)

• POST /subscriptions - Create a subscription for change notifications
• GET /subscriptions - List active subscriptions
• PATCH /subscriptions/{id} - Renew a subscription
• DELETE /subscriptions/{id} - Delete a subscription

Events to Track

1. Mail Events

   • Email received
   • Email sent
   • Email replied to
   • Email forwarded
   • Email moved to folder
   • Email deleted
   • Email read/unread status changed

2. Calendar Events

   • Event created
   • Event updated (time, location, attendees)
   • Event cancelled
   • Event invitation received
   • Event accepted/declined/tentative
   • Event reminder triggered

3. Contact Events

   • Contact created
   • Contact updated
   • Contact deleted

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts with Microsoft Identity Platform
• Create Microsoft Graph API utilities in utils.ts
• Implement sync logic in schedule.ts for mail, calendar, and contacts
• Set up Graph API subscriptions (webhooks) for real-time change notifications
• Convert Outlook events to CORE activity format
• Handle delta queries for efficient incremental sync
• Implement pagination with @odata.nextLink
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Microsoft Graph API v1.0 is the stable endpoint; beta has newer features but may change
• Use $select, $filter, $orderby, $top, $skip OData query parameters for efficient queries
• Delta queries (/me/messages/delta) enable efficient incremental sync without re-fetching all data
• Subscriptions (webhooks) require a publicly accessible HTTPS endpoint and must be renewed before expiry (max 3 days for mail, 3 days for events)
• Access tokens expire after ~1 hour; refresh tokens last 90 days (or longer with continuous use)
• Microsoft supports both delegated (user) and application (daemon) permission models
• Rate limiting: 10,000 API requests per 10 minutes per app per mailbox
• Multi-tenant app registration supports personal Microsoft accounts and work/school accounts
• $search parameter available for full-text search of mail messages

Resources

• Microsoft Graph API Overview
• Outlook Mail REST API
• Outlook Calendar REST API
• Microsoft Graph Auth Overview
• Graph API Permissions Reference
• Subscriptions / Change Notifications
• Delta Queries
• Compare Graph and Outlook REST endpoints

Labels

enhancement, integration, new-feature