Prompt
I'm building a product that needs two-way sync with Outlook calendars
Latest observation
Two-way sync with Outlook calendars is very doable, but the right approach depends on what “Outlook calendars” means in your case:
- Microsoft 365 / Exchange Online calendars
- Outlook.com personal calendars
- On-prem Exchange
- Classic Outlook desktop client as the UI, but the actual calendar lives in one of the above
Recommended approach
Use the Microsoft Graph API. It’s the modern, supported way to read/write Outlook calendar data and handle sync.
What you typically need
- OAuth 2.0 / OpenID Connect for user sign-in
- Calendar permissions like:
Calendars.ReadWriteoffline_access
- Delta queries for incremental sync
- Webhooks / subscriptions for change notifications
- A conflict strategy for two-way edits
Core sync design
A reliable two-way sync usually looks like this:
1) Initial import
- Pull the user’s calendar events from Microsoft Graph
- Store:
- Microsoft event ID
changeKeyiCalUIdif useful- your internal object ID
- last sync cursor / delta token
2) Keep changes flowing in both directions
From Outlook to your app
- Subscribe to calendar change notifications
- When notified, use delta queries to fetch actual changes
- Update your local store
From your app to Outlook
- When the user creates/edits/deletes in your app, call Graph:
POST /eventsPATCH /events/{id}DELETE /events/{id}
- Save the new
changeKeyreturned by Microsoft
3) Conflict handling
Common options:
- Last write wins
- Outlook wins if Microsoft changeKey has advanced unexpectedly
- Field-level merge for some properties
- Show a conflict UI if both sides changed since last sync
Important technical details
Use delta sync
Graph supports delta queries for calendar events, which is much better than polling all events every time.
Typical pattern:
- First call: full sync
- Save the
@odata.deltaLink - Later calls: use the delta link to fetch only changes
Use notifications as a trigger, not the source of truth
Microsoft webhook notifications tell you “something changed,” but not exactly what. You still need to call delta queries to reconcile.
Handle recurring events carefully
Recurring meetings are one of the trickiest parts:
- Series master
- Exceptions
- Cancellations
- Instance edits
Make sure your data model supports recurrence properly.
Time zones
Outlook can store event times with time zones and daylight-saving behavior. Be careful to preserve:
- Start/end timezone
- Original local time
- Floating events if applicable
Identity mapping
You’ll want a mapping table like:
internal_event_idprovider = microsoftprovider_event_idprovider_calendar_idlast_synced_changeKeylast_synced_at
API endpoints you’ll likely use
GET /me/calendarsGET /me/calendars/{id}/eventsGET /me/events/{id}POST /me/eventsPATCH /me/events/{id}DELETE /me/events/{id}GET /me/calendars/{id}/events/deltaPOST /subscriptions
Things to watch out for
- Webhook expiration: subscriptions must be renewed
- Throttling: Graph may rate limit you
- Permissions/admin consent: some orgs require admin approval
- Shared calendars: behavior can differ depending on permissions
- Deleted items: delta queries report removals, which you should process
If you want the simplest reliable architecture
- OAuth login with Microsoft
- Full import of calendar events
- Store Graph IDs and delta token
- Webhook subscription for “calendar changed”
- Delta sync after notifications
- Push local edits to Graph immediately
- Background retry queue for failures/conflicts
Alternative options
If you need to support environments where Microsoft Graph is not enough:
- Exchange Web Services (EWS) for legacy/on-prem Exchange, but it’s deprecated in many scenarios
- CalDAV is generally not the right route for Outlook/Microsoft 365
Security/compliance notes
- Request only the minimum scopes you need
- Encrypt stored tokens
- Support token refresh securely
- Be mindful of tenant restrictions and enterprise review requirements
If you want, I can help you with one of these next:
- A reference architecture for two-way Outlook sync
- A database schema for syncing events
- Example Microsoft Graph API calls
- A conflict resolution strategy for edits/deletes