Skip to main content

Microsoft Outlook Calendar

Microsoft Outlook Calendar is a scheduling and time management service that's part of Microsoft 365. This connector enables AI assistants to create, manage, and query calendar events, check availability, find meeting times, and manage multiple calendars through the Microsoft Graph API.

Authentication Types​

Microsoft Outlook Calendar supports OAuth 2.0 authentication via the Microsoft identity platform:

  • OAuth - Standard OAuth 2.0 authorization flow with PKCE
    • Pros: Secure delegated access, per-user calendar access, supports shared calendars, automatic token refresh
    • Cons: Requires Azure app registration, user consent needed
    • Best for: Production applications, scheduling automation, calendar management

Setting up OAuth​

1. Register an Application in Azure Portal​

  1. Go to Azure Portal

  2. Navigate to Microsoft Entra ID (formerly Azure Active Directory)

  3. In the left sidebar, click App registrations

  4. Click New registration

  5. Fill in the application details:

    • Name: Choose a descriptive name (e.g., "Webrix Outlook Calendar Integration")
    • Supported account types: Select the appropriate option:
      • "Accounts in this organizational directory only" for single-tenant apps
      • "Accounts in any organizational directory" for multi-tenant apps
      • "Accounts in any organizational directory and personal Microsoft accounts" for the widest support
    • Redirect URI: Select "Web" and enter:
      • For SaaS deployments: https://{org}.mcp-s.com/{org}/api/auth/callback
      • For On-Premise deployments: {connectUrl}/{org}/api/auth/callback

  6. Click Register

2. Configure API Permissions​

  1. In your app registration, click API permissions in the left sidebar

  2. Click Add a permission

  3. Select Microsoft Graph

  4. Choose Delegated permissions

  5. Add the following permissions based on your needs:

    Essential permissions:

    • User.Read - Sign in and read user profile
    • Calendars.Read - Read user calendars and events
    • offline_access - Maintain access to data (enables refresh tokens)

    For creating and managing events:

    • Calendars.ReadWrite - Create, update, and delete events and calendars

    For accessing shared calendars:

    • Calendars.Read.Shared - Read shared calendars
    • Calendars.ReadWrite.Shared - Manage shared calendars

  6. Click Add permissions

  7. Important: Click Grant admin consent for [Your Organization] if you have admin rights.

tip

The Calendars.Read.Shared and Calendars.ReadWrite.Shared permissions allow access to calendars that other users have shared with the authenticated user. These are useful for executive assistants or team scheduling scenarios.

3. Create Client Secret​

  1. In your app registration, click Certificates & secrets in the left sidebar

  2. Under Client secrets, click New client secret

  3. Add a description (e.g., "Calendar Connector Secret")

  4. Choose an expiration period (recommended: 12 months or 24 months)

  5. Click Add

  6. Important: Copy the secret Value immediately - it will only be shown once!

warning

Store the client secret securely. If you lose it, you'll need to create a new one.

4. Get Your Credentials​

You'll need these values to configure the connector:

  1. Application (client) ID: Found on the app registration Overview page
  2. Client Secret: The value you copied in the previous step

5. Configure in Webrix​

  1. In Webrix, paste the Client ID and Client Secret

  2. Select the scopes you need:

    • At minimum: User.Read, Calendars.Read, offline_access
    • For creating/managing events: Add Calendars.ReadWrite
    • For shared calendars: Add Calendars.Read.Shared and/or Calendars.ReadWrite.Shared

  3. Click Save Changes

  4. Click Connect to authorize the integration

Available Scopes​

Read Operations​

  • User.Read - Required for authentication; reads user profile information
  • Calendars.Read - Read-only access to the user's calendars and events
  • Calendars.Read.Shared - Read-only access to calendars shared with the user

Write Operations​

  • Calendars.ReadWrite - Full read/write access to calendars, events, and meeting responses
  • Calendars.ReadWrite.Shared - Full read/write access to shared calendars

Essential​

  • offline_access - Enables refresh tokens to maintain long-term access without re-authentication

Common Use Cases​

View Upcoming Schedule​

  • List events in a date range using calendar view (expands recurring events)
  • Get event details including attendees, location, and Teams meeting links
  • View events across multiple calendars

Schedule Meetings​

  • Create events with attendees, location, and Teams online meeting links
  • Use "Find Meeting Times" to discover when all attendees are available
  • Check free/busy availability with "Get Schedule"
  • Set reminders and show-as status (busy, tentative, free)

Manage Events​

  • Update event details (time, location, attendees)
  • RSVP to meeting invitations (accept, tentatively accept, decline)
  • Cancel/delete events with automatic attendee notifications
  • Reschedule events by updating start/end times

Calendar Organization​

  • List all user calendars (default, shared, group)
  • Create separate calendars for different purposes (work, personal, projects)
  • Delete calendars that are no longer needed

Availability Checking​

  • Check free/busy status for multiple users before scheduling
  • Find available time slots across a group of attendees
  • View schedule availability in configurable time intervals (15, 30, or 60 minutes)

Working with Time Zones​

Calendar events use time zones extensively. When creating or querying events:

  1. Always specify time zones when creating events using IANA time zone names (e.g., America/New_York, Europe/London, Asia/Tokyo)
  2. Calendar View requires UTC timestamps for the startDateTime and endDateTime parameters
  3. All-day events use date-only values without time components
  4. The connector defaults to UTC if no time zone is specified

Troubleshooting​

Insufficient Privileges Error​

Cause: The application doesn't have the required calendar permissions.

Solution:

  1. Verify that you've added Calendars.Read or Calendars.ReadWrite permissions
  2. Grant admin consent if required
  3. For shared calendars, ensure Calendars.Read.Shared or Calendars.ReadWrite.Shared is added

Cannot Create Events​

Cause: Missing Calendars.ReadWrite permission or the target calendar is read-only.

Solution:

  1. Ensure the app has the Calendars.ReadWrite permission
  2. Verify the user has a licensed Exchange Online mailbox
  3. Check if the target calendar allows write access (shared calendars may be read-only)

Find Meeting Times Returns No Results​

Cause: All potential time slots conflict with attendee schedules, or the search window is too narrow.

Solution:

  1. Expand the search window (use a wider date range)
  2. Reduce the required meeting duration
  3. Make some attendees optional instead of required
  4. Check that attendee email addresses are correct and within your organization

Recurring Events Not Showing​

Cause: Using "List Events" instead of "List Calendar View" which doesn't expand recurring events.

Solution:

  • Use the List Calendar View tool instead of List Events — it expands recurring event series into individual occurrences within the specified date range

Access Token Has Expired​

Cause: The OAuth access token has expired (typically after 1 hour).

Solution:

  • Ensure offline_access scope is included to enable automatic token refresh
  • The connector should automatically refresh tokens using the refresh token

Best Practices​

Permissions​

  • Principle of Least Privilege: Start with Calendars.Read and add Calendars.ReadWrite only when needed
  • Only request shared calendar permissions if your use case requires them
  • Use delegated permissions (not application permissions) for user-context operations

Scheduling​

  • Always use Find Meeting Times or Get Schedule before creating meetings with multiple attendees
  • Include time zones in all event creation requests to avoid confusion
  • Set appropriate reminders (default: 15 minutes before)
  • Use isOnlineMeeting: true to automatically generate Teams meeting links

Rate Limits​

  • Microsoft Graph has throttling limits; implement retry logic for 429 responses
  • Use $select to request only needed fields when listing events
  • Use calendar view with date range filters rather than listing all events

Security​

  • Never expose client secrets in client-side code or version control
  • Store tokens securely and rotate client secrets regularly
  • Audit application access periodically

API Reference​

This connector uses Microsoft Graph API v1.0 to interact with Outlook Calendar. The base URL is https://graph.microsoft.com/v1.0.

Key endpoints used:

  • /me/events - Event operations
  • /me/calendarView - Calendar view (recurring event expansion)
  • /me/calendars - Calendar management
  • /me/findMeetingTimes - Meeting time suggestions
  • /me/calendar/getSchedule - Free/busy availability

For more information, see the Microsoft Graph Calendar API documentation.

Limitations​

  • Recurring Events: Creating recurring events with complex patterns is not yet supported through the connector
  • Calendar Sharing: Creating new calendar sharing permissions is not supported; only accessing already-shared calendars
  • Attachment Support: Adding attachments to calendar events is not yet supported
  • Rate Limiting: Microsoft Graph API has throttling limits; the connector does not currently implement retry logic for 429 responses
  • Room Booking: Room/resource calendar booking requires additional configuration

Additional Resources​