Body prefetch and the message cache
MailDesk keeps the body of a message — and its attachment list — in a short-lived cache so the reading pane opens instantly instead of waiting for a round-trip to the mail provider. Body prefetch is the mechanism that fills that cache ahead of time, so that by the time you click a message its body is usually already there.
MailDesk keeps the body of a message — and its attachment list — in a short-lived cache so the reading pane opens instantly instead of waiting for a round-trip to the mail provider. Body prefetch is the mechanism that fills that cache ahead of time, so that by the time you click a message its body is usually already there.
Available in: Pro. Body prefetch is part of the 4.2.0 realtime work. MailDesk Basic keeps the same on-demand cache but does not warm it in advance.
Near-release feature (4.2.0)
Body prefetch ships with MailDesk 4.2.0. It is complete and test-covered but is not yet in the shipped 4.1.x build — it lives on the realtime branch and merges with 4.2.0. On 4.1.x, message bodies are still cached, but only when you first open a message (on demand). Everything on this page describes 4.2.0 behavior.
What it does
When a message arrives or when you open a folder, MailDesk quietly fetches the message body in the background and stores it in the cache. Two things trigger this:
- After a sync — every newly synced message is queued for prefetch at high priority, so a fresh email is usually ready to read the moment it shows up in your list.
- When you open a folder — the messages near the top of the list (the ones you are most likely to open next) are queued for prefetch.
A background job then works through the queue a few messages at a time and warms the cache. When you click a message whose body is already warm, it opens with no provider round-trip.
Why it matters
- Instant opens. The reading pane shows the body immediately for prefetched messages instead of pausing to download it.
- This is what makes IMAP feel fast. IMAP accounts do not get true provider push, so MailDesk leans on prefetch: new mail still appears within the regular sync interval, but opening a message is instant because the body was already warmed.
- It is gentle on your provider. Prefetch is rate-limited per account and runs in small batches, so warming the cache never floods the provider with requests.
How it works
flowchart LR
A[New mail synced] -->|priority 1| Q[Prefetch queue]
B[Folder opened] -->|priority 5, top messages| Q
Q --> W[Warming job<br/>every minute]
W --> C[Message cache<br/>body + attachment list]
U[You open a message] --> C
C -->|already warm| R[Opens instantly]- Queueing. Each message that needs warming becomes one slot in a prefetch queue, keyed by account, folder, and message. Slots are deduplicated — a message is never queued twice — and a freshly synced message (high priority) takes precedence over a message queued only because you opened its folder (lower priority).
- Warming. A background job runs about once a minute, takes a small batch, and fetches each body into the cache. It respects a short time budget per run, so it never blocks the system.
- Serving. When you open a message, MailDesk serves the cached body if it is warm. If it is not — for example because warming has not caught up yet — the body is simply fetched on demand at that moment, exactly as it always was. Prefetch is an optimization, never a requirement.
The safeguards
The warming job is deliberately conservative so it can never overwhelm a provider or the server:
| Guard | Behavior |
|---|---|
| Batch size | A few messages per run (default 5) |
| Time budget | About 10 seconds per run, then it stops and resumes next minute |
| Per-account limit | Up to 200 prefetches per account per hour |
| Retry with backoff | A failed warm is retried later with an increasing wait (seconds, then minutes, up to a couple of hours) |
| Give-up limit | After several failed attempts the slot is dropped; if the message no longer exists on the server, it is dropped immediately |
If warming a body fails, nothing breaks for you: the body is fetched on demand the next time you open that message.
How long bodies stay cached
The cache is a short-lived convenience copy, not permanent storage. Cached bodies and attachment lists expire on a retention schedule, and a daily cleanup job removes expired entries. The message itself — and all of its metadata — always lives safely in MailDesk's own records; the cache only holds a temporary copy of the body to make opening fast.
What an administrator configures
Nothing, in the normal case. Body prefetch turns on automatically with the 4.2.0 update and ships with sensible defaults. There is no per-user setup and no per-mailbox switch to flip — it simply makes opening mail faster.
The behavior is controlled by a small set of system parameters with safe defaults, which an administrator can adjust under Settings → Technical → System Parameters if a deployment ever needs to:
| Parameter | Default | Meaning |
|---|---|---|
maildesk.prefetch.enabled |
1 |
Master switch for body prefetch |
maildesk.prefetch.batch_per_run |
5 |
Messages warmed per run |
maildesk.prefetch.max_per_account_per_hour |
200 |
Per-account hourly cap |
maildesk.prefetch.folder_open_top_n |
30 |
How many top-of-list messages to warm when a folder opens |
Leave the defaults alone unless you have a reason
The defaults are tuned to feel instant while staying gentle on providers. Only change them with guidance from support — for example to lower the hourly cap on a provider with very tight rate limits.
What an administrator can see
Prefetch is observable, not hidden:
- Scheduled Actions. The warming job appears under Settings → Technical → Scheduled Actions as MailDesk: Warm Message Body Cache (runs every minute). Its run log shows it is active and progressing.
- Diagnostic snapshot. MailDesk administrators can produce a per-account diagnostic snapshot for a support ticket. It reports sync timestamps, the account's sync profile, push-subscription health, and failed-queue counts — and is deliberately scrubbed of any message content, recipients, subjects, tokens, or secrets.
Expected result
- New mail is usually ready to read the instant it appears in your list.
- Opening a folder and then clicking one of its top messages opens with no visible delay.
- On any miss, the message still opens — it just fetches the body at that moment.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| First message you open still pauses briefly | Warming has not caught up yet, or the body was not prefetched | Normal — it is fetched on demand; subsequent opens are instant |
| Bodies never seem pre-warmed | Prefetch is disabled, or the warming job is not running | Check maildesk.prefetch.enabled is 1; confirm MailDesk: Warm Message Body Cache is active under Scheduled Actions |
| Opens are slow only on one IMAP account under heavy load | Per-account hourly prefetch cap reached | Expected throttling; opens still work on demand. Raise the cap only with support guidance |
| Provider reports rate-limit pressure | Prefetch volume too high for that provider | Lower maildesk.prefetch.max_per_account_per_hour or batch_per_run |
For new mail not appearing at all (rather than just opening slowly), see Realtime troubleshooting.