📄 Google IMAP
Sign in

Google IMAP


What is “Google IMAP” in MailDesk?

MailDesk supports Gmail in two modes:

  1. Gmail OAuth (recommended)

    Connect via “Sign in with Google”. Uses Gmail API (fast incremental sync).

  2. Gmail via IMAP (this article)

    Connect Gmail like a classic mail client using IMAP/SMTP + App Password.

Use IMAP mode if:

  • Your company (Google Workspace) blocks OAuth for third-party apps

  • You can’t do the OAuth admin setup

  • You explicitly want classic IMAP/SMTP

❗Important:

  • IMAP mode is NOT the Gmail OAuth mode.

    If you want IMAP, create the mailbox account as Provider = IMAP, not “Gmail”.

🐢 Technical Limitation: No History API

Please note that Gmail via IMAP does NOT support the Gmail History API. Synchronization in this mode relies on standard periodic polling (every 3 minutes), which is slower and more resource-intensive than the recommended OAuth method.



Before you start (requirements)

To use Gmail via IMAP you need:

  • A Gmail / Google Workspace account

  • IMAP access enabled

  • In most cases: 2-Step Verification enabled and an App Password (recommended/required)

Why App Password?

Google does not want you to use your main Gmail password in mail clients when 2-Step Verification is enabled. Instead you generate an App Password (a special 16-character password) for IMAP/SMTP.


Step 1 — Enable IMAP in Gmail

Personal Gmail

  1. Open Gmail in browser

  2. Settings (⚙) → See all settings

  3. Tab Forwarding and POP/IMAP

  4. In IMAP access: choose Enable IMAP

  5. Save

Google Workspace (company accounts)

Your admin may restrict IMAP. If IMAP cannot be enabled or login fails even with correct credentials, ask your Workspace admin to allow IMAP for your organization/users.


Step 2 — Create a Google App Password (recommended)

App Passwords are available only if 2-Step Verification is enabled (and not blocked by your Workspace policy).

Create App Password (short, user-friendly)

  1. Open your Google Account → Security

  2. Enable 2-Step Verification (if not enabled)

  3. Open App passwords

  4. Create a new password:

    • App: Mail

    • Device: choose your device or Other

  5. Copy the generated password (usually 16 characters)

  6. Use this password in MailDesk for both IMAP and SMTP

Notes:

  • If “App passwords” is missing, your organization may have disabled it → use Gmail OAuth instead, or ask your admin.

  • Treat App Password like a real password: store it in a password manager.


Step 3 — Configure Gmail as IMAP in MailDesk

In Odoo → MailDesk → Settings (⚙) → Mailbox Accounts → Create

Incoming (IMAP)

  • Server: imap.gmail.com

  • Port: 993

  • Security: SSL/TLS

  • Username: full Gmail address

  • Password: App Password (not your normal Google password)

Outgoing (SMTP)

  • Server: smtp.gmail.com

  • Port: 465 (SSL) or 587 (STARTTLS)

  • Username: full Gmail address

  • Password: same App Password (not your normal Google password)

Then:

  1. Test & Confirm (IMAP)

  2. Test Connection (SMTP)

  3. Sync Folders (fetch folder list)

  4. Select folders you want to sync (Inbox, Sent, Drafts…)


OAuth vs IMAP — what to tell customers (simple)

Gmail OAuth (recommended)

  • “Sign in with Google”

  • No password stored in Odoo

  • Fast incremental sync (API)

  • Best option if allowed

Gmail IMAP (App Password)

  • Manual server settings + App Password

  • Works like a classic mail client

  • Often slower than API

  • Might be restricted by Workspace security policies

Rule of thumb:

If user can click Authorize / Sign in with Google → choose OAuth.

If OAuth is blocked → choose IMAP + App Password.

Common problems (and the exact fix)


1) “Authentication failed” / “Invalid credentials”

Cause: You used the normal Google password instead of App Password, or IMAP is disabled.
Fix: Enable IMAP + generate App Password.


2) “App passwords” not available in Google Account

Cause: 2-Step Verification disabled, or Workspace policy blocks App Passwords.
Fix: Enable 2-Step Verification or use Gmail OAuth; if Workspace blocks, contact admin.


3) “Gmail OAuth2 missing access token / You don’t have an active subscription”

Cause: You created the account as Gmail OAuth (or system detected Gmail OAuth path) and Odoo tried to refresh token via IAP.
Fix: If you want IMAP: create provider IMAP and use App Password.

If you want OAuth: admin must configure Google OAuth credentials in Odoo (Client ID/Secret) and re-authorize.


4) Folders missing / Sent folder not shown

Cause: Gmail/IMAP folder naming differences (Sent Mail vs Sent).
Fix: Run Sync Folders and select the correct Sent folder.

Security notes

  • Always use SSL/TLS (IMAP 993, SMTP 465/587).

  • Never share App Password in tickets/screenshots.

  • Revoke/rotate App Password if it’s compromised.

Quick checklist (copy/paste block)

  • IMAP enabled in Gmail settings

  • 2-Step Verification enabled

  • App Password created (16 characters)

  • MailDesk Provider = IMAP (not Gmail OAuth)

  • IMAP imap.gmail.com:993 SSL

  • SMTP smtp.gmail.com:465 SSL or 587 STARTTLS

  • Username = full email

  • Password = App Password

  • Sync Folders + select Inbox/Sent/Drafts