MailDesk docs
Get MailDesk
Basic and Pro

Troubleshooting

The most common MailDesk issues and how to resolve them. Most problems come down to sync timing, account configuration, or email-provider behaviour — and usually clear up on their own within a few minutes. Work through the section that matches what you are seeing before contacting support.

9 min read Basic and Pro

The most common MailDesk issues and how to resolve them. Most problems come down to sync timing, account configuration, or email-provider behaviour — and usually clear up on their own within a few minutes. Work through the section that matches what you are seeing before contacting support.

Available in: Basic and Pro. Synchronisation, OAuth, and sent-mail behaviour are part of the MailDesk engine (Basic). The AI section applies to Pro only.

First, give it a moment

MailDesk synchronises in the background and is near-real-time, not instant. Most "missing email" reports are simply mail that is still on its way in. Waiting a minute or two — or refreshing the view — resolves the majority of timing issues.

Emails are missing or delayed

What is normal

MailDesk checks each connected mailbox on a schedule using scheduled background jobs, so new mail typically appears within a couple of minutes rather than the instant it arrives. Short delays are expected and depend on the provider and on system load. Once a message is indexed, the open MailDesk screen updates on its own.

New mail has not appeared yet

  1. Refresh the MailDesk view.
  2. Wait a moment for the next background synchronisation.
  3. Confirm the mailbox is connected (see Mailbox is disconnected).
  4. Confirm the message actually arrived in your provider's own webmail (Gmail / Outlook). If it is not there either, it simply has not been delivered yet.

Older emails seem to be missing

When a mailbox is first connected, MailDesk loads the newest messages first so you can start working immediately, then fills in older history gradually in the background. During this initial fill:

  • leave MailDesk open and give the background fill time to complete;
  • avoid disconnecting and reconnecting the account repeatedly — that restarts the work.

If specific older messages in one folder still have not arrived after the initial fill, an administrator can force a deeper historical fetch for that folder:

  1. Go to MailDesk → Configuration → Mailboxes → Mailbox Accounts and open the account.
  2. Open the Folders tab and select the folder.
  3. Click Trigger Backfill to start a deep historical fetch for that folder.

A folder shows "0 emails"

A folder only fills if it is selected for synchronisation:

  1. Open the mailbox account and the Folders tab.
  2. Make sure the folder is visible / selected for sync.
  3. Confirm in your webmail that the folder actually contains messages.

Gmail uses labels, not folders

On Gmail, a single message can appear under several labels at once — for example in both its conversation label and in All Mail. MailDesk reflects this, so the same email may show in more than one place. This is normal Gmail behaviour, not duplication. Make sure you are looking at the label you expect.

When to investigate further

Look more closely (or escalate) if no new mail appears for a long time, connection tests fail, error messages are shown, or synchronisation has not progressed at all. In those cases, check OAuth and re-authorization and the IMAP connection settings, and see Where an administrator looks.

OAuth and re-authorization

This applies to Gmail and Outlook / Microsoft 365 mailboxes. Most OAuth problems are configuration issues, not faults in MailDesk.

"OAuth not configured"

What it means: the Google or Microsoft OAuth credentials are missing or incomplete in Odoo, so MailDesk cannot start the sign-in flow.

What to do: this is an administrator task. The administrator configures the provider once for the company:

Once the credentials are in place, start the mailbox authorisation again.

"Authorization expired" / "Re-authorization required"

OAuth tokens do not last forever, access can be withdrawn from the provider side, and some security policies force periodic re-consent. The fix is to sign in again:

  1. Go to MailDesk → Configuration → Mailboxes → Mailbox Accounts and open the affected account.
  2. Start the provider sign-in again and grant access:
    • Outlook / Microsoft 365: click Connect Microsoft Graph (OAuth) on the account and complete the Microsoft sign-in.
    • Gmail: re-run the Google sign-in for the mailbox's incoming mail server (Gmail's authorisation runs on the incoming server, not on a button on the account form — see Gmail setup).

No data is lost during re-authorization — your synced mail stays in place.

"Access denied" during sign-in

Usually the requested permissions were not granted, or — on Microsoft 365 — tenant admin consent is missing.

  • Read the permission screen carefully during sign-in and accept the requested permissions.
  • For Microsoft 365, make sure an administrator has granted admin consent for the app.
  • Ask your administrator to review any tenant restrictions or conditional-access policies.

Authorization succeeds but mail does not sync

If sign-in works but no mail comes in, the issue is usually network or rate-limiting rather than authorisation:

  • Confirm the Odoo server has outbound internet access to the provider.
  • Check that the provider's API is available and not rate-limiting your account.
  • MailDesk retries automatically; give it a sync cycle or two before escalating.

Resetting access cleanly

If you want to start over, you can safely reset OAuth access and reconnect:

  • Gmail: remove the mailbox account in MailDesk, revoke app access in Google Account → Security, then reconnect.
  • Outlook / Microsoft 365: remove the mailbox account in MailDesk, revoke the app in Microsoft Entra / Azure AD, then reconnect.

Sent mail does not appear

Why a sent email can seem to "disappear"

When you click Send, MailDesk does the following:

  1. sends the email immediately through your outgoing (SMTP) server;
  2. shows it in Sent right away as a local entry;
  3. your email provider saves its own copy in the provider's Sent folder;
  4. the next synchronisation replaces the local entry with the provider's copy.

That brief swap is normal — it is how MailDesk avoids leaving you with duplicate sent messages. If a message seems to vanish and reappear, it is being replaced by the provider's copy.

Check the correct Sent folder

Providers name their Sent folder differently — Sent, Sent Items, or Sent Mail.

  1. Confirm which Sent folder is selected for synchronisation on the mailbox account.
  2. Check your webmail to see where that provider stores sent messages.

Provider-specific notes:

  • Gmail labels sent mail automatically; MailDesk replaces the local copy after sync, and a short delay is normal.
  • Outlook / Microsoft 365 stores sent mail in Sent Items; the server copy replaces the local one, on Microsoft Graph's sync timing.
  • Classic IMAP servers do not all save sent mail automatically. MailDesk relies on the Sent folder you selected, so the folder mapping must match how your server actually behaves.

If sending failed

If the email never sent, it is not lost — it stays in Drafts:

  1. Open Drafts and confirm the message is there.
  2. Review the outgoing-server (SMTP) connection.
  3. Try sending again.

If sending fails repeatedly, error messages appear, or an SMTP test fails, ask your administrator to check the outgoing-server configuration and the mail logs (see Where an administrator looks).

Mailbox is disconnected

If MailDesk shows a mailbox as disconnected, or new mail simply stops arriving:

  1. Open the mailbox account under MailDesk → Configuration → Mailboxes → Mailbox Accounts.
  2. Check the connection status.
  3. For OAuth mailboxes (Gmail, Outlook), re-run the provider sign-in — see OAuth and re-authorization.
  4. For classic IMAP mailboxes, verify the credentials and use Test Incoming Server (and Test Outgoing Server for sending).
  5. If you recently changed your provider password, an OAuth mailbox needs to be re-authorised and an IMAP mailbox needs the new password entered.

Tip

If the connection test fails repeatedly, ask your Odoo administrator to check the provider settings and confirm the Odoo server can reach the provider over the internet.

An AI action is unavailable (Pro)

Available in: Pro. Basic has no AI.

If an AI action such as Summarize current, Draft from context, or Check with AI is greyed out or fails:

  • Confirm an administrator has configured at least one AI provider — see What MailDesk AI can and cannot access.
  • For very long threads the provider may briefly rate-limit; try again in a minute.
  • Confirm the mailbox has Enable AI features switched on, on its Mailbox Account form (see Security & access rights).
  • Confirm AI has not been turned off system-wide. The global and per-feature switches live under Settings → Technical → System Parameters: maildesk.ai.enabled turns all AI on or off at once, and maildesk.ai.feature.<feature>.enabled controls a single feature. Both are on by default; AI is off only if one of these is set to 0.
  • Confirm the mailbox is running MailDesk Pro — AI features are not part of Basic.

A Workflow Bridge action is missing on a record

If a bridge action such as Create lead, Create ticket, or Link to order does not appear where you expect it:

  • Confirm the matching Workflow Bridge module is installed (CRM, Helpdesk, Calendar, Documents, Sales, Partner 360, Chatter, or Automation).
  • Confirm the bridge is enabled on the mailbox — open the mailbox account and check the bridge settings.
  • Confirm you have read access to the target Odoo app. You cannot link an email to a CRM lead if you have no access to CRM.
  • For shared mailboxes, an administrator can enable the bridge for the whole team.
  • If a smart-button count on an Odoo record looks wrong, refresh the form — the count updates on the next synchronisation.

Every bridge requires MailDesk Pro.

Where an administrator looks

When timing or sync behaviour needs a closer look, an administrator can inspect MailDesk's background activity directly in Odoo.

  • Scheduled background jobs: Settings → Technical → Scheduled Actions. The MailDesk synchronisation, import, and maintenance jobs run here; their last-run time and status show whether synchronisation is progressing.
  • Outgoing mail / sending problems: the standard Odoo mail logs and the Test Outgoing Server action on the mailbox account.
  • Connectivity: confirm the Odoo server can reach the email provider over the internet (firewall / outbound rules), and that the provider's API is available.

How synchronisation behaves under failure

MailDesk is built to degrade gracefully. Transient problems (network timeouts, provider rate limits) are retried automatically with a back-off delay. A problem in one folder does not stop the others. If a provider resets a folder or an authorisation expires, MailDesk re-fetches that folder from scratch or asks for re-authorisation rather than losing data.

When to contact support

Contact your administrator or Metzler IT support if:

  • OAuth cannot be configured, or authorisation fails repeatedly even after re-authorising;
  • connection or SMTP tests fail consistently;
  • errors appear repeatedly, or you suspect a server or firewall issue;
  • you have a valid licence but it is not recognised, or the activation screen shows an error you cannot resolve.

To help support help you faster, include:

  • the email provider (Gmail / Outlook / IMAP),
  • the exact error message, if any,
  • what you expected versus what happened, and roughly when.