MailDesk docs
Get MailDesk
Basic

Folder sync & background jobs

This page explains how MailDesk keeps each connected mailbox up to date, and the settings an administrator can adjust to tune that behavior — sync batch sizes, how much history is loaded, and how long email bodies stay cached. It is written for the Odoo administrator who looks after a MailDesk deployment.

9 min read Basic

This page explains how MailDesk keeps each connected mailbox up to date, and the settings an administrator can adjust to tune that behavior — sync batch sizes, how much history is loaded, and how long email bodies stay cached. It is written for the Odoo administrator who looks after a MailDesk deployment.

Available in: Basic. The synchronization engine and all of the settings on this page are part of the MailDesk engine, so they work the same whether your mailboxes run on Basic or Pro. Pro adds two-way actions (changes you make in MailDesk are pushed back to the provider) and, in the 4.2.0 release, near-instant delivery for Gmail and Outlook — see Realtime & synchronization architecture for that. The tuning settings below apply to both editions.

What it does

MailDesk does not keep a live connection open to every mailbox. Instead it runs a set of scheduled background jobs that check each provider on a short, regular cadence, fetch what has changed since the last check, and update the inbox you see. The same machinery also loads older email gradually after a mailbox is first connected, and keeps a short-lived cache of message bodies so opening an email is fast.

In day-to-day use this means new mail surfaces automatically within a few minutes, and once a mailbox is open the view refreshes on its own as each background sync completes.

Why it matters

  • Predictable load. Work is done in small, bounded batches on a timer rather than in one large burst, so a busy mailbox or a large history does not slow the rest of Odoo.
  • Fast first use. When a mailbox is connected, the newest messages appear in seconds; the rest of the history fills in quietly in the background.
  • Tunable for your environment. The batch sizes, history depth, and cache retention are all adjustable from a single settings page, so you can trade database size against how much history is kept locally and how often the provider is contacted.

Requirements

  • At least one connected mailbox account (Gmail, Outlook / Microsoft 365, or IMAP). See Gmail setup, Outlook / Microsoft 365 setup, or IMAP / SMTP setup.
  • Odoo's scheduled actions must be running on the server (they are, in any standard Odoo deployment).
  • MailDesk works on Odoo 17, 18, or 19 — the settings below are the same on each.

Permissions required

  • The MailDesk settings page is available to MailDesk administrators (the Mailbox Admin access group). A regular MailDesk user (the Mailbox User group) does not see it.
  • The OAuth credential fields on the same page are additionally restricted to Odoo Settings administrators.

How the background sync works

MailDesk uses three stages, all driven by scheduled jobs:

  1. Bootstrap — when a mailbox or folder is first connected, MailDesk fetches the newest messages straight away so the folder is usable within seconds.
  2. Incremental sync — on a short timer thereafter, MailDesk fetches only what has changed since the last check (new mail, read/unread changes, moves), using each provider's efficient delta mechanism.
  3. Progressive backfill — separately and at a lower priority, MailDesk works backwards through older history in small batches until the configured depth is reached.

Once a message has been indexed, every open MailDesk tab is refreshed promptly over Odoo's internal message bus, so users do not need to reload to see new mail. This in-app refresh fires after a scheduled sync has fetched the message — it is not a separate live feed from the provider.

The scheduled jobs (stable 4.1.x)

These jobs run automatically. You do not normally need to touch them; they are listed here so you can recognize them under Settings → Technical → Scheduled Actions when checking sync health.

Scheduled job Runs every What it does
MailDesk Gmail Incremental Sync 2 minutes Fetches new and changed Gmail messages
MailDesk IMAP INBOX Sync 3 minutes Fetches new and changed IMAP messages
MailDesk Outlook Delta Sync 3 minutes Fetches new and changed Outlook / Microsoft 365 messages
MailDesk Outlook Sparse Metadata Repair 15 minutes Fills in any thin Outlook message details
MailDesk: Alias Scan (Index → Queue) 3 minutes Promotes indexed messages into the import queue
MailDesk: Process Queue (Odoo Import) 3 minutes Brings queued messages fully into Odoo
MailDesk: Bootstrap Pending Folders 4 minutes Performs the first fill of newly added folders
MailDesk: Progressive Backfill 4 minutes Loads older history in small batches
MailDesk: Clean Expired Cache daily Removes cached message bodies past their retention period

New mail timing

In a standard 4.1.x deployment, new mail surfaces within its provider's poll interval — roughly two to three minutes. This is normal, expected behavior, not a fault. The 4.2.0 release shortens Gmail and Outlook delivery to seconds with provider push; see Realtime & synchronization architecture.

Where the settings live

All of the tuning settings are on one page:

  1. Open MailDesk → Configuration → MailDesk Settings → Settings.

(This is the same as Settings → MailDesk — both open the MailDesk section of Odoo's settings.) 2. You will see five grouped blocks: OAuth Settings, Cache Settings, Sync Settings, Performance Settings, and Folder Backfill. 3. Change the values you need, then click Save at the top of the settings page.

The MailDesk Settings page with the Cache, Sync, Performance, and Folder Backfill blocks

Cache Settings

Setting Default What it controls
Email Cache Retention (days) 30 How long MailDesk keeps cached email bodies and attachments locally. A longer retention means messages reopen instantly for longer, at the cost of more database storage; a shorter retention saves space but re-fetches from the provider more often.

Sync Settings

Setting Default What it controls
Sync Batch Size 100 The maximum number of messages MailDesk fetches from the provider in a single sync batch. Higher values can improve throughput on fast connections; lower values keep each job shorter.
Ingest Queue Batch Size 50 The maximum number of queued messages MailDesk fully imports into Odoo per job run. Lower this to smooth out load spikes on a busy server.

Performance Settings

Setting Default What it controls
List Page Size 30 How many messages MailDesk loads per page in the message list. Larger pages show more at once but feel heavier in the interface.

Folder Backfill

These settings govern how much email history MailDesk loads after a mailbox is connected, and how hard it works while doing so.

Setting Default What it controls
Backfill Mode Progressive How history is loaded — see the table below.
Bootstrap: Max Messages 1500 How many of the newest messages MailDesk fetches immediately when a folder is first connected, before the slower background backfill takes over.
Backfill: Batch Size 100 How many older messages each background backfill run fetches.
Backfill: Job Budget (seconds) 25 The maximum time one backfill run is allowed before it stops and resumes on the next scheduled run. This keeps backfill from monopolizing a worker.
Backfill: Max Total Per Folder 20000 An upper limit on how many messages are stored per folder, to keep database growth predictable. Set to 0 for no limit.

Backfill Mode offers three choices:

Mode Label in the form Behavior
Progressive Progressive (Bootstrap + Background) Fetches the newest messages immediately, then loads the rest of the history quietly in the background. Recommended for most deployments.
Full Full Historical (Unbounded) Loads the entire history. Use when you must have every message available locally and accept the larger database.
From now on From Now On (No Backfill) Loads no history at all — only mail that arrives after connection. Use to keep the database small when older mail is not needed in MailDesk.

Sensible defaults

The defaults suit most installations. The two settings most worth reviewing are Backfill Mode (how much history you want in Odoo) and Email Cache Retention (how much storage you want to spend on fast reopening). Changes apply on the next scheduled run; you do not need to restart anything.

For advanced operators

Each setting above is stored as an Odoo system parameter (for example maildesk.sync_batch_size, maildesk.backfill_mode). The MailDesk Settings page is the supported way to change them; editing the raw parameters directly is only for advanced automation and is not required for normal administration.

Steps — adjust how much history a mailbox keeps

  1. Open MailDesk → Configuration → MailDesk Settings → Settings.
  2. In the Folder Backfill block, choose a Backfill Mode (Progressive, Full, or From Now On).
  3. If you want to cap storage, set Backfill: Max Total Per Folder to a number, or 0 for no limit.
  4. Click Save.

Expected result

New mailboxes connected from now on follow the chosen mode. Mailboxes that are already connected keep what they have already loaded; the new depth and limits apply to subsequent background runs.

Steps — load older mail for one folder now

If a specific folder is missing older messages, you can ask MailDesk to fetch its history without changing the global settings:

  1. Open MailDesk → Configuration → Mailboxes → Mailbox Accounts and open the account.
  2. Go to the Folders tab.
  3. Find the folder and check its Backfill Status and Progress.
  4. Click Trigger Backfill on that folder.

Expected result

MailDesk begins fetching that folder's older history in the background, in the batch sizes set in the Folder Backfill block. The Progress indicator advances as history loads.

Troubleshooting

Symptom Likely cause What to do
New mail takes a couple of minutes to appear Normal scheduled-sync timing in 4.1.x This is expected. The open list refreshes on its own as each background sync completes — mail arrives within the poll interval without any action. To force an immediate fetch, run the relevant sync under Settings → Technical → Scheduled Actions, or trigger a folder backfill from the mailbox account.
Older messages are still missing after connection Backfill is still running, or From Now On mode is selected Leave the mailbox connected and allow backfill time to complete. If you need history, set Backfill Mode to Progressive or Full, then use Trigger Backfill on the folder.
A folder shows no messages The folder may not be selected for sync, or has no mail at the provider Open the account, confirm the folder is included, and verify in webmail that messages exist there.
Backfill seems very slow on a large mailbox Backfill is deliberately low-priority and budget-limited Raise Backfill: Batch Size and/or Backfill: Job Budget (seconds) in the Folder Backfill block. New mail always takes priority over backfill.
Database is growing faster than expected Long cache retention, Full backfill, or a high per-folder limit Lower Email Cache Retention (days), switch Backfill Mode to Progressive, or set Backfill: Max Total Per Folder to a smaller number.
Messages reopen slowly after a while Their cached bodies expired and were re-fetched This is expected once past the retention period; increase Email Cache Retention (days) if fast reopening of older mail matters.
A mailbox stops receiving new mail entirely The provider authorization expired or the connection failed Open the account and re-authorize (Gmail / Outlook) or re-test the connection (IMAP). See Troubleshooting.

Most timing issues clear on their own

The majority of "missing email" reports are simply mail that is still syncing. Waiting one or two background cycles resolves them without any change to settings; the open list updates itself as each sync completes.