Zum Inhalt springen
Congratulations!Security ChecklistTips for New UsersNext StepsCommon First-Time IssuesStep 6: Configure Folders (Optional)Step 5: Send a Test EmailStep 4: Initial SyncStep 3: Test Your ConnectionStep 2: Add Your First AccountStep 1: Access MailDeskPrerequisitesOverviewGetting Started With MailDesk

Getting Started With MailDesk


Overview

This guide walks you through setting up your first email account in MailDesk. The entire process takes 5-10 minutes.

Prerequisites

Before you begin, ensure you have:

✅ Active Odoo account with MailDesk module installed 
✅ Email account credentials (username and password OR OAuth setup) 
✅ Email server details (for IMAP accounts) 
✅ Administrator permissions (if configuring OAuth for Gmail/Outlook)

Step 1: Access MailDesk

  1. Log into your Odoo instance
  2. Click Apps menu (grid icon, top-left)
  3. Find and click MailDesk app
  4. UI opens with empty inbox (no accounts yet)

Step 2: Add Your First Account

  1. Click Settings (gear icon, top-right)
  2. Click Mailbox Accounts
  3. Click Create button
  4. Choose account type:

Quick Decision Guide:

  • Have Gmail address ([email protected] using Google Workspace)? → Choose Gmail
  • Have Outlook.com or [email protected] using Microsoft 365? → Choose Outlook
  • Have other email provider (FastMail, ProtonMail, self-hosted)? → Choose IMAP

Step 3: Test Your Connection

After configuring your account:

  1. Click Test Incoming button
    • ✅ Success: "Connection successful"
    • ❌ Failure: Check server address, port, credentials
  2. Click Test Outgoing button
    • ✅ Success: "Connection successful"
    • ❌ Failure: Check SMTP settings
  3. Click Save button

Step 4: Initial Sync

After saving:

  1. MailDesk automatically starts bootstrap sync
  2. Inbox folder syncs first (newest 50 messages)
  3. Progress indicator shows in folder tree
  4. First messages appear within 5-30 seconds

What's happening?:

  • MailDesk fetches email metadata (subject, sender, date)
  • Full email bodies fetched on-demand when you open messages
  • Older messages fetched progressively in background

Step 5: Send a Test Email

Verify sending works:

  1. Click Compose button (top-right)
  2. Fill in:
    • To: [email protected] (send to yourself)
    • Subject: "MailDesk test"
    • Body: "Testing MailDesk email client"
  3. Click Send

Expected Result:

  • Email appears in Sent folder immediately (local-pending)
  • Test email arrives in your inbox within 1 minute
  • Both inbox and sent mail show the same message

Step 6: Configure Folders (Optional)

By default, MailDesk syncs: Inbox, Sent, Drafts, Trash

To add more folders:

  1. Go to Settings → Mailbox Accounts
  2. Click your account name
  3. Click Sync Folders button
  4. MailDesk scans your email server for all folders
  5. Check boxes for folders you want to sync
  6. Click Save

Recommended folders:

  • ✅ Inbox (always enabled)
  • ✅ Sent (always enabled)
  • ✅ Drafts (if you save drafts)
  • ✅ Trash (to see deleted messages)
  • ⚠️ Archive (optional, for long-term storage)
  • ❌ Spam (usually not needed in MailDesk)

Why not sync all folders?:

  • More folders = slower sync
  • Rarely-accessed folders waste bandwidth
  • You can always add folders later

Common First-Time Issues

Issue: "Connection Refused"

Symptoms: "Cannot connect to mail server"

Causes:

  1. Wrong server address (typo)
  2. Firewall blocking outbound connections
  3. Email provider requires app-specific password

Fix:

  1. Double-check server address (imap.gmail.com, outlook.office365.com, etc.)
  2. Ask your IT department about firewall rules
  3. For Gmail: Enable "Less secure apps" OR use app-specific password
  4. For Outlook: Use OAuth instead of password

Issue: "No Messages Appear"

Symptoms: Folders show "0 messages", but you have emails

Causes:

  1. Sync still in progress (wait 30-60 seconds)
  2. Folder not selected for sync
  3. Server-side folder filter active

Fix:

  1. Refresh browser (Ctrl+R / Cmd+R)
  2. Check Settings → Mailbox Accounts → Sync Folders
  3. Check email server web interface (Gmail.com, Outlook.com) to confirm emails exist

###Issue: "Sent Email Not Visible"

Symptoms: Clicked Send, but message disappeared

Expected Behavior: Message appears immediately (local-pending), then syncs to server

If message truly disappeared:

  1. Check Sent folder (it should be there)
  2. Check Drafts folder (if send failed, draft saved)
  3. Check Odoo server logs for SMTP errors

Prevention: This should never happen in MailDesk v3 (local-first design)

Next Steps

✅ Account configured → Proceed to Daily Usage Guide

✅ Multiple accounts → Repeat Step 2 for each email address

✅ Performance tuning → Read Caching and Performance

✅ Troubleshooting → See FAQ & Troubleshooting

Tips for New Users

Tip 1: Start with One Account

Don't configure all your email accounts at once:

  • Start with your primary work email
  • Learn the interface
  • Then add secondary accounts

Tip 2: Sync Selectively

You don't need to sync all folders:

  • Inbox + Sent is enough for most users
  • Add Archive if you use it frequently
  • Skip Spam, Trash, All Mail (Gmail)

Tip 3: Give Sync Time

Initial bootstrap takes time:

  • 50 emails: ~10 seconds
  • 500 emails: ~1 minute
  • 5,000 emails: ~5 minutes (incremental backfill)

Don't panic if messages don't appear instantly.

Tip 4: Use Tags, Not Folders

MailDesk tags are faster than moving messages:

  • Tags are instant (no provider sync needed)
  • One message can have multiple tags
  • Search by tag is fast

Folders require provider sync (slower).

Security Checklist

Before using MailDesk in production:

  • [ ] HTTPS enabled on Odoo server (not HTTP)
  • [ ] Strong password for email account
  • [ ] Two-factor authentication enabled (if supported)
  • [ ] OAuth used for Gmail/Outlook (not password)
  • [ ] Regular Odoo database backups configured
  • [ ] Access logs monitored

If unsure, consult your Odoo administrator.

Congratulations!

You've successfully set up your first email account in MailDesk.

You can now:

  • Send and receive emails within Odoo
  • Search and organize messages
  • Reply and forward with threading
  • Access emails from any device (web-based)

Next recommended reading: