Skip to Content
IMAP Account Setup GuidePrerequisitesStep 1: Gather Server InformationStep 2: Create Account in MailDeskStep 3: Configure Incoming Mail (IMAP)Step 4: Configure Outgoing Mail (SMTP)Step 5: Configure FoldersStep 6: Initial SyncIMAP-Specific BehaviorCommon Issues & SolutionsSecurity RecommendationsProvider-Specific NotesTesting Your SetupWhat to ExpectNext Steps

IMAP Account Setup Guide


Prerequisites

Before setting up an IMAP account in MailDesk, ensure you have:

  • ✅ Email account with IMAP access enabled
  • ✅ IMAP server address (e.g., imap.example.com)
  • ✅ SMTP server address for sending (e.g., smtp.example.com)
  • ✅ Your email address and password
  • ✅ (Optional) App-specific password if your provider requires it

Step 1: Gather Server Information

Common Provider Settings

Gmail (use OAuth instead—see Gmail Setup Guide):

  • IMAP: imap.gmail.com, port 993 (SSL)
  • SMTP: smtp.gmail.com, port 465 (SSL) or 587 (TLS)

Outlook.com/Hotmail (use OAuth instead—see Outlook Setup Guide):

  • IMAP: outlook.office365.com, port 993 (SSL)
  • SMTP: smtp.office365.com, port 587 (TLS)

FastMail:

  • IMAP: imap.fastmail.com, port 993 (SSL)
  • SMTP: smtp.fastmail.com, port 465 (SSL)

ProtonMail Bridge:

  • IMAP: 127.0.0.1, port 1143 (STARTTLS)
  • SMTP: 127.0.0.1, port 1025 (STARTTLS)
  • Requires: ProtonMail Bridge app running locally

Self-Hosted / Unknown:

  • Check your email provider's documentation
  • Look for "IMAP settings" or "Mail client configuration"

Step 2: Create Account in MailDesk

  1. Open MailDesk app in Odoo
  2. Click Settings (gear icon) → Mailbox Accounts
  3. Click Create
  4. Fill in Account Details:
    • Name: Descriptive name (e.g., "Work Email", "Personal")
    • Email Address: [email protected]
    • Provider: Select "IMAP"

Step 3: Configure Incoming Mail (IMAP)

  1. Click Incoming Mail Server tab
  2. Fill in:
    • Server: IMAP hostname (e.g., imap.fastmail.com)
    • Port: Usually 993 for SSL
    • Security: Select "SSL/TLS"
    • Username: Usually your full email address
    • Password: Your email password or app-specific password
  3. Click Test Connection
    • ✅ Success: "Connection successful"
    • ❌ Failure: See troubleshooting below

Step 4: Configure Outgoing Mail (SMTP)

  1. Click Outgoing Mail Server tab
  2. Fill in:
    • Server: SMTP hostname (e.g., smtp.fastmail.com)
    • Port: Usually 465 (SSL) or 587 (TLS)
    • Security: Select "SSL/TLS" or "STARTTLS"
    • Username: Usually your full email address
    • Password: Same as IMAP password
  3. Click Test Connection
    • ✅ Success: "Email sent successfully"
    • ❌ Failure: See troubleshooting below

Step 5: Configure Folders

  1. Click Save to save account
  2. Click Sync Folders button
  3. MailDesk scans your IMAP server for all folders
  4. Select folders to sync:
    • ✅ Inbox (always recommended)
    • ✅ Sent (required for sent mail to appear)
    • ✅ Drafts (if you save drafts)
    • ⚠️ Trash (optional, shows deleted messages)
    • ⚠️ Archive (optional, for long-term storage)
    • ❌ Spam (usually not needed)
  5. Click Save

Step 6: Initial Sync

After saving:

  1. MailDesk automatically starts syncing
  2. Inbox syncs first (newest 50 messages)
  3. Messages appear within 5-30 seconds
  4. Older messages fetched progressively in background

Expected behavior:

  • First 50 messages: 5-30 seconds
  • Full mailbox (1000+ messages): 10-30 minutes (background)

IMAP-Specific Behavior

Sent Mail Handling

When you send an email via MailDesk:

  1. Email sent via SMTP immediately
  2. Local copy appears in Sent folder instantly
  3. IMAP APPEND: MailDesk copies message to your server's Sent folder (background)
  4. Next sync replaces local copy with server copy

Why this matters: You see sent mail immediately, even if IMAP APPEND is slow or fails.

UID-Based Sync

IMAP uses UIDs (unique identifiers) per folder:

  • UIDs are integers: 1, 2, 3, ...
  • UIDs are folder-specific (same message in different folders has different UIDs)
  • UIDs increment (newer messages have higher UIDs)
  • UIDVALIDITY: If server resets (backup restore), MailDesk re-syncs entire folder

User impact: Usually invisible, but explains why folder reset may re-download emails.

Folder Structure

IMAP folders are hierarchical:

  • INBOX (root inbox)
  • Sent or Sent Messages or Sent Items (provider-specific)
  • Drafts
  • Custom folders: Work, Projects/Client A, etc.

MailDesk flattens hierarchy (shows Projects/Client A as single folder name).

Common Issues & Solutions

Issue: "Connection Refused"

Symptoms: Cannot connect to IMAP server

Causes:

  1. Wrong server address or port
  2. Firewall blocking outbound connections
  3. IMAP not enabled on your account

Solutions:

  1. Double-check server address (copy from provider documentation)
  2. Try alternative ports: 993 (SSL), 143 (STARTTLS)
  3. Check provider settings:
    • Gmail: Enable "IMAP" in Gmail settings
    • Outlook: IMAP enabled by default
    • Self-hosted: Check with IT department

Issue: "Authentication Failed"

Symptoms: Server connection works, but login fails

Causes:

  1. Wrong username or password
  2. Provider requires app-specific password
  3. Two-factor authentication enabled without app password

Solutions:

  1. Verify credentials (try logging into webmail)
  2. Generate app-specific password:
    • Gmail: Use OAuth instead (see Gmail Setup)
    • Outlook: Use OAuth instead (see Outlook Setup)
    • Yahoo: Create app password in Yahoo Account Security
  3. Disable 2FA temporarily to test (not recommended long-term)

Issue: "No Sent Folder Found"

Symptoms: Sent messages don't appear in MailDesk

Causes:

  1. Sent folder not synced
  2. Sent folder has non-standard name

Solutions:

  1. Go to Settings → Mailbox Accounts → Sync Folders
  2. Look for folder named:
    • Sent
    • Sent Messages
    • Sent Items
    • Sent Mail
  3. Check the box to sync it
  4. If missing: Send test email via webmail, check where it appears, sync that folder

Issue: "Messages Appear Duplicated"

Symptoms: Same email shows up multiple times

Causes:

  1. Message exists in multiple folders (Inbox + Archive)
  2. IMAP server assigned same message different UIDs

Solutions:

  1. This is normal IMAP behavior (one message, multiple folders)
  2. MailDesk shows separate entries (one per folder)
  3. To avoid: Use IMAP MOVE instead of COPY when organizing

Issue: "Sync is Slow"

Symptoms: Messages take minutes to appear

Causes:

  1. Large mailbox (10K+ messages)
  2. Slow IMAP server
  3. Network latency

Solutions:

  1. MailDesk syncs newest 50 messages first (should be fast)
  2. Older messages fetched progressively (intentional design)
  3. Check IMAP server performance (try webmail access)

Security Recommendations

Use App-Specific Passwords

Why: Real password compromise = full account access

How:

  • Gmail: Google Account → Security → App Passwords
  • Yahoo: Account Security → Generate App Password
  • Self-hosted: Check with administrator

Enable TLS/SSL

Always use encrypted connections:

  • ✅ Port 993 (SSL/TLS)
  • ✅ Port 143 with STARTTLS
  • ❌ Port 143 without encryption (insecure)

Regular Password Rotation

Change IMAP password every 6-12 months, especially if:

  • Account used on shared/untrusted networks
  • Password reused across services
  • Provider recommends rotation

Provider-Specific Notes

FastMail

Strengths: Fast IMAP, reliable Notes: Supports CONDSTORE (efficient flag sync) Recommendation: ✅ Use IMAP

ProtonMail Bridge

Strengths: End-to-end encryption Notes: Requires local Bridge app running Server: 127.0.0.1 (localhost) Recommendation: ✅ Use IMAP via Bridge

Gmail / Outlook.com

Recommendation: ❌ Use OAuth instead

  • Faster (Gmail History API, Outlook Delta API)
  • More secure (no password storage)
  • Better sync (provider-specific optimizations)

See: Gmail Setup Guide, Outlook Setup Guide

Testing Your Setup

After configuration, test:

  1. Receive Test:
    • Send email to yourself from another account
    • Should appear in Inbox within 1-5 minutes (next sync cycle)
  2. Send Test:
    • Compose email to yourself in MailDesk
    • Click Send
    • Check Sent folder (should appear instantly)
    • Check Inbox (should arrive within 1-5 minutes)
  3. Threading Test:
    • Reply to an existing email
    • Check that reply appears in same conversation

What to Expect

Sync Frequency

  • Inbox: Every 5 minutes (automatic)
  • Other folders: Round-robin (every 10-15 minutes)
  • Manual refresh: Click refresh icon or Ctrl+R

Storage

  • Metadata: Stored in Odoo database
  • Full bodies: Cached for 7 days
  • Attachments: Fetched on-demand, cached temporarily

Limitations

  • Threading: Requires proper email headers (some older emails may not thread correctly)
  • Large mailboxes: 10K+ messages may take time for initial sync
  • Offline: Read-only (cannot send or modify flags offline)

Next Steps

✅ Setup complete → Read Daily Usage Guide to learn everyday features

✅ Need OAuth instead → Switch to Gmail Setup or Outlook Setup

✅ Having issues → See FAQ & Troubleshooting