org-outlook

Conquer your Microsoft Outlook agenda from the comfort of Emacs.

Disclaimer: org-outlook is currently in beta. Updates & responses to issues will be sporadic.

Contents

• Features
• Screenshots
• Installation
• Usage
• Changelog
• Notes

Features

• Integrated with org-roam
  • Find outlook events with org-roam-node-find
  • Refile outlook events to any file within org-roam-directory
  • Each recurring event instance has unique ID for individual refiling
• Accept and Decline meeting requests from the agenda buffer
• Join Teams calls directly from the agenda buffer (launches Teams or web browser)
• At-a-glance overview of your appointments and free timeslots when used with org-timeblock
• Org capture template to quickly plan meetings with Teams meeting integration
  • Automatic Teams meeting creation with join links
  • Availability checking for all invitees
  • Interactive conflict resolution

Planned features & improvements:

• Reduce the number of dependencies
• More configurability
• Two-way sync of event body (owned events only).

Future:

• Org contacts integration

Screenshots

Installation

Prerequisites

Upon first launch you will be asked to give org-outlook permission to read and write to your Outlook calendar. Note: Some organisations will have disabled third-party applications. In this case, unfortunately, you won’t be able to use org-outlook.

Dependencies

• gnupg: org-outlook requires you to have a public/private gpg keypair capable of encryption
• html2org
• org-ml
• org-msg
• emacs-request
• htmlize

Optional

A standard oauth client is provided with org-outlook, you are of course, free to use your own Microsoft Entra App Registration instead. To do so you will need to create an App Registration in Microsoft Entra (Formally Azure Active Directory) via https://portal.azure.com. Optionally make a note of your tenant-id (you can provide org-outlook-tenant-id to restrict the scope of your app to your Azure tenant).

Required API permissions:

• Calendars.Read - Read calendar events
• Calendars.ReadWrite - Create and modify calendar events
• offline_access - Maintain access when user is offline

Additional permissions for Teams meeting functionality:

• OnlineMeetings.ReadWrite - Create Teams meetings with join links
• Calendars.ReadBasic.All - Check availability of other users

Note: For Teams functionality, you may need to use the https://graph.microsoft.com/.default scope instead of individual permissions due to Microsoft Graph API limitations.

Under “Authentication” click Add a platform and add http://localhost:9004 as the redirect uri. At the bottom of the page ensure Allow public client flows is toggled to “Yes”. From the “Overview” tab copy the Application (client) id and insert into your config as specified below.

Quelpa

The package org-outlook is not currently available from MELPA, but can be installed directly from github with Quelpa.

Installing with Quelpa is easy:

1. Install quelpa-use-package (which can be installed directly from MELPA).
2. Add this form to your init file:

(use-package org-outlook
  :quelpa (org-outlook :fetcher github :repo "ifitzpat/org-outlook")
  :config
  ;; Optional: Use your own Microsoft Entra App Registration
  ;(setq org-outlook-client-id "client-id-of-your-registered-app")
  ;(setq org-outlook-tenant-id "your-azure-tenant-id")

  ;; Required settings
  (setq org-outlook-gpg-recipient "you@example.com")
  (setq org-outlook-local-timezone "Europe/Berlin") ; Your local time zone
  (setq org-outlook-file "/path/to/outlook.org")

  ;; Sync range (number of days)
  (setq org-outlook-sync-start 14)  ; days in the past to keep in sync
  (setq org-outlook-sync-end 90)    ; days in the future to keep in sync

  ;; Optional: Customize full sync frequency (default: 7 days)
  (setq org-outlook-full-sync-interval-days 7)  ; weekly validation
  ;(setq org-outlook-full-sync-interval-days 14) ; bi-weekly validation
  ;(setq org-outlook-full-sync-interval-days nil) ; disable automatic full syncs

  ;; Optional: Set your email for availability checking functions
  (setq org-outlook-user-email "your.email@company.com")
  )

Usage

• Commands
• Tips

Commands

• Syncing Outlook events:
  • M-x org-outlook-sync - Intelligent sync (uses delta sync when possible, falls back to full sync as needed)
  • C-u M-x org-outlook-sync - Force full sync (syncs all events regardless)
  • M-x org-outlook-full-sync - Direct full sync

  How sync works:

  • First run: Automatically performs full sync and initializes delta tracking
  • Daily use: Fast delta sync (only processes changes since last sync)
  • Weekly: Automatic full sync for validation (configurable with org-outlook-full-sync-interval-days)
  • Error recovery: Falls back to full sync if delta sync fails
  • Deleted events: Automatically removed during delta sync
• Accepting a meeting request:
  • With point on the entry in the agenda view or within the org entry body: org-outlook-accept-event
• Declining a meeting request:
  • With point on the entry in the agenda view or within the org entry body: org-outlook-decline-event
• Joining a Teams meeting:
  • With point on the entry in the agenda view or within the org entry body: org-outlook-join-teams-call
• Creating new meetings with org-capture:
  • C-c c o - Create new Outlook meeting using org-capture template
  • The template will prompt for:
    • Event title
    • Teams meeting (yes/no)
    • Invitees (space-separated email addresses)
    • Location
    • Meeting time (org timestamp format)
  • Upon finalization (C-c C-c), the system automatically:
    • Checks availability of all invitees
    • Warns if conflicts exist with options to continue, edit, or cancel
    • Creates Teams meeting with join link if Teams meeting was selected
    • Creates the event in Outlook if proceeding
• Checking availability:
  • M-x org-outlook-check-availability - Interactive availability check for multiple people
  • org-outlook-persons-available-p - Programmatic availability check (returns t/nil)
  • org-outlook-i-am-available-p - Check your own availability (requires org-outlook-user-email to be set)

  Example usage:

  ;; Set your email for convenience functions
  (setq org-outlook-user-email "your.email@company.com")
  
  ;; Check if you're free for a meeting
  (org-outlook-i-am-available-p "2025-11-30T14:00:00" "2025-11-30T15:00:00")
  
  ;; Check if multiple people are all available
  (org-outlook-persons-available-p '("person1@company.com" 
                                    "person2@company.com")
                                  "2025-11-30T14:00:00" 
                                  "2025-11-30T15:00:00")
  
  ;; Interactive availability report
  (org-outlook-check-availability '("colleague@company.com") 
                                 "2025-11-30T09:00:00" 
                                 "2025-11-30T17:00:00")
      

Tips

• Calling org-outlook-sync via emacs --batch avoids blocking your main emacs session.
• Creating meetings with org-capture workflow:
  1. Press C-c c o to start the capture template
  2. Enter event title when prompted
  3. Fill in the template:
     • INVITEES: Space-separated email addresses (e.g., john@company.com mary@company.com)
     • LOCATION: Meeting location
     • MEETING-TIME: Use org timestamp (e.g., <2025-12-01 Mon 14:00-15:00>)
  4. Press C-c C-c to finalize
  5. If conflicts are detected, choose from:
     • (c)ontinue anyway - Proceed despite conflicts
     • (e)dit capture - Return to edit invitees/time
     • (q)uit capture - Cancel the meeting creation
  6. If Teams meeting was selected:
     • Automatically creates Teams meeting with join link
     • Join link is included in the meeting body and org entry
  7. Meeting is automatically created in Outlook and synced to your org file

Changelog

Note: Breaking changes may be made before version 1.0, but in the event of major changes, attempts at backward compatibility will be made with obsolescence declarations, translation of arguments, etc. Users who need stability guarantees before 1.0 may choose to use tagged stable releases.

0.1.3-beta (2025-11-30)

New Features

• Teams meeting integration - Create Teams meetings directly from org-capture template
  • Set location to “Teams” to automatically create Teams meeting with join link
  • Join links are included in meeting body and org entry properties
• Comprehensive availability checking system
  • org-outlook-check-availability - Interactive availability reports
  • org-outlook-persons-available-p - Programmatic availability checking
  • org-outlook-i-am-available-p - Check your own availability (requires org-outlook-user-email)
• Enhanced org-capture template with conflict resolution workflow

Fixed Issues

• No issue number: Fixed buffer mode switching bug where any buffer would be switched to org-mode during event insertion

Breaking Changes

• Authentication scope change - Now uses https://graph.microsoft.com/.default scope for broader API access
• Token cache invalidation - Users must delete ~/.cache/outlook.plist and re-authenticate
• New API permissions required for Teams functionality:
  • OnlineMeetings.ReadWrite (Teams meeting creation)
  • Calendars.ReadBasic.All (availability checking)

0.1.2-beta (2025-11-29)

New Features

• org-capture-template now checks for attendee availability and allows you to edit the event if one or more attendees is not available

Fixed Issues

• No issue number: fix refresh token timeout

0.1.1-beta (2025-11-29)

Fixed Issues

• Issue #5: - browser does not launch on MacOS
• Issue #6 -AADSTS501491: Invalid size of Code_Challenge
• No issue number: current-buffer mode change

Breaking Changes

• org-outlook-code-challenge is now limited to 43 characters

0.1.0-beta (2025-11-20)

Major stability and reliability improvements:

Fixed Issues

• Issue #1 - DST Duplicates: Fixed duplicate events during daylight saving time transitions
  • Event IDs now use Outlook ID directly (stable across DST changes)
  • Fixed timestamp parsing to handle local timezone correctly
  • Added error handling for stale org-id cache
  • Each recurring event instance has unique, stable ID
• Issue #2 - Refresh Token: Fixed reversed logic that prevented automatic OAuth flow when refresh token expired
• Issue #3 - Auth Code Race Conditions: Removed blocking sleeps and race conditions from OAuth flow
  • Non-blocking authentication with 5-minute timeout (up from 90 seconds)
  • Proper async handling with state tracking
  • Better user feedback and error messages
• Issue #4 - Deleted Meetings: Implemented intelligent hybrid sync
  • Delta sync for fast daily syncs
  • Automatic full sync for periodic validation
  • Handles deleted and cancelled events properly
  • Self-healing with automatic error recovery

New Features

• Intelligent hybrid sync system (org-outlook-sync)
  • Fast delta sync by default
  • Weekly full sync validation (configurable)
  • Automatic fallback on errors
• New configuration variable: org-outlook-full-sync-interval-days
• Force full sync with prefix argument: C-u M-x org-outlook-sync

Breaking Changes

• org-outlook-sync behavior changed: now uses delta sync by default (was full sync)
• Old full sync is now org-outlook-full-sync
• Event IDs changed (will cause re-sync on first run)

0.0.5-alpha

Fix issue where request token times out

0.0.4-alpha

Fix hashing of PKCE code

0.0.3-alpha

Potential fix for duplicate event creation when going to/from DST

0.0.2-pre-alpha

Switch to PKCE oauth flow & provide default auth client

0.0.1-pre-alpha

Initial release

Notes

Known issues

• Accepting an event doesn’t change the event status from REQUEST to MEETING until the next sync.

Fixed in 0.1.2-beta

• ✅ fix refresh token time-out (fixed in 0.1.2)

Fixed in 0.1.1-beta

• ✅ AADSTS501491: Invalid size of Code_Challenge (fixed in 0.1.1)
• ✅ browser does not launch on MacOS (fixed in 0.1.1)
• ✅ current-buffer mode change (fixed in 0.1.1)

Fixed in 0.1.0-beta

• ✅ DST duplicate events (fixed in 0.1.0)
• ✅ Refresh token timeout handling (fixed in 0.1.0)
• ✅ OAuth authentication race conditions (fixed in 0.1.0)
• ✅ Deleted meetings not removed from org mode (fixed in 0.1.0)

License

GPLv3