MailDesk docs
Get MailDesk

Glossary

Terms used throughout the MailDesk documentation. Entries are plain-language first, with the underlying model or technical identifier in parentheses for developers. Sorted alphabetically.

5 min read

Terms used throughout the MailDesk documentation. Entries are plain-language first, with the underlying model or technical identifier in parentheses for developers. Sorted alphabetically.

Autopilot (IMAP)

The 4.2.0 mechanism that automatically figures out how capable each IMAP server is and picks the cheapest correct synchronization strategy for it — with no tuning knobs. A weekly probe runs the IMAP CAPABILITY command and classifies the account into one of four profiles: A (IDLE + CONDSTORE + QRESYNC + UIDPLUS — cheapest deltas), B (IDLE only), C (basic IMAP, UID-append detection), or D (capabilities unreliable — strict budget mode). Classification is deterministic and re-probed weekly. (Use cases detect_imap_profile.py, sync_imap_folder_smart_pro.py; near-release, not yet merged to 18.0.)

Bridge (Workflow Bridge)

An optional module that connects MailDesk to another Odoo app so emails can be linked to that app's records — CRM leads, Helpdesk tickets, Sale orders, Calendar events, Documents — plus Partner 360, the Chatter integration, and the Automation Engine. Every bridge requires Pro. Bridges are SSOT-safe: they read and link, they do not own MailDesk's message truth. There are nine bridges in total.

Bus

Odoo's websocket channel that pushes UI updates to open browser tabs. Once a message is indexed, MailDesk broadcasts on account-scoped bus channels so other open tabs and users see changes promptly. This is UI push — it only fires after a synchronization has already ingested the message; it is not the same as provider push. (Model ir.websocket.)

Cockpit

A manager-facing module that provides a read-only projection over MailDesk activity: KPIs, AI briefings (with per-tier quotas), SLA tracking, and a four-tier permission model. The Cockpit reports on workflow truth; it does not own it. It additionally requires the Automation Engine and Odoo's resource module. (Module maildesk_mail_client_cockpit.)

delivery_key

The identity of a synced message: the tuple (account, provider, folder, uid). It is how the message index recognizes the same message across syncs, and how the outbound mutation queue addresses changes. Stable identity by delivery_key is what lets a linked email survive folder moves and label changes.

Ingest queue

The durable hand-off that materializes indexed messages into Odoo's mail.thread so they participate in normal Odoo features (Chatter, activities, record links). It retries on failure. A scheduled job promotes indexed messages into the queue, and another job imports the queue into Odoo. (Model maildesk.ingest_queue.)

Message index

The single source of truth (SSOT) for message metadata in MailDesk — sender, recipients, subject, date, folder, flags, and identity. Bodies and attachment lists are not stored here; they live in the UI cache. The message index is keyed by delivery_key. (Model maildesk.message_index.)

Prefetch (body prefetch)

The 4.2.0 mechanism that loads message bodies into the UI cache before the user opens them, so opening a message (or a folder) feels instant. A queue is fed by two hooks — one fires for each newly synced message (high priority), one fires when a folder's list renders and warms the top visible messages — and a once-a-minute warming job fills the cache under throttle, time-budget, and backoff guards. The hooks are no-ops in Basic; Pro provides the real implementation. (Model maildesk.message_prefetch_queue; near-release, not yet merged to 18.0.)

Push subscription

A registration with Gmail (Cloud Pub/Sub + users.watch) or Outlook (Microsoft Graph /subscriptions) that lets the provider notify MailDesk the moment new mail arrives, instead of waiting for the next scheduled check. Subscriptions are time-limited and renewed automatically (Gmail ~7-day watch, Outlook ~3-day subscription). A webhook receives the notification, then triggers the existing sync job — push shortens latency, it doesn't replace the sync pipeline. (Model maildesk.push_subscription; near-release, not yet merged to 18.0.)

SSOT (single source of truth)

The design principle that one place owns each piece of truth, and everything else reads from it. In MailDesk the message index is the SSOT for message metadata; the ingest queue, UI cache, bridges, and the outbound update queue all defer to it rather than holding competing copies.

Two-way sync

Pro's ability to push your changes back to the provider, not just pull mail in. When you flag, label, move, or delete a message in MailDesk, Pro coalesces that change per message and applies it to Gmail, Outlook, or IMAP through a per-provider executor, with lease locking and backoff. Basic is one-way (inbound) only. (Model maildesk.update_queue + per-provider mutation_executor.py.)

UI cache

A short-lived (TTL) cache that holds rendered message bodies and attachment lists so the interface can show a message without re-fetching it from the provider every time. It is guarded by advisory locks and cleaned up on a schedule. In 4.2.0, body prefetch warms this cache ahead of the user. (Model maildesk.ui_cache.)

Update queue

Pro's outbound mutation queue — the engine behind two-way sync. It coalesces outbound changes (flag, label, move, soft-delete) per delivery, locks the work with leases, and retries with backoff (up to eight attempts) before applying each change to the provider. (Model maildesk.update_queue.)

Other terms

  • Basic — the MailDesk engine edition: unified inbox, one-way (inbound) sync, composer, and the SSOT data model. No AI, non-adaptive desktop UI. (Module maildesk_mail_client.)
  • Pro — extends Basic with two-way sync, the AI Assistant, the mobile-adaptive UI, and (in 4.2.0) realtime push and prefetch. Required by all bridges. (Module maildesk_mail_client_pro.)
  • Backfill — the background, progressive load of older historical mail after a mailbox is connected; newest mail loads first, history fills in gradually.
  • Bootstrap — the first-time fill of a folder when a mailbox is newly connected.
  • Lease — a short-lived lock that lets only one worker sync or mutate an account at a time, so parallel jobs don't collide. (Model maildesk.account_lease.)
  • Mailbox account — a connected Gmail, Outlook/M365, or IMAP mailbox, with its OAuth or credential state, sync state, owner, and access list. (Model mailbox.account.)
  • Near-realtime — the honest description of MailDesk's freshness: Gmail and Outlook push within ~15 seconds (4.2.0); IMAP arrives within the poll interval but opens instantly from prefetch.
  • Silence detection — a 4.2.0 safety net: if no push notification arrives for ~6 hours, the account is scheduled for a full delta resync so nothing is silently missed.