Outlook / Microsoft 365 OAuth setup (administrator)

Connect Outlook.com and Microsoft 365 mailboxes to MailDesk using Microsoft's OAuth2 sign-in over the Microsoft Graph API. As with Gmail, no email password is stored in Odoo — Microsoft handles the login and returns a revocable token. This page is for the Odoo administrator who registers the application once for the company. Afterwards, each Outlook mailbox is authorized with a single Microsoft sign-in from inside MailDesk.

Connect Outlook.com and Microsoft 365 mailboxes to MailDesk using Microsoft's OAuth2 sign-in over the Microsoft Graph API. As with Gmail, no email password is stored in Odoo — Microsoft handles the login and returns a revocable token. This page is for the Odoo administrator who registers the application once for the company. Afterwards, each Outlook mailbox is authorized with a single Microsoft sign-in from inside MailDesk.

• Basic connects Outlook for reading and the engine's own actions, requesting Microsoft Graph Mail.Read access (plus offline refresh).
• Pro requests broader Microsoft Graph Mail.ReadWrite access (plus offline refresh) so it can perform two-way changes back to Outlook — marking read/unread, moving messages, and deleting. The Azure app registration is the same for both; Pro simply asks for the wider permission when a mailbox is authorized.

What it does

You register an application in Microsoft Entra ID (Azure Active Directory), create a client secret, grant the Microsoft Graph mail permission, and enter the application's Client Id and Client Secret into MailDesk. Connecting an Outlook mailbox is then a one-time Microsoft sign-in; MailDesk receives a token and a refresh token and never sees the password.

Why it matters

• No passwords stored, and access can be revoked from Microsoft at any time.
• Efficient delta sync over Microsoft Graph instead of legacy full-mailbox scanning.
• One company-wide setup: register the app once; users then authorize their own mailboxes.

Requirements

• A Microsoft Entra ID / Azure account that can create an app registration (Azure portal). For company mailboxes this is normally your Microsoft 365 tenant administrator.
• Your Odoo server reachable over HTTPS at a stable public address. Microsoft rejects OAuth redirects to plain http://.
• Administrator access to Odoo, including the technical settings.
• MailDesk works on Odoo 17, 18, or 19 — the steps below are the same on each.

Permissions required

• The Outlook credentials fields are restricted to Odoo Settings administrators (the Administration: Settings access group). Only such a user can view or change the Outlook Client Id and Secret.
• Creating mailbox accounts and authorizing them is available to MailDesk administrators.

Step 1 — Register the application in Azure

1. Open the Azure portal and go to Microsoft Entra ID (or Azure Active Directory) → App registrations.
2. Click New registration and give it a name (for example MailDesk).
3. Choose the supported account types:
   • Single tenant — recommended for a single organization; only your organization's users can authorize.
   • Multitenant — for multiple organizations.
   • Multitenant and personal Microsoft accounts — also allows Outlook.com / Hotmail sign-ins.

4. Under Redirect URI, choose platform Web and enter exactly:

   https://YOUR-ODOO-DOMAIN/microsoft_outlook/confirm
   

   Replace YOUR-ODOO-DOMAIN with your Odoo address — for example https://erp.example.com/microsoft_outlook/confirm.

5. Click Register.

On the registration's Overview page, copy the Application (client) ID. If you chose single tenant, also note the Directory (tenant) ID.

Step 2 — Create a client secret

1. In the app registration, open Certificates & secrets.
2. Click New client secret, give it a description, choose an expiry, and click Add.
3. Copy the secret Value immediately — Azure shows it only once. If you lose it, create a new one.

Step 3 — Add the Microsoft Graph permission

1. Open API permissions → Add a permission → Microsoft Graph → Delegated permissions.
2. Add the mail permission your deployment needs:
   • Mail.Read — sufficient for Basic.
   • Mail.ReadWrite — required for Pro's two-way changes (mark read, move, delete). Adding Mail.ReadWrite also covers reading, so a deployment that runs Pro can grant just Mail.ReadWrite.
3. The refresh permission (offline_access) is a standard OpenID Connect permission that MailDesk requests automatically during sign-in, so you do not need to add it here.

Step 4 — (Optional) Grant admin consent

If your organization requires administrator approval for delegated permissions, open API permissions and click Grant admin consent for [your organization]. Users can then authorize without each seeing an individual consent prompt. This is optional for personal accounts and for individual-consent testing.

Step 5 — Enter the credentials in MailDesk

MailDesk stores the Outlook Client Id and Secret per company. There are two equivalent places to enter them.

Option A — MailDesk settings

1. In Odoo, go to Settings, open the MailDesk section, and find the OAuth Settings block.
2. Turn on Use an Outlook Server.
3. Enter the Microsoft ID (the Application/client ID) and Secret from Steps 1–2.
4. Save.

The values you see and edit here belong to the company selected in the top-right company switcher.

Option B — Company form

1. Go to Settings → Users & Companies → Companies and open the company.
2. Open the Mail OAuth tab.
3. Under Outlook OAuth, fill in Outlook Client Id and Outlook Client Secret.
4. Save.

Step 6 — Check the Odoo base URL

MailDesk builds the redirect URI from Odoo's base URL, so it must match what you registered in Azure.

1. Go to Settings → Technical → System Parameters.
2. Find web.base.url. It should be your public HTTPS address with no trailing slash (for example https://erp.example.com).
3. Correct it if needed and save.

Step 7 — Connect and authorize an Outlook mailbox

1. Go to MailDesk → Configuration → Mailboxes → Mailbox Accounts and create a new account.
2. Set the account name and the Outlook email address, and link it to an Outlook incoming mail server. Save.
3. Click Connect Microsoft Graph (OAuth) in the form header. (This button appears only for Outlook accounts.)
4. Complete the Microsoft sign-in and accept the requested permissions. Microsoft returns you to the mailbox account in Odoo, and the mailbox begins syncing.

Expected result

After sign-in the mailbox connects and MailDesk starts an initial fill of the newest messages, then continues loading history in the background through its scheduled background jobs. New mail then arrives automatically on the regular sync schedule. On Pro, changes you make in MailDesk (read/unread, move, delete) are written back to Outlook.

Troubleshooting

Handling the Client Secret responsibly

• The Client Id and Secret are stored in the Odoo database and are visible only to Settings administrators. They are never written to logs.
• Treat the Secret like any credential: do not paste it into tickets, chat, or version control. Set a reminder to rotate it before it expires (Step 2), and replace it immediately after any suspected exposure.
• For separate dev / staging / production servers, register a separate app (or at least a separate redirect URI) per environment so each environment has its own credentials and isolated secret rotation.

Related

• Gmail OAuth setup
• IMAP / SMTP setup
• Mailbox setup
• Security & access rights
• Licensing & tiers
• Troubleshooting