MailDesk User Guide — Introduction

What is MailDesk?

MailDesk is a professional email client integrated directly into Odoo. It allows you to manage multiple email accounts (IMAP, Gmail, Outlook) within your Odoo workspace without switching between applications.

Key Features:

• Multi-account support: Manage work, personal, and team emails in one place
• Multi-provider support: IMAP, Gmail (OAuth), Outlook (OAuth)
• Threading: Conversations grouped intelligently using email headers
• Search & filtering: Find emails by sender, subject, date, tags
• Offline-first: Your emails sync in background, always available
• Real-time updates: New emails appear instantly via websocket
• Tagging: Organize emails with custom tags
• Drafts: Save work-in-progress emails

How MailDesk Works (User Perspective)

What You See

Folder Tree (left sidebar):

• Inbox, Sent, Drafts, Archive, Trash
• Custom folders (if configured on your email server)
• Unread badges update in real-time

Message List (center):

• Subject, sender, preview, date
• Icons: unread (dot), starred (star), attachments (paperclip)
• Click to open full message

Message Detail (right):

• Full email body with images and formatting
• Attachments (download or preview)
• Reply, Reply All, Forward buttons

What Happens Behind the Scenes

####Synchronization (Automatic)

Your emails sync with your email server every 5 minutes:

1. Backend checks your email server (IMAP/Gmail/Outlook) for new messages
2. New emails downloaded (metadata only, bodies fetched on-demand)
3. Your UI updates automatically via websocket (no page refresh needed)

You don't need to click "Refresh" — it happens automatically.

Local-First Sent Mail

When you click "Send":

1. Email sent via SMTP immediately (200-800ms)
2. Message appears in your Sent folder instantly (MailDesk creates a local entry)
3. Background sync copies message to your email server's Sent folder (5-30 seconds later)
4. Local entry replaced by server copy seamlessly

Why this matters: You never see "sent email disappeared" issues common in other clients.

Smart Caching

When you open an email:

1. First open: Fetched from your email server (500ms - 3s)
2. Subsequent opens: Loaded from cache (<100ms, instant)
3. Cache expires after 7 days → re-fetched automatically

You don't manage cache — it's automatic and transparent.

How MailDesk Differs from Other Email Clients

vs. Thunderbird / Outlook Desktop

vs. Gmail Web / Outlook Web

vs. Odoo's Built-In Mail (Chatter)

Important: MailDesk is NOT a replacement for Odoo Chatter. They serve different purposes:

• Chatter: Internal team communication, record comments
• MailDesk: External email (clients, partners, suppliers)

Who Should Use MailDesk?

Ideal Users

✅ Odoo power users who want email + CRM/Projects in one place 
✅ Remote teams who need web-based email (no desktop app) 
✅ Multi-account users (work + personal + team aliases) 
✅ Privacy-conscious users (self-hosted email client) 
✅ Gmail/Outlook power users who want better threading + search

Not Ideal For

❌ Users with 100K+ emails per account (performance degrades) ❌ Users needing offline desktop app (MailDesk is web-based) ❌ Users wanting POP3 support (only IMAP, Gmail, Outlook) ❌ Users needing Exchange ActiveSync (use Outlook OAuth instead)

System Requirements

Browser Support

• ✅ Chrome / Chromium 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+

Not supported: Internet Explorer, Opera Mini, mobile WebView browsers

Email Provider Requirements

IMAP Accounts:

• IMAP server with SSL/TLS
• SMTP server for sending
• Folder support (Inbox, Sent, Drafts)

Gmail:

• Google Workspace or personal Gmail account
• OAuth 2.0 enabled (MailDesk will guide you)
• API scopes: gmail.readonly, gmail.modify, gmail.send

Outlook:

• Microsoft 365 or Outlook.com account
• OAuth 2.0 via Microsoft Graph
• API scopes: Mail.ReadWrite, Mail.Send

Privacy & Security

Data Storage

What MailDesk stores:

• ✅ Email metadata (subject, sender, date, folder)
• ✅ Cached email bodies (7-day TTL)
• ✅ Your account credentials (encrypted)

What MailDesk does NOT store:

• ❌ Full email archive (only recent cache)
• ❌ Attachments permanently (cached temporarily)
• ❌ Deleted emails (removed immediately)

Where data is stored: Your Odoo server's PostgreSQL database

Security Features

Encryption:

• TLS/SSL for IMAP/SMTP connections
• OAuth tokens encrypted in database
• HTTPS required for web access

Access Control:

• Per-user email accounts (no sharing)
• Odoo's built-in authentication
• Optional 2FA (via Odoo)

Password Storage:

• IMAP passwords encrypted with Odoo's encrypt function
• OAuth tokens encrypted separately
• Never logged or exposed in UI

Getting Help

In This Guide

• Getting Started: Set up your first account
• Account Setup Guides: IMAP, Gmail, Outlook step-by-step
• Daily Usage: Sending, organizing, searching emails
• FAQ & Troubleshooting: Common issues and solutions

Support Channels

• Odoo Community Forums: forum.odoo.com
• MailDesk Documentation: /docs folder in module
• Your Odoo Administrator: For server-side issues

Next Steps

👉 New users: Read Getting Started to set up your first account
👉 IMAP users: Follow IMAP Setup Guide 
👉 Gmail users: Follow Gmail Setup Guide 
👉 Outlook users: Follow Outlook Setup Guide
👉 Already set up: Learn Daily Usage tips and tricks