Connect Outlook

This guide explains how to connect an Outlook.com or Microsoft 365 mailbox to MailDesk correctly.

MailDesk uses OAuth 2.0 and Microsoft Graph — not classic IMAP — for secure access and reliable synchronization.

However, authorization alone is not enough: incoming and outgoing servers and folders must still be configured.

When should you use this guide?

Use this guide if you use:

• Outlook.com

• Microsoft 365 (Exchange Online)

• Business email hosted on Microsoft

⚠️ If Outlook OAuth is available, it is strongly recommended over IMAP.

How Outlook connection works (important)

MailDesk connects to Outlook using:

• OAuth 2.0 (Microsoft sign-in)

• Microsoft Graph API

• Delta synchronization for efficient updates

✔ Your Outlook password is never stored
✔ Access can be revoked at any time
✔ Enterprise-ready authentication

⚠️ OAuth grants access, but does not automatically configure synchronization.

Step-by-step: Connect Outlook

Step 1 — Open Mailbox Accounts

1. Open MailDesk

2. Click Settings (⚙️)

3. Open Mailbox Accounts

4. Click Create

Step 2 — Create the mailbox account

1. Choose Outlook

2. Enter:

   • Account Name (internal)

   • Email Address

   • Sender Name

3. Click Save

At this stage, the mailbox exists but is not yet synchronized.

Step 3 — Authorize Outlook (OAuth)

1. Click Authorize Outlook

2. You will be redirected to Microsoft

3. Sign in with your Microsoft account

4. Review permissions and click Accept

5. You are redirected back to MailDesk

OAuth access is now granted.

Step 4 — Create and confirm email servers (required)

OAuth only grants access to Outlook.

You must manually create and confirm the email servers in Odoo.

Why two servers are required

• Incoming Mail Server → receives emails from Outlook

• Outgoing Mail Server → sends emails via Outlook

Both must be configured and tested separately.

4.1 Create Incoming Mail Server

In Odoo search, type Incoming Mail Servers

1. Click Create
2. Choose server type: Outlook OAuth / Microsoft Graph
3. Select the Outlook account you authorized
4. Click Test & Confirm

Result must be:

• Status = Confirmed

• No error message

• After synchronization starts, Last Fetch Date will update

⚠️ If Incoming remains Not Confirmed, MailDesk will not receive emails.

💡 If you cannot find “Incoming Mail Servers”, enable Developer Mode or ask your Odoo administrator.

4.2 Create Outgoing Mail Server

In Odoo search, type Outgoing Mail Servers

1. Click Create
2. Choose server type: Outlook / Microsoft 365
3. Select the authorized Outlook account
4. Click Test

If the test succeeds, sending is configured correctly.

⚠️ If Outgoing is missing or fails, emails cannot be sent.

Only after both servers are confirmed, continue with:

→ Fetch folders

→ Select folders

→ Start synchronization

Step 5 — Fetch folders (required)

Click Fetch Folders in the mailbox account header.

What this does:

• Connects to Microsoft Graph

• Reads available Outlook folders

• Makes them selectable for synchronization

⚠️ Without fetching folders, no emails will be synchronized.

Step 6 — Select folders to sync

Go to the Folders tab and select which folders to synchronize.

Recommended minimum:

• Inbox

• Sent Items

Optional:

• Drafts

• Deleted Items

• Archive

💡 Sync only what you need — fewer folders = faster sync.

Step 7 — Initial synchronization (how it works)

Outlook synchronization works per folder:

• Sync starts after folders are selected

• Newest emails are fetched first

• Older emails are loaded progressively (backfill)

• Full email bodies are fetched when you open a message

⏳ Large Outlook mailboxes may take time to fully backfill
⚠️ This is expected behavior

Outlook folders (behavior)

Outlook uses real folders.

This means:

• Each email belongs to one folder at a time

• Moving an email changes its folder

• Sent, Drafts, and Deleted Items behave exactly like Outlook

This differs from Gmail labels.

Sending emails with Outlook

When you send an email from MailDesk:

1️⃣ The email is sent immediately
2️⃣ It appears in Sent Items right away (local entry)
3️⃣ Outlook stores its own copy
4️⃣ The next sync replaces the local entry

This prevents duplicate sent messages.

Step 8 — Test your setup

Verify everything works:

1️⃣ Send an email to yourself
2️⃣ Check Sent Items (appears immediately)
3️⃣ Wait for the email to arrive in Inbox
4️⃣ Reply and verify the conversation stays together

If all steps work — the setup is complete 🎉

Common issues & quick fixes

“OAuth not configured”

• Azure App Registration is missing

• Required Microsoft Graph permissions not granted

• Admin consent not completed

Emails appear slowly

• Sync runs periodically (near real-time)

• Microsoft Graph rate limits may apply

• Short delays are normal

Old emails are missing

• Initial sync uses progressive backfill

• Leave MailDesk open and allow sync to finish

Sync stopped after inactivity

• Microsoft Graph delta tokens can expire

• MailDesk automatically re-bootstrap when needed
  
  
  

Privacy & revoking access

You can revoke MailDesk access at any time:

• Remove the mailbox account in MailDesk

• Or revoke the app’s access in Microsoft Entra / Azure AD

No password change required.

What’s next?

Now that Outlook is fully connected:

→ Explore Daily use
→ Organize emails with tags and folders
→ Check Troubleshooting if needed

Tip

If you manage multiple Outlook or Microsoft 365 accounts, configure and verify them one by one.