MailDesk docs
Get MailDesk
Basic and Pro

Gmail OAuth setup (administrator)

Connect Gmail and Google Workspace mailboxes to MailDesk using Google's OAuth2 sign-in, so that no email password is ever stored in Odoo. This page is for the Odoo administrator who configures the connection once for the whole company. After it is done, each user (or the administrator) authorizes individual Gmail mailboxes with a single Google sign-in.

7 min read Basic and Pro

Connect Gmail and Google Workspace mailboxes to MailDesk using Google's OAuth2 sign-in, so that no email password is ever stored in Odoo. This page is for the Odoo administrator who configures the connection once for the whole company. After it is done, each user (or the administrator) authorizes individual Gmail mailboxes with a single Google sign-in.

Available in: Basic and Pro. Gmail OAuth is part of the MailDesk engine, so the setup is identical on both. Pro adds two-way sync and other features on top of the same Gmail connection — no extra Gmail configuration is required for Pro.

There is also a no-OAuth option

If your organization cannot use OAuth, Gmail can instead be connected as a classic IMAP/SMTP account using a Google App Password. That path needs none of the steps on this page — see IMAP / SMTP setup. The OAuth path described here is the recommended one: faster sync, no stored password, and access you can revoke at any time from your Google account.

What it does

You register a Google OAuth application once (in the Google Cloud console), then enter its Client Id and Client Secret into MailDesk. From then on, connecting a Gmail mailbox is a one-time Google sign-in: Google handles the login and returns a revocable access token to MailDesk. MailDesk never sees or stores the Gmail password.

Why it matters

  • No passwords stored. Authentication happens on Google's side; MailDesk holds only tokens, which you can revoke from your Google account at any time.
  • Efficient sync. The connection uses the Gmail API, which fetches only what changed since the last sync rather than rescanning the whole mailbox.
  • One company-wide setup. You configure the credentials once; users then connect their own mailboxes without needing the Client Id or Secret.

Requirements

  • A Google account that can create a project in the Google Cloud console (a Google Workspace admin account is ideal for company deployments).
  • Your Odoo server reachable over HTTPS at a stable public address. Google rejects OAuth redirects to plain http:// (other than http://localhost for local testing).
  • Administrator access to Odoo, including the technical settings.
  • MailDesk works on Odoo 17, 18, or 19 — the steps below are the same on each.

Permissions required

  • The OAuth credentials fields are restricted to Odoo Settings administrators (the Administration: Settings access group). Only such a user can view or change the Gmail Client Id and Secret.
  • Creating mailbox accounts and authorizing them is available to MailDesk administrators.

Step 1 — Create a Google Cloud project

  1. Open the Google Cloud console.
  2. In the top bar, open the project selector and choose New Project.
  3. Give it a clear name (for example MailDesk), pick your organization if you have one, and confirm. Wait a few seconds for the project to be created, then select it.

Creating a new project in the Google Cloud console

Step 2 — Enable the Gmail API

  1. Go to APIs & Services → Library.
  2. Search for Gmail API and open it.
  3. Click Enable.

You can confirm it later under APIs & Services → Enabled APIs & services.

Finding the Gmail API in the API Library

  1. Go to APIs & Services → OAuth consent screen.
  2. Choose the user type:
    • Internal — recommended for Google Workspace organizations. Only people in your organization can authorize, and no Google verification is needed.
    • External — needed if you must connect personal @gmail.com accounts or several organizations. In Testing mode you may add up to 100 named test users; going beyond that requires Google's app-verification review.
  3. Fill in the application details: an app name (for example MailDesk), a user-support email, and a developer-contact email. Under Authorized domains, add your Odoo server's domain without the https:// prefix (for example erp.example.com).
  4. On the scopes step, add the four Gmail scopes MailDesk uses (see the table below), then save and continue.

Choosing the OAuth audience — Internal or External

The OAuth app publishing status — move it out of Testing when you are ready for production

Scopes MailDesk requests

Scope Why MailDesk needs it
https://www.googleapis.com/auth/gmail.readonly Read messages, labels, and folder structure
https://www.googleapis.com/auth/gmail.modify Mark read/unread, star, apply labels, move messages
https://www.googleapis.com/auth/gmail.send Send mail from MailDesk
https://www.googleapis.com/auth/gmail.compose Save and manage drafts

Same four scopes on Basic and Pro

These four Gmail scopes are requested whether the customer runs Basic or Pro. Two-way actions such as marking read and moving messages are part of the engine; Pro builds its additional features on top of the same Gmail access.

Step 4 — Create the OAuth client credentials

  1. Go to APIs & Services → Credentials.
  2. Click Create Credentials → OAuth client ID.
  3. For Application type, choose Web application and give it a name.

  4. Under Authorized redirect URIs, add exactly:

    https://YOUR-ODOO-DOMAIN/google_gmail/confirm

    Replace YOUR-ODOO-DOMAIN with your Odoo address — for example https://erp.example.com/google_gmail/confirm.

  5. Click Create. Google shows the Client ID and Client Secret. Copy both.

The Credentials screen where you create the OAuth client for the project

The redirect URI must match exactly

MailDesk always sends Google to {web.base.url}/google_gmail/confirm. The value in the Google console must match character-for-character: same scheme (https), same domain, no trailing slash, no typo. A mismatch is the most common cause of a redirect_uri_mismatch error.

Step 5 — Enter the credentials in MailDesk

MailDesk stores the Gmail Client Id and Secret per company. There are two equivalent places to enter them; use whichever fits your setup.

Option A — MailDesk settings

  1. In Odoo, go to Settings, open the MailDesk section, and find the OAuth Settings block.
  2. Turn on Use a Gmail Server.
  3. Enter the Google ID and Secret from Step 4.
  4. Save.

The values you see and edit here belong to the company selected in the top-right company switcher.

Option B — Company form

  1. Go to Settings → Users & Companies → Companies and open the company.
  2. Open the Mail OAuth tab.
  3. Under Gmail OAuth, fill in Gmail Client Id and Gmail Client Secret.
  4. Save.

Multi-company and the legacy fallback

MailDesk reads the credentials in a fixed order: it uses the company's Gmail Client Id and Secret first, and only if those are empty does it fall back to the older system-wide Gmail credentials kept in Odoo's system parameters. Set the values on each company that operates Gmail mailboxes. When you upgrade an existing single-company install, MailDesk automatically copies any previous system-wide Gmail credentials onto your main company so nothing breaks — but the per-company fields are now the place to manage them.

Step 6 — Check the Odoo base URL

MailDesk builds the redirect URI from Odoo's base URL, so it must match what you registered in Google.

  1. Go to Settings → Technical → System Parameters.
  2. Find web.base.url. It should be your public HTTPS address with no trailing slash (for example https://erp.example.com).
  3. Correct it if needed and save.

Step 7 — Connect and authorize a Gmail mailbox

  1. Go to MailDesk → Configuration → Mailboxes → Mailbox Accounts and create a new account.
  2. Set the account name and the Gmail email address, and link it to a Gmail incoming mail server (an incoming server whose type is the Gmail OAuth option). Save.
  3. Complete the Google sign-in for that mail server when prompted, and grant the requested permissions. Google returns you to Odoo, and the mailbox begins syncing.

Gmail authorization happens on the mail server

Unlike Outlook, Gmail does not use a dedicated button on the mailbox account form. The Google sign-in is driven by the standard Gmail incoming-server flow, using the company credentials you entered above.

Expected result

After authorization the mailbox connects and MailDesk starts an initial fill of the newest messages, then continues loading history in the background through its scheduled background jobs. New mail then arrives automatically on the regular sync schedule.

Troubleshooting

Symptom Likely cause What to do
redirect_uri_mismatch from Google The redirect URI in Google does not exactly match {web.base.url}/google_gmail/confirm Compare web.base.url (Step 6) with the Google console value; fix scheme, domain, and any trailing slash
Gmail authorization shows a "not configured" style error The Gmail Client Id or Secret is empty for this company Enter them via Step 5; confirm you are on the correct company
Google shows "This app isn't verified" An External consent screen without verification Use Internal for a Workspace org, or add the user as a test user in Testing mode, or submit for verification
"Access blocked: invalid request" A scope is missing on the consent screen Re-open the consent screen and confirm all four scopes from Step 3 are present
Sync stops and Gmail asks to sign in again The stored authorization was revoked or expired Re-run the Google sign-in for that mailbox's incoming server
A subscription-related token-refresh error appears Odoo fell back to its built-in IAP token path instead of your own credentials Make sure the company Gmail Client Id and Secret are set (Step 5), then re-authorize so a fresh token is stored

Handling the Client Secret responsibly

  • The Client Id and Secret are stored in the Odoo database and are visible only to Settings administrators. They are never written to logs.
  • Treat the Secret like any credential: do not paste it into tickets, chat, or version control. Rotate it periodically and after any suspected exposure by creating a new client secret in the Google console and updating the value in MailDesk (Step 5).
  • For separate dev / staging / production servers, register a separate redirect URI (or a separate OAuth client) per environment so each environment has its own credentials.