GMAIL Account Setup Guide

What is Gmail Integration in MailDesk?

MailDesk connects to Gmail using Google's Gmail API, not standard IMAP. This provides:

• Faster sync: Gmail History API tracks changes efficiently
• Better reliability: API designed for client applications
• Proper threading: Gmail's native conversation support
• Label support: Gmail labels work as MailDesk folders

Important: MailDesk Gmail integration is not IMAP. It uses OAuth 2.0 and the Gmail API.

Why Gmail API Instead of IMAP?

Gmail IMAP (what most clients use):

• Slow (every sync queries all messages)
• Unreliable (connection issues, throttling)
• No history tracking

Gmail API (what MailDesk uses):

• Fast (History API only fetches changes)
• Reliable (built for applications)
• Efficient (incremental updates only)

You cannot use Gmail via IMAP in MailDesk — use the Gmail account type instead.

Prerequisites

Before connecting Gmail to MailDesk:

• ✅ Gmail or Google Workspace account
• ✅ Administrator must have configured Google OAuth (see Admin Guide)
• ✅ Browser with access to your Gmail account

Note: First-time Gmail connection requires administrator OAuth setup. Contact your Odoo administrator if you see "OAuth not configured" error.

Step 1: Create Gmail Account in MailDesk

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

Step 2: Authorize Gmail Access

1. After saving, click Authorize Gmail button
2. Browser redirects to Google login page
3. If not logged in: Enter your Gmail credentials
4. If logged in: Google shows account picker

What you'll see:

Google Account Permissions Request

MailDesk wants to access your Google Account

This will allow MailDesk to:
✓ Read, compose, send, and permanently delete emails from Gmail
✓ See your primary Gmail email address

[Cancel] [Allow]

1. Click Allow
2. Browser redirects back to MailDesk
3. Account status changes to "Connected"

What Permissions MailDesk Requests

Scope: https://www.googleapis.com/auth/gmail.readonly

• Read emails (subject, sender, body, attachments)
• Access labels and folder structure

Scope: https://www.googleapis.com/auth/gmail.modify

• Mark messages as read/unread
• Star/unstar messages
• Apply labels (folders)
• Move messages
• Delete messages

Scope: https://www.googleapis.com/auth/gmail.send

• Send emails on your behalf

Why these permissions?

• Read: Required to show your emails in MailDesk
• Modify: Required for mark-as-read, starring, organizing
• Send: Required to send emails from MailDesk

Does MailDesk see my password? No. OAuth means Google handles login. MailDesk never sees your password.

What Happens After Connection

Immediate: Folder Discovery

MailDesk scans your Gmail labels and maps them to folders:

System Labels:

• INBOX → "Inbox"
• SENT → "Sent"
• DRAFT → "Drafts"
• TRASH → "Trash"
• SPAM → "Spam" (usually not synced)

Custom Labels:

• Work/Projects → "Work/Projects"
• Important → "Important"

Note: Gmail labels are not folders. One email can have multiple labels, so it appears in multiple MailDesk folders.

Step 1: Bootstrap Sync (Newest Messages First)

Timeline: 5-30 seconds

What happens:

1. MailDesk fetches newest 50 messages from Inbox
2. Messages appear in MailDesk UI immediately
3. Other folders (Sent, Drafts) synced next

Why only 50? Bootstrap prioritizes instant usability. Older messages fetched progressively (see below).

Step 2: Incremental Sync (New Messages)

Timeline: Every 5 minutes (automatic)

What happens:

1. MailDesk calls Gmail History API
2. Fetches only changes since last sync:
   • New emails
   • Deleted emails
   • Label changes (folder moves)
   • Read/unread flag changes
3. Updates MailDesk SSOT
4. UI refreshes automatically

Gmail History Explained:

• Gmail tracks every change with a historyId
• MailDesk stores last historyId, fetches newer changes only
• Efficient: No need to scan entire mailbox

Step 3: Progressive Backfill (Older Messages)

Timeline: Background, over hours

What happens:

1. After bootstrap, MailDesk starts fetching older messages
2. Batch size: 200 messages per hour (controlled budget)
3. Older messages appear progressively
4. Continues until entire mailbox synced

Why slow?

• Prevents overwhelming Gmail API quota
• Prioritizes recent emails (you read most often)
• Background: doesn't block UI

Example Timeline:

• 0-30 seconds: Newest 50 messages (Inbox)
• 5 minutes: Sent, Drafts synced
• 1 hour: 200 older messages fetched
• 5 hours: 1000 total messages synced
• 1 day: 5000+ messages synced (depending on mailbox size)

Gmail-Specific Behavior

Labels = Virtual Folders

Important: Gmail labels are NOT folders.

IMAP folders: One message, one folder Gmail labels: One message, multiple labels

Example:

Email: "Meeting tomorrow"
Labels: INBOX, Work, Important

MailDesk shows this email in:
- Inbox folder
- Work folder
- Important folder

Same email, three places.

Why: Gmail's label system allows multi-categorization.

User Impact: Deleting from one folder removes label, but message stays in other folders.

Sent Mail Behavior

When you send an email via MailDesk:

1. Immediately: Message appears in MailDesk Sent folder (local entry)
2. Background: Gmail automatically archives sent mail with SENT label
3. Next sync (within 5 minutes): Gmail's copy replaces local entry

Why local entry? Gmail takes 5-30 seconds to archive sent mail. Local entry prevents "sent mail disappeared" UX.

Result: Sent mail always visible immediately, seamlessly replaced by Gmail's copy.

"All Mail" vs Specific Labels

Gmail's "All Mail":

• Virtual folder containing every email
• Not synced by MailDesk (would duplicate all messages)

MailDesk syncs:

• INBOX
• Specific labels (Work, Important, etc.)
• System labels (Sent, Drafts, Trash)

Finding archived mail:

• If email has no labels, it's only in "All Mail" (Gmail's archive)
• MailDesk won't show it (no folder mapping)
• Apply a label in Gmail webmail → appears in MailDesk

Common Issues & Solutions

Issue: "OAuth Not Configured"

Symptoms: "Authorize Gmail" button shows error

Cause: Administrator hasn't configured Google OAuth client

Solution: Contact your Odoo administrator. They must:

1. Create Google Cloud project
2. Enable Gmail API
3. Configure OAuth client
4. Add credentials to Odoo

See: Admin Guide

Issue: "Messages Not Appearing Immediately"

Symptoms: Sent an email in Gmail webmail, doesn't show in MailDesk

Cause: Sync runs every 5 minutes, not realtime

Solution:

• Wait 1-5 minutes for next sync cycle
• OR click Refresh icon in MailDesk
• OR open/close folder to trigger manual refresh

This is normal Gmail API behavior (not a bug).

Issue: "Old Messages Loading Slowly"

Symptoms: Can only see recent emails, older messages missing

Cause: Progressive backfill in progress

Solution:

• Wait: Backfill fetches 200 messages/hour automatically
• Check tomorrow: Most mailboxes fully synced within 24-48 hours
• For 10K+ mailboxes: May take several days

This is intentional design (prevents API quota exhaustion).

Issue: "History ID Expired"

Symptoms: MailDesk shows "Full folder resync required"

Cause: Gmail History API expires after ~7 days of inactivity

What happens:

1. MailDesk detects expired historyId
2. Automatically resets folder
3. Re-bootstraps newest 50 messages
4. Progressive backfill restarts

User Impact: Brief delay (30-60 seconds), then normal sync resumes

Prevention: Use MailDesk at least once per week

Issue: "Re-Authorization Required"

Symptoms: "Gmail authentication expired, please re-authorize"

Cause: OAuth token revoked (password changed, security issue, manual revoke)

Solution:

1. Go to Settings → Mailbox Accounts
2. Click your Gmail account
3. Click Re-Authorize Gmail
4. Log in again

Why: OAuth tokens can expire for security reasons. This is normal.

Issue: "Message Appears in Multiple Folders"

Symptoms: Same email shows in Inbox, Work, Important

Cause: Gmail labels (not duplicate emails)

Explanation: This is expected Gmail behavior. One email, multiple labels = multiple folders.

To remove:

• Go to one folder
• Delete or archive message
• Removes from that folder only
• Stays in other folders (other labels intact)

To delete completely:

• Move to Trash
• OR delete from all folders

Unread Counts and Consistency

Eventually Consistent Unread Counts

Gmail unread counts in MailDesk are eventually consistent:

1. Sync runs every 5 minutes
2. Unread count updated at END of sync
3. Badge updates via websocket

Scenarios:

• Mark read in Gmail webmail → MailDesk badge updates within 5 minutes
• Mark read in MailDesk → Badge updates immediately (optimistic), confirmed by sync

This is intentional (balance between accuracy and performance).

Testing Your Setup

After connection, verify:

Test 1: Receive Email

1. Send email to yourself from another account
2. Wait 1-5 minutes (next sync cycle)
3. Check MailDesk Inbox → should appear

Test 2: Send Email

1. Compose email in MailDesk
2. Send
3. Check Sent folder → should appear immediately
4. Check recipient → should receive

Test 3: Threading

1. Reply to an existing email thread
2. Check conversation view → reply appears in thread

Test 4: Label/Folder Change

1. Apply a label in Gmail webmail
2. Wait 5 minutes
3. Check MailDesk → message appears in new folder

Performance Expectations

Sync Speed

• New emails: Appear within 1-5 minutes (sync frequency)
• Sent emails: Appear immediately (local-first)
• Label changes: Reflected within 1-5 minutes

Storage

• Metadata: Stored in Odoo database (~1KB per message)
• Full bodies: Cached for 7 days, re-fetched on demand
• Attachments: Fetched on first open, cached temporarily

API Quota

Google provides generous quotas:

• 1 billion quota units/day per project
• users.messages.list: 5 units per request
• users.history.list: 2 units per request

Typical usage: 1000-10000 units/day per user (well under limit)

Privacy & Security

What Google Knows

• Google knows MailDesk requested access to your Gmail
• Google logs OAuth token grants
• Google can revoke access anytime

What MailDesk Stores

• Access token: Stored encrypted in Odoo database
• Refresh token: Used to renew access automatically
• Metadata: Subject, sender, date (in message_index)
• Bodies: Cached temporarily (7-day TTL)

What MailDesk Does NOT Store

• ❌ Your Gmail password (OAuth handles auth)
• ❌ Permanent email bodies (cached with expiry only)
• ❌ Attachment binaries (fetched on-demand)

Revoking Access

To disconnect MailDesk from Gmail:

1. In MailDesk: Delete account → Settings → Mailbox Accounts → Delete
2. In Google: Revoke app access
   • Go to Google Account Security
   • Find "MailDesk"
   • Click "Remove Access"

Effect: MailDesk can no longer access your Gmail. Existing cached data remains in Odoo until manually deleted.

Gmail vs Outlook vs IMAP

Recommendation: If you have Gmail or Google Workspace, use Gmail account type (not IMAP).

Next Steps

✅ Account connected → Read Daily Usage Guide to learn features (to be created)

✅ Need multiple accounts → Repeat setup for each Gmail address

✅ Having issues → See FAQ & Troubleshooting (to be created)

✅ Administrator setup → See Gmail OAuth Setup Admin Guide