Outlook Account Setup Guide

Critical: MailDesk Uses Microsoft Graph, Not Odoo's Outlook

MailDesk Outlook integration is SEPARATE from Odoo's built-in Outlook integration.

MailDesk uses:

• Microsoft Graph API (direct)
• Custom OAuth flow
• Custom token storage
• Delta sync for efficiency

Odoo's built-in Outlook (NOT used by MailDesk):

• IMAP/SMTP fallback
• Different OAuth scopes
• Different token storage

Important: If you configure "Outlook" in Odoo Settings, that is NOT for MailDesk. MailDesk has its own Outlook account type.

What is Microsoft Graph?

Microsoft Graph is the official API for Microsoft 365 and Outlook.com.

Benefits vs IMAP:

• Delta sync: Only fetches changes (like Gmail History API)
• Reliable: Built for applications, not legacy email clients
• Consistent: Works for Outlook.com and Microsoft 365

MailDesk uses Microsoft Graph for all Outlook accounts.

Prerequisites

Before connecting Outlook to MailDesk:

• ✅ Outlook.com or Microsoft 365 account
• ✅ Administrator must have configured Microsoft Graph OAuth
• ✅ Browser with access to your Microsoft account

Note: Administrator must create Azure App Registration first. See Admin Guide.

Step 1: Create Outlook Account in MailDesk

1. Open MailDesk app in Odoo
2. Click Settings (gear icon) → Mailbox Accounts
3. Click Create
4. Fill in:
   • Name: Descriptive name (e.g., "Work Outlook", "Personal")
   • Email Address: [email protected] or [email protected]
5. Click Save

Step 2: Authorize Microsoft Account

1. After saving, click Authorize Outlook button
2. Browser redirects to Microsoft login page
3. If not logged in: Enter your Microsoft credentials
4. If logged in: Microsoft shows account picker

What you'll see:

Microsoft Account Permissions Request

MailDesk wants to access your Microsoft Account

This will allow MailDesk to:
✓ Read your mail
✓ Send mail as you
✓ Access your mailbox even when you're not using MailDesk

[Cancel] [Accept]

1. Click Accept
2. Browser redirects back to MailDesk
3. Account status changes to "Connected"

What Permissions MailDesk Requests

Scope: https://graph.microsoft.com/Mail.Read

• Read emails (subject, sender, body, attachments)
• Access folder structure
• Read message properties (unread, importance, etc.)

Scope: offline_access

• Refresh access token without re-login
• Keep connection active long-term

Why these permissions?

• Mail.Read: Required to show your emails in MailDesk
• offline_access: Required to sync automatically (without clicking "Authorize" every hour)

Does MailDesk see my password? No. OAuth means Microsoft handles login. MailDesk only receives an access token.

What Happens After Connection

Immediate: Folder Discovery

MailDesk scans your Outlook folders:

Default Folders:

• Inbox → shown as "Inbox"
• SentItems → shown as "Sent"
• Drafts → shown as "Drafts"
• DeletedItems → shown as "Trash"
• JunkEmail → shown as "Spam" (usually not synced)

Custom Folders:

• Projects → "Projects"
• Archive → "Archive"

Note: Unlike Gmail, Outlook folders are real folders. One message, one folder (no multi-folder like Gmail labels).

Step 1: Bootstrap Sync (Newest Messages First)

Timeline: 5-30 seconds

What happens:

1. MailDesk fetches newest 50 messages from Inbox
2. Messages appear in MailDesk UI immediately
3. Other folders (Sent, Drafts) synced next

Why only 50? Bootstrap prioritizes instant usability. Older messages fetched progressively.

Step 2: Incremental Sync (New Messages)

Timeline: Every 5 minutes (automatic)

What happens:

1. MailDesk calls Microsoft Graph Delta API
2. Fetches only changes since last sync:
   • New emails
   • Deleted emails
   • Folder moves
   • Read/unread flag changes
3. Updates MailDesk SSOT
4. UI refreshes automatically

Delta API Explained:

• Microsoft Graph tracks changes with a deltaLink URL
• MailDesk stores deltaLink, fetches newer changes only
• Efficient: No need to scan entire mailbox

Step 3: Progressive Backfill (Older Messages)

Timeline: Background, over hours

What happens:

1. After bootstrap, MailDesk starts fetching older messages
2. Batch size: 200 messages per hour (controlled budget)
3. Older messages appear progressively
4. Continues until entire mailbox synced

Why slow?

• Prevents overwhelming Microsoft Graph API throttling
• Prioritizes recent emails
• Background: doesn't block UI

Example Timeline:

• 0-30 seconds: Newest 50 messages (Inbox)
• 5 minutes: Sent, Drafts synced
• 1 hour: 200 older messages fetched
• 5 hours: 1000 total messages synced
• 1 day: 5000+ messages synced

Outlook-Specific Behavior

Real Folders (Not Labels)

Important: Outlook folders are traditional IMAP-style folders.

One message, one folder:

• Email in Inbox → only in Inbox
• Move to Archive → no longer in Inbox, now in Archive

Different from Gmail:

• Gmail: One message can have multiple labels (appears in multiple folders)
• Outlook: One message, one folder at a time

User Impact: Moving messages removes from original folder.

Sent Mail Behavior

When you send email via MailDesk:

1. Immediately: Message appears in MailDesk Sent folder (local entry)
2. Background: Outlook automatically saves to SentItems folder
3. Next sync (within 5 minutes): Outlook's copy replaces local entry

Why local entry? Outlook takes 5-30 seconds to save sent mail. Local entry prevents "sent mail disappeared" UX.

Result: Sent mail always visible immediately.

Focused Inbox

Microsoft's Focused Inbox:

• Splits Inbox into "Focused" and "Other"
• Powered by machine learning

MailDesk behavior:

• MailDesk shows combined Inbox (Focused + Other)
• No separate "Focused" vs "Other" folders
• If you need this separation: Use Outlook webmail

Why: Graph API provides unified Inbox view. Focused/Other separation is UI-only in webmail.

Common Issues & Solutions

Issue: "OAuth Not Configured"

Symptoms: "Authorize Outlook" button shows error

Cause: Administrator hasn't configured Microsoft Graph OAuth

Solution: Contact your Odoo administrator. They must:

1. Create Azure App Registration
2. Configure delegated permissions (Mail.Read, offline_access)
3. Add credentials to Odoo

See: Admin Guide

Issue: "Messages Not Appearing Immediately"

Symptoms: Sent email in Outlook webmail, doesn't show in MailDesk

Cause: Sync runs every 5 minutes, not realtime

Solution:

• Wait 1-5 minutes for next sync cycle
• OR click Refresh icon in MailDesk

This is normal Graph API behavior (not a bug).

Issue: "Old Messages Loading Slowly"

Symptoms: Can only see recent emails, older messages missing

Cause: Progressive backfill in progress

Solution:

• Wait: Backfill fetches 200 messages/hour automatically
• Check tomorrow: Most mailboxes fully synced within 24-48 hours

This is intentional design (prevents API throttling).

Issue: "Delta Token Expired"

Symptoms: MailDesk shows "Full folder resync required"

Cause: Microsoft Graph Delta token expires after ~30 days of inactivity

What happens:

1. MailDesk detects expired deltaLink
2. Automatically resets folder
3. Re-bootstraps newest 50 messages
4. Progressive backfill restarts

User Impact: Brief delay (30-60 seconds), then normal sync resumes

Prevention: Use MailDesk at least once per month

Issue: "Re-Authorization Required"

Symptoms: "Outlook authentication expired, please re-authorize"

Cause: OAuth token revoked (password changed, admin revoked app, security policy)

Solution:

1. Go to Settings → Mailbox Accounts
2. Click your Outlook account
3. Click Re-Authorize Outlook
4. Log in again

Why: OAuth tokens can be revoked for security reasons. This is normal.

Issue: "Throttling Delays"

Symptoms: Sync slower than expected

Cause: Microsoft Graph enforces rate limits:

• 10,000 requests per 10 minutes per user (typical limit)
• Throttling: HTTP 429 with Retry-After header

What MailDesk does:

• Detects HTTP 429
• Exponential backoff (waits before retry)
• Silent: No error shown to user

User Impact: Slight sync delays during heavy usage

This is normal — Microsoft Graph protects servers from overload.

Unread Counts and Consistency

Eventually Consistent Unread Counts

Outlook unread counts in MailDesk are eventually consistent:

1. Sync runs every 5 minutes
2. Unread count updated at END of sync
3. Badge updates via websocket

Scenarios:

• Mark read in Outlook webmail → MailDesk badge updates within 5 minutes
• Mark read in MailDesk → Badge updates immediately (optimistic), confirmed by sync

This is intentional (balance between accuracy and performance).

Testing Your Setup

After connection, verify:

Test 1: Receive Email

1. Send email to yourself from another account
2. Wait 1-5 minutes (next sync cycle)
3. Check MailDesk Inbox → should appear

Test 2: Send Email

1. Compose email in MailDesk
2. Send
3. Check Sent folder → should appear immediately
4. Check recipient → should receive

Test 3: Folder Move

1. Move message to Archive in MailDesk
2. Check Inbox → message gone
3. Check Archive → message appears

Performance Expectations

Sync Speed

• New emails: Appear within 1-5 minutes (sync frequency)
• Sent emails: Appear immediately (local-first)
• Folder moves: Reflected within 1-5 minutes

Storage

• Metadata: Stored in Odoo database (~1KB per message)
• Full bodies: Cached for 7 days, re-fetched on demand
• Attachments: Fetched on first open, cached temporarily

API Quota

Microsoft Graph provides generous limits:

• 10,000 requests per 10 minutes per user
• Delta queries consume 1 request each
• Typical usage: 50-200 requests/day per user

Privacy & Security

What Microsoft Knows

• Microsoft knows MailDesk requested access to your mailbox
• Microsoft logs OAuth token grants
• Microsoft can revoke access anytime

What MailDesk Stores

• Access token: Stored encrypted in Odoo database
• Refresh token: Used to renew access automatically
• Delta link: URL for next sync query
• Metadata: Subject, sender, date (in message_index)
• Bodies: Cached temporarily (7-day TTL)

What MailDesk Does NOT Store

• ❌ Your Microsoft password (OAuth handles auth)
• ❌ Permanent email bodies (cached with expiry only)
• ❌ Attachment binaries (fetched on-demand)

Revoking Access

To disconnect MailDesk from Outlook:

1. In MailDesk: Delete account → Settings → Mailbox Accounts → Delete
2. In Microsoft: Revoke app access
   • Go to Microsoft Account Permissions
   • Find "MailDesk"
   • Click "Remove"

Effect: MailDesk can no longer access your Outlook. Existing cached data remains in Odoo.

MailDesk Outlook vs Odoo Outlook

They are NOT the same. Configuring "Outlook" in Odoo Settings does NOT configure MailDesk Outlook.

Outlook.com vs Microsoft 365

Both work with MailDesk:

Outlook.com (personal):

• Free Microsoft email (@outlook.com, @hotmail.com)
• OAuth tenant: common
• Works without organization admin

Microsoft 365 (business):

• Company email (@your-company.com via Microsoft 365)
• OAuth tenant: Your organization's tenant ID OR common
• May require admin consent (Enterprise Application)

MailDesk supports both — same setup process.

Next Steps

✅ Account connected → Read Daily Usage Guide to learn features (to be created)

✅ Need multiple accounts → Repeat setup for each Outlook account

✅ Having issues → See FAQ & Troubleshooting (to be created)

✅ Administrator setup → See Outlook Graph OAuth Setup Admin Guide