Realtime sync (4.2.0) — what it means per provider
This page explains what "realtime" means in MailDesk, told honestly per email provider. The short version: Gmail and Outlook get genuine push (new mail in seconds), while IMAP gets an "autopilot" that polls intelligently and pre-loads message bodies so the inbox feels instant when you open it.
This page explains what "realtime" means in MailDesk, told honestly per email provider. The short version: Gmail and Outlook get genuine push (new mail in seconds), while IMAP gets an "autopilot" that polls intelligently and pre-loads message bodies so the inbox feels instant when you open it.
Status — 4.2.0 is near-release, not yet in the shipped build
The realtime work described here is complete and test-covered but not yet merged into the shipped
18.0 line. It lives on the development branches MailDesk-889-realtime-sync-v18 and
MailDesk-prefetch-cache-v18 (in both the engine and Pro repositories), tracked by merge requests
!237 and !124. Today's shipped builds (4.1.x) deliver new mail on the scheduled background
jobs described in Current stable behavior below. Treat the
4.2.0 section as forward-looking until those merge requests land.
Available in: Pro. The realtime layer is part of the Pro module — it extends the engine's scheduled sync, it does not replace it. The engine (Basic) provides the underlying inbound sync on its scheduled jobs; Pro adds push, IMAP autopilot, and body prefetch on top.
What it does
MailDesk keeps your inbox current without you pressing refresh. There are two distinct mechanisms, and it matters which one applies to your account:
- True push (Gmail, Outlook / Microsoft 365). The provider tells MailDesk the moment new mail arrives. MailDesk reacts within a few seconds — there is no waiting for the next scheduled run.
- IMAP autopilot (all other IMAP/SMTP accounts). Generic IMAP has no reliable "tell me when mail arrives" channel, so MailDesk does the next best thing: it studies what each server is capable of, polls at a sensible cadence, and pre-loads the bodies of the messages you are most likely to open next. New mail appears within the poll interval; opening a message is instant because the body is already cached.
In all cases, the open MailDesk screen also refreshes itself live over Odoo's websocket, so other tabs and teammates see changes promptly once a message has been ingested.
Why it matters
- Gmail / Outlook feel like a native mail app — new mail lands in seconds, not minutes.
- IMAP feels fast where it counts — the inbox you actually look at opens instantly, because bodies are warmed in the background.
- Nothing to babysit. IMAP autopilot is automatic with zero configuration. Push for Gmail is a guided, one-button setup. If push ever fails, MailDesk quietly falls back to scheduled sync — you never lose mail.
Be precise — what "realtime" means per provider
| Provider | Mechanism | Typical latency | Genuinely push? |
|---|---|---|---|
| Gmail | Google Cloud Pub/Sub topic + a watch on the mailbox; a secure webhook validates each notification and triggers the Gmail sync |
~3–8 seconds | Yes — push |
| Outlook / Microsoft 365 | Microsoft Graph change-notification subscription (with a verification secret); a secure webhook triggers the Outlook sync | ~3–13 seconds | Yes — push |
| IMAP | "Autopilot" capability profiling + smart polling + fetch-on-open body prefetch | poll interval; instant on open from cache | No — smart polling + prefetch |
Push shortens latency — it does not replace the engine
A push notification does not carry the email itself. It simply tells MailDesk "this account has new mail," which triggers the same delta-fetch and live-refresh pipeline the scheduled jobs use. So push makes mail arrive sooner; it does not change how messages are fetched, stored, or displayed.
Gmail — true push (guided one-button setup)
For Gmail and Google Workspace mailboxes, MailDesk sets up a Google Cloud Pub/Sub topic and a watch on
the mailbox. When mail arrives, Google posts a notification to a secure MailDesk webhook, which verifies it
and triggers an immediate Gmail sync.
Setup is a guided assistant on the mailbox account form: open the account in MailDesk → Configuration → Mailboxes → Mailbox Accounts and use the Configure Gmail Realtime button. The assistant walks you through a preflight check, a copy-and-paste Google Cloud Shell script, validation, and a live test. After setup, the same button becomes Manage Gmail Realtime so you can review the subscription and its expiry without re-running the script.
Outlook / Microsoft 365 — true push
For Outlook and Microsoft 365 mailboxes, MailDesk creates a Microsoft Graph change-notification subscription. Graph posts a notification (carrying a verification secret MailDesk checks) to a secure webhook, which triggers an immediate Outlook sync.
Outlook push setup surface (4.2.0)
On this branch the polished one-button assistant is wired onto the account form for Gmail. The Outlook push setup exists as a wizard ("Enable Microsoft 365 push notifications") and the webhook and renewal jobs are in place, but its entry point on the account form is less prominent than Gmail's. If you do not enable Outlook push, the mailbox simply keeps syncing on the scheduled jobs — nothing breaks.
IMAP — autopilot (no push, no configuration)
Generic IMAP servers vary wildly in what they support, and IMAP has no dependable delivery channel that MailDesk can rely on. So MailDesk does not pretend to push for IMAP. Instead it runs an autopilot: it detects each server's capabilities, polls at a cadence matched to those capabilities, and pre-loads message bodies so the inbox opens instantly. New mail surfaces within the poll interval. There is nothing to configure. See IMAP autopilot for the full picture.
Body prefetch — why the inbox opens instantly (all providers)
Independently of how new mail is detected, 4.2.0 warms a body cache so messages are ready before you click them. Two things feed it:
- New mail from sync is queued for warming at high priority the moment it is indexed.
- Opening a folder queues the top visible messages (the newest 30 by default) for warming.
A background warming job (running about once a minute) fetches those bodies into the cache, throttled so it never hammers a provider. If a body is not yet warmed when you open it, it is simply fetched on demand — prefetch is an accelerator, never a dependency.
Current stable behavior (shipped, 4.1.x)
Until the 4.2.0 merge requests land, today's builds deliver new mail on scheduled background jobs, not push. New mail surfaces within the relevant poll interval (roughly 2–3 minutes), and the open screen still refreshes live over the websocket once a message has been ingested. This pipeline does not disappear in 4.2.0 — push and autopilot sit on top of it and it remains the fallback path.
| Job (engine) | Cadence | Purpose |
|---|---|---|
| Gmail incremental | 2 min | History-API delta fetch |
| IMAP inbox | 3 min | New-message and flag delta |
| Outlook delta | 3 min | Graph delta-link fetch |
| Outlook sparse-metadata repair | 15 min | Fill thin metadata rows |
| Bootstrap pending folders | 4 min | First-time folder fill |
| Progressive backfill | 4 min | Historical fill in the background |
For the full data-flow and websocket detail, see Realtime & synchronization architecture.
How push stays healthy, and what happens if it fails
| Concern | What MailDesk does |
|---|---|
| Subscriptions expire | A renewal job runs about once an hour: it renews the Gmail watch (well before its ~7-day limit) and the Outlook subscription (PATCHed at ~6 days, well within its ~7-day max). |
| A provider goes quiet | If no push notification arrives for several hours, the account is flagged for a full delta resync so nothing is missed. |
| Push fails or is not set up | MailDesk silently falls back to the scheduled jobs above. You always keep getting mail. |
| A body fails to prefetch | The message body is fetched on demand the moment you open it. |
What an administrator does
- Gmail: open the mailbox account and run Configure Gmail Realtime. One guided assistant per Gmail mailbox.
- Outlook / Microsoft 365: enable the Microsoft 365 push subscription for the mailbox (the scheduled jobs keep running regardless).
- IMAP: nothing. Autopilot is automatic. There is an optional Probe IMAP capabilities button on IMAP accounts if you want to re-detect the server profile immediately.
- Prefetch: on by default after the 4.2.0 update, with sensible limits. No setup required.
Checking that it works
With push enabled, send yourself a test email and watch it appear in seconds. Subscription health and the warming/renewal jobs are visible to administrators under Settings → Technical → Scheduled Actions (look for the MailDesk push, prefetch, and capability-probe jobs).
Requirements
- MailDesk Pro on Odoo 17, 18, or 19.
- For Gmail push: a Google Cloud project the assistant can configure (the assistant generates the script).
- For Outlook push: a Microsoft 365 mailbox connected with the standard MailDesk Outlook OAuth.
- Your Odoo server reachable over HTTPS at a stable public address, so the providers can reach the webhooks.
- IMAP autopilot has no extra requirement beyond a connected IMAP account.
Permissions required
Configuring realtime push is an administrator task, performed on the mailbox account record. Regular users do not need to do anything — they simply see fresher mail. Standard MailDesk access rules still apply: you only ever see accounts you already have access to.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| New Gmail/Outlook mail still takes minutes | Push not set up (or fell back to scheduled sync) | Run the Gmail Realtime assistant; confirm your server is reachable over HTTPS |
| Gmail Realtime button missing | The account is not a Gmail account, or you are not viewing the mailbox account form | The button only appears for Gmail mailboxes |
| Push worked, then stopped | The subscription expired or was revoked at the provider | The hourly renewal job normally fixes this; re-run the assistant if it persists |
| Inbox feels slow to open on IMAP | The body cache is still warming, or the server is a limited profile | See IMAP autopilot — opening still works, just fetched on demand |