Folder mapping & sync settings

Your team should never have to wonder "is this the real, up-to-date inbox?" — and you should never have to babysit a sync to make it behave. This page shows you exactly how MailDesk maps your provider's folders into Odoo and keeps every connected mailbox current, plus the handful of settings an administrator can adjust to fit your storage, history, and load preferences. By the end you'll know which folders sync, how often, and what every toggle on the MailDesk Settings page a

Your team should never have to wonder "is this the real, up-to-date inbox?" — and you should never have to babysit a sync to make it behave. This page shows you exactly how MailDesk maps your provider's folders into Odoo and keeps every connected mailbox current, plus the handful of settings an administrator can adjust to fit your storage, history, and load preferences. By the end you'll know which folders sync, how often, and what every toggle on the MailDesk Settings page actually does.

Available in: Basic. The synchronization engine and every setting on this page are part of the core MailDesk engine, so they behave the same on Basic and Pro. Pro adds two-way actions — changes you make in MailDesk (read/unread, moves, deletes) are pushed back to the provider — and near-instant delivery for Gmail and Outlook. See Realtime & synchronization architecture for that. The tuning settings below apply to both editions.

What you get

MailDesk doesn't hold a live connection open to every mailbox all day. Instead it runs a small set of scheduled background jobs that quietly check each provider on a short, regular cadence, fetch only what has changed since the last check, and update the inbox your team sees. The same machinery loads older email gradually after a mailbox is first connected, and keeps a short-lived cache of message bodies so opening an email feels instant.

In everyday use this means three things:

• New mail surfaces on its own within a few minutes — nobody has to click "refresh."
• Your folders look familiar. Inbox, Sent, Drafts, Spam, Trash and Archive are recognised automatically, even when your provider names them in German, French, Italian, Spanish, Portuguese or Russian.
• It stays out of the way. Work happens in small, timed batches, so a busy mailbox or a deep history never slows down the rest of Odoo.

Why it matters

• Predictable load. Syncing runs in bounded batches on a timer rather than one big burst, so the rest of Odoo stays responsive.
• Fast first use. When a mailbox is connected, the newest messages appear within seconds; the rest of the history fills in quietly behind the scenes.
• Tunable for your environment. 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 you keep locally and how often the provider is contacted.

Before you start

• 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 running on the server (they are, in any standard Odoo deployment).
• MailDesk runs on Odoo 17, 18 or 19 — the settings below are identical on each.

Who can change these settings

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

How your folders are mapped

When MailDesk connects to a mailbox, it reads the folder list from the provider and recreates it inside Odoo so the sidebar mirrors what your users already know. It does more than copy names, though — it works out the purpose of each folder so the right icon and behaviour follow it everywhere.

Standard folders are recognised automatically. MailDesk maps each folder it finds to one of these logical types:

It speaks your language. Recognition isn't tied to English. A "Gesendet", "Envoyés", "Inviati", "Enviados", "Отправленные" or "[Gmail]/Sent Mail" folder is all understood as your Sent folder; "Papierkorb", "Corbeille", "Cestino", "Papelera" and "Trash" all map to Trash; and so on for Drafts, Spam, Archive and Inbox. Nested project folders like Work/Sent are recognised too, so they sort and behave sensibly rather than getting dumped into "Other."

Non-mail folders are filtered out. Calendars, Contacts, Tasks, Notes, RSS feeds, sync-conflict folders and the Outbox are not email and would only clutter the sidebar, so MailDesk leaves them out. Hidden system folders are skipped as well, keeping the folder list clean and useful.

How the background sync works

MailDesk keeps mailboxes current in 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 depth you've chosen is reached.

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

The scheduled jobs

These jobs run automatically; you don't normally need to touch them. They're listed here so you can recognise them under Settings → Technical → Scheduled Actions when checking sync health.

Where the settings live

All of the tuning settings sit on one page. To reach them:

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

(This is the same place as Settings → MailDesk — both open the MailDesk section of Odoo's settings.)

2. You'll see 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.

Cache Settings

Sync Settings

Performance Settings

Folder Backfill

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

Backfill Mode offers three choices:

Walkthrough — choose 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.

What happens next: new mailboxes connected from now on follow the mode you chose. Mailboxes that are already connected keep what they've loaded; the new depth and limits apply to their subsequent background runs.

Walkthrough — 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 any 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.

What happens next: MailDesk starts fetching that folder's older history in the background, using the batch sizes from the Folder Backfill block. The Progress indicator advances as history loads, and you'll see a confirmation that backfill has started.

Troubleshooting

Related

• Realtime & synchronization architecture — the full technical picture, including push for Gmail and Outlook
• Mailbox setup
• Gmail setup · Outlook / Microsoft 365 setup · IMAP / SMTP setup
• Troubleshooting
• Security & access rights