Details

" 17 July 2026\

The Mail Client caching mechanism is designed to optimize performance, minimize server load, and ensure a responsive user experience by storing folder structures, email headers, and message bodies locally in the database.

1. Folder Synchronization (syncFolders)

When connecting to an IMAP mailbox, the system retrieves the directory listing. Any folders discovered on the server are synced into the c01_mailclient_folders table, where they are mapped to predefined roles (such as inbox, sent, drafts, trash, spam, and archive) for standardized UI display. Folders deleted on the server are pruned from the local database.

2. Header Syncing & Cache Invalidation (syncHeaders)

Each folder sync session starts by querying the remote status of the folder, retrieving uid_validity, uid_next, and message count.

• Cache Invalidation: If the remote uid_validity value differs from the local cached value, it indicates that the remote UIDs have changed or been renumbered. The local cache of headers for this folder is immediately cleared to prevent mismatched IDs.
• Incremental Syncing: The system compares the local cached UIDs (imap_uid) with the server's current UID list. Deleted messages are pruned locally, and missing (new) headers are fetched in batch and inserted into the c01_mailclient_headers table.

3. On-Demand Message Body Caching (getOrFetchBody)

To optimize bandwidth, message bodies and attachments are fetched on-demand only when a user selects a message.

• Local Lookup: The client first queries c01_mailclient_bodies. If the body is cached, it is rendered instantly.
• Server Fetch: If not cached, the client connects to the IMAP server, downloads the HTML body, strips tags for a text version, retrieves any attachments, caches them as JSON in the database, and serves the content. Subsequent views load instantly from the cache.

4. Logging and Auditing

All IMAP actions, connections, and cache synchronization results (number of fetched or deleted items) are logged systematically in the c01_imap_logs table via the logImap routine.