MailDesk docs
Installation and first setup

Install MailDesk: choose your setup

4 min read Odoo 18.0

This page helps you pick the right installation guide, then shows how to install the MailDesk modules in Odoo.

Who this is for: the Odoo administrator who installs MailDesk for the first time. You need: Odoo administrator access, and either access to your Odoo.sh Git repository or to the server that runs Odoo.

Step 1: choose your hosting

Where does your Odoo run? What to do
Odoo.sh Follow Install on Odoo.sh.
Your own server, VPS, on-premise or Docker Follow Install on your own server.
Odoo Online MailDesk cannot be installed. Odoo Online does not allow custom modules or modules from the Odoo Apps Store. You need Odoo.sh or your own server.

The two guides put the module files in the right place. Come back to this page for the Odoo steps in Install the modules.

Before you begin

  • Odoo version. You need Odoo 17, 18, 19 or 20. Features can differ between versions. Download the MailDesk files that match your Odoo version.
  • Edition. The plan you bought decides which modules you may install. See Plans and included features.
  • Backup. Take a full database backup.
  • Staging first. Test the installation on a staging or development copy before you touch production.
  • Public HTTPS address. You need one if you connect Gmail or Microsoft 365 with OAuth sign-in (see For server administrators below).
  • Licence key. Have your licence key ready. You activate it after installation: Activate your license.

Prefer not to do this yourself?

Metzler IT offers an installation service that is quoted separately on request. It is not included with the licence.

Install the modules

Do this after the module files are on your Odoo.sh repository or your server, and Odoo has restarted or the Odoo.sh build is green.

  1. Log in to Odoo as an administrator and turn on developer mode.
  2. Open Apps.
  3. Click Update Apps List and confirm.
  4. Remove the Apps filter in the search box, then search for MailDesk.
  5. On MailDesk Basic, click Install.
  6. Install MailDesk Pro and any bridge modules only if they are part of your purchase.

What you should see: after step 5, a MailDesk menu in the top bar. Administrators also see Configuration inside it.

Odoo installs the modules a module depends on. You do not have to follow a fixed order.

If it does not work

  • MailDesk is not in the Apps list. The module folders are not on a configured addons path, or Odoo did not restart. Check the hosting guide, then click Update Apps List again.
  • Odoo reports a missing Python module when you install. Install the Python packages in the section below, restart Odoo, and try again.
  • A module cannot be installed because another app is missing. A bridge needs its Odoo app (for example CRM or Helpdesk). Install that Odoo app first, or skip the bridge. Some Odoo apps, such as Documents and Helpdesk, are Odoo Enterprise apps.

Next step

Activate your license, then connect your first mailbox.


For server administrators: requirements

Modules and dependencies

Module Technical name Needs
MailDesk Basic maildesk_mail_client Odoo apps web, contacts, mail, microsoft_outlook, google_gmail
MailDesk Pro maildesk_mail_client_pro MailDesk Basic
Automation Engine maildesk_mail_client_automation Basic and Pro
Calendar integration maildesk_mail_client_calendar Basic, Pro, Odoo Calendar
Chatter integration maildesk_mail_client_chatter Basic and Pro
Cockpit (Odoo 18 only) maildesk_mail_client_cockpit Basic, Pro, Automation Engine, Odoo resource
CRM integration maildesk_mail_client_crm Basic, Pro, Odoo CRM
Documents integration maildesk_mail_client_documents Basic, Pro, Odoo Documents (Enterprise)
Helpdesk integration maildesk_mail_client_helpdesk Basic, Pro, Odoo Helpdesk (Enterprise)
Partner 360 maildesk_mail_client_partner360 Basic and Pro
Sales integration maildesk_mail_client_sale Basic, Pro, Odoo Sales

Other bridges (Accounting, Time Off, Project, Purchase, Stock) follow the same rule: Basic, Pro and the matching Odoo app. You do not need server_wide_modules for MailDesk. Odoo installs the dependency order itself.

Required Python packages

MailDesk Basic declares these packages in its manifest. Install them in the Python environment that runs Odoo:

pip install imapclient google-api-python-client google-auth google-auth-httplib2 msal

The MailDesk Basic module folder contains a requirements.txt with pinned versions. On a server you can use pip install -r with that file. On Odoo.sh, put the packages in the repository's root requirements.txt instead (see Install on Odoo.sh).

Optional Python packages for AI (MailDesk Pro)

MailDesk Pro has its own requirements.txt for the AI provider libraries. They are not declared in the manifest, so Odoo does not warn you if they are missing. Install only the ones you use:

If you use... Package
OpenAI, xAI Grok, DeepSeek, or a custom or local server (Ollama, LM Studio, vLLM) openai>=1.55.3,<2
Google Gemini google-genai==1.0.0
Anthropic Claude anthropic>=0.40

The Pro file also limits google-auth to a version below 2.48.0. If you install both Basic and Pro packages, let pip resolve them together. The Documents bridge also needs pdfminer.six.

If you configure no AI provider, none of these packages are needed. See What MailDesk AI can access.

Public HTTPS address

To connect Gmail or Microsoft 365 with OAuth, your Odoo server must be reachable over HTTPS at a public address, and Odoo's web.base.url must use it. Google and Microsoft reject OAuth redirects to plain http://. Plain IMAP/SMTP mailboxes do not need this. Gmail push notifications use the public address /maildesk/push/gmail. Do not disable the MailDesk sync scheduled actions. Setup guides: Gmail, Microsoft 365.

Database

PostgreSQL 13 or newer is recommended, and 15 or newer for larger deployments.