MailDesk docs
Get MailDesk
Pro

Outlook / Microsoft 365 realtime push setup (administrator)

Turn on provider-native push for an Outlook or Microsoft 365 mailbox so that new mail arrives in MailDesk in seconds instead of waiting for the next scheduled sync. MailDesk subscribes to Microsoft Graph change notifications: Microsoft notifies your server the moment a mailbox changes, and MailDesk runs an immediate sync for just that mailbox.

6 min read Pro

Turn on provider-native push for an Outlook or Microsoft 365 mailbox so that new mail arrives in MailDesk in seconds instead of waiting for the next scheduled sync. MailDesk subscribes to Microsoft Graph change notifications: Microsoft notifies your server the moment a mailbox changes, and MailDesk runs an immediate sync for just that mailbox.

Available in: Pro. Outlook realtime push is part of the MailDesk Pro module — it is not present in Basic, which always uses scheduled background sync. Push reuses the mailbox's existing Microsoft Graph connection and asks for no new permissions beyond those MailDesk already uses for two-way Outlook sync.

Status — near-release (4.2.0), not yet in shipped builds

Outlook realtime push ships in MailDesk Pro 4.2.0. At the time of writing it lives on the source branch MailDesk-889-realtime-sync-v18 and is tracked by merge request !124 (Pro). It is complete and test-covered but has not yet been merged into the released 18.0 line, so the setup described here will appear once 4.2.0 is installed. Until then, every mailbox keeps receiving mail on the regular automatic sync schedule.

Honest expectation on speed

With push enabled, new Outlook mail typically appears in MailDesk in about 3 to 13 seconds. This is genuine provider push — Microsoft notifies MailDesk when mail changes — but it is not instantaneous: the notification has to travel to your server and trigger a short sync. MailDesk does not claim "instant" delivery.

What it does

Microsoft Graph lets your server subscribe to changes in a mailbox. When you register a subscription, Graph first sends a one-time validation request to your webhook to confirm it is really yours; after that, Graph posts a small notification every time mail is created or updated. MailDesk's webhook verifies each notification and triggers the normal Outlook sync for that mailbox.

The notification does not carry the email itself. It only tells MailDesk "this mailbox changed" — MailDesk then runs its usual incremental fetch and updates the inbox. Push therefore shortens the delay; it does not replace the proven sync engine behind it.

Why it matters

  • Faster mail. New messages surface in seconds rather than waiting for the next scheduled sync.
  • Nothing to type. Unlike the Gmail setup, the Outlook assistant collects no values from you — every setting it needs already comes from the mailbox's existing Microsoft Graph connection.
  • Safe fallback. If push ever stops arriving, MailDesk automatically falls back to its scheduled background sync, so no mail is ever lost — push only ever makes things faster.

Requirements

  • An Outlook or Microsoft 365 mailbox already connected to MailDesk over Microsoft Graph OAuth and syncing. See Outlook / Microsoft 365 OAuth setup first. The connection must be a Graph connection — a classic Outlook IMAP/SMTP connection cannot receive Graph push.
  • Your Odoo server reachable over HTTPS at a stable public address. Microsoft will only send the validation handshake and notifications to an https:// URL with a valid certificate. Plain http:// and local-only addresses cannot receive push.
  • MailDesk Pro 4.2.0 installed (see the status note above).
  • MailDesk works on Odoo 17, 18, or 19 — the steps below are the same on each.

Use the Graph connection, not the IMAP one

Microsoft offers two different kinds of mailbox access. A token issued for classic IMAP/SMTP access cannot call Graph subscriptions. MailDesk checks this for you: if the mailbox is connected with an IMAP-only Microsoft token, the assistant blocks registration and asks you to reconnect the mailbox using the Microsoft Graph option.

Permissions required

  • Configuring Outlook realtime push is restricted to MailDesk administrators (the Mailbox administrator access group). The assistant refuses to register a subscription for a user without that access.

  • The secret that authenticates incoming notifications is visible only to MailDesk administrators and is rotated every time a subscription is registered.

Step 1 — Open the Outlook push setup assistant

Open the Enable Microsoft 365 push notifications assistant for the Outlook mailbox you want to speed up, and confirm the mailbox is selected at the top.

The assistant is a single short screen. It shows:

  • the mailbox account the subscription will cover;
  • the webhook URL Microsoft will send notifications to (read-only, built from your public address);
  • a readiness check for this mailbox, with a clear reason if it is not yet ready.

Step 2 — Check readiness

The assistant verifies that the mailbox is connected over Microsoft Graph (not IMAP) and has a usable Graph token. If the readiness check passes, the Register Subscription button is available. If it does not pass, the screen shows the reason — most often that the mailbox needs to be reconnected with the Microsoft Graph option — and the button stays hidden until the issue is resolved.

Make sure the public URL is correct first

The webhook URL is built from Odoo's web.base.url. Before registering, confirm that value is your public HTTPS address with no trailing slash, under Settings → Technical → System Parameters. Microsoft's validation handshake must be able to reach it.

Step 3 — Register the subscription

Click Register Subscription. MailDesk:

  1. generates a fresh secret for this subscription;
  2. asks Microsoft Graph to create a subscription on the mailbox's messages, pointing at your webhook URL;
  3. Microsoft immediately sends a one-time validation request, which MailDesk's webhook answers automatically;
  4. on success, MailDesk stores the subscription id and its expiration date.

Expected result

The assistant shows the new subscription id and its expiration date, and the mailbox begins receiving push notifications. New Outlook mail appears in MailDesk within a few seconds. The subscription is renewed automatically before it expires, so you do not need to repeat this setup.

Renewal is automatic

A Microsoft Graph mailbox subscription is short-lived. MailDesk registers it for about 6 days and renews it automatically with roughly a day to spare, using a scheduled background job, so push keeps running without any further action.

Troubleshooting

Symptom Likely cause What to do
"Register Subscription" button is missing The readiness check did not pass Read the reason shown on the screen; usually the mailbox must be reconnected with the Microsoft Graph option
Readiness reason mentions IMAP / wrong token The mailbox is connected with a classic Outlook IMAP/SMTP token, which cannot call Graph Reconnect the mailbox using the Microsoft Graph (OAuth) option, then re-open the assistant
Registration fails with a Graph error Microsoft could not validate the webhook, or the token lacks the right access Confirm web.base.url is your public HTTPS address and that the mailbox's Graph authorization is current; reconnect if needed, then retry
Validation handshake fails Microsoft could not reach your webhook over HTTPS Confirm the public address resolves and serves a valid TLS certificate; check any firewall or reverse proxy in front of Odoo
No mail appears after enabling A notification was missed MailDesk automatically falls back to scheduled sync, so mail still arrives within the normal sync interval; the subscription is re-checked automatically

Push never blocks normal sync

Realtime push sits on top of MailDesk's scheduled background sync. If notifications are ever delayed or missed, MailDesk notices the silence and runs a catch-up sync automatically. Push only ever makes mail arrive sooner — it can never make it arrive late.