MailDesk docs
Get MailDesk
All editions

Installing MailDesk

This page is for the Odoo administrator who installs MailDesk for the first time. It covers what to install, in which order, the prerequisites your Odoo server needs, the optional extras for AI, and the two common hosting situations (Odoo.sh and self-hosted).

5 min read All editions

This page is for the Odoo administrator who installs MailDesk for the first time. It covers what to install, in which order, the prerequisites your Odoo server needs, the optional extras for AI, and the two common hosting situations (Odoo.sh and self-hosted).

Available in: all of MailDesk. MailDesk Basic (maildesk_mail_client) is the engine; MailDesk Pro (maildesk_mail_client_pro) and the integration modules build on top of it. The licensing edition you bought (Basic, Pro, Business, Ultimate) decides which of these modules you are entitled to install — see Licensing & editions.

MailDesk runs on Odoo 17, 18, or 19

Choose the MailDesk package that matches your Odoo version. The same feature set works on each; the steps below are the same on all three.

What you install

MailDesk is a family of Odoo modules, not a single app. You install the ones your edition includes:

Module Technical name Requires
MailDesk Basic maildesk_mail_client A standard Odoo install (engine, no other MailDesk module)
MailDesk Pro maildesk_mail_client_pro Basic
Automation Engine maildesk_mail_client_automation Pro
Calendar integration maildesk_mail_client_calendar Pro (and Odoo Calendar)
Chatter integration maildesk_mail_client_chatter Pro
Cockpit maildesk_mail_client_cockpit Pro and the Automation Engine
CRM integration maildesk_mail_client_crm Pro (and Odoo CRM)
Documents integration maildesk_mail_client_documents Pro (and Odoo Documents)
Helpdesk integration maildesk_mail_client_helpdesk Pro (and Odoo Helpdesk)
Partner 360 maildesk_mail_client_partner360 Pro
Sales integration maildesk_mail_client_sale Pro (and Odoo Sales)

Install order

Odoo resolves and installs prerequisites automatically, so in practice you only pick the modules you want and Odoo pulls in the rest. The logical order is always:

  1. MailDesk Basic first — the engine. Nothing else can install without it.
  2. MailDesk Pro next — it installs on top of Basic and unlocks two-way sync, AI, the mobile-adaptive interface, and the dark theme.
  3. Integration modules last — each one requires Pro. Install only the ones you need.

The Cockpit module needs the Automation Engine

If you install Cockpit, Odoo also installs the Automation Engine module, because Cockpit builds on it. You do not have to install them in a particular order — Odoo handles the dependency for you.

You cannot end up half-installed

Odoo enforces these dependencies at install time. You cannot install Pro without Basic, and you cannot install an integration module without Pro. If a module is missing a prerequisite, Odoo offers to install the prerequisite first.

How to install (the Apps menu)

  1. In Odoo, open Apps.
  2. Update the apps list if you have just added the MailDesk files to your server (Apps → Update Apps List, available with developer mode on).
  3. Search for MailDesk.
  4. Open MailDesk Basic and click Activate (Install). Then do the same for MailDesk Pro and any integration modules your edition includes.

After installation, a MailDesk menu appears in the top bar, and a Configuration section becomes available to administrators for connecting mailboxes.

Prerequisites

Odoo and the database

  • A working Odoo 17, 18, or 19 installation, with administrator access including the technical settings.
  • PostgreSQL 13 or newer is recommended; PostgreSQL 15+ for larger deployments.
  • A valid MailDesk subscription or one-time licence for your edition and Odoo version. Licence activation is described in Licensing & editions.

A public HTTPS address (for Gmail and Outlook)

If you will connect Gmail or Microsoft 365 / Outlook mailboxes with OAuth sign-in, your Odoo server must be reachable over HTTPS at a stable public address, and Odoo's web.base.url must point to it. Google and Microsoft reject OAuth redirects to plain http://. This is not required for plain IMAP/SMTP mailboxes. See Gmail OAuth setup and Outlook / Microsoft 365 OAuth setup.

Python libraries (installed once, on the server)

MailDesk Basic uses a small set of Python libraries to talk to mail servers and the Gmail and Microsoft APIs. Install them on the server, as the system user that runs Odoo:

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

On Odoo.sh these belong in your repository's requirements.txt; on a self-hosted server, install them into the same Python environment Odoo runs in (see the hosting notes below).

Optional Python libraries (only if you use AI)

The AI features in MailDesk Pro are optional and only call out to an AI provider you configure. Each provider family needs its own Python SDK on the server, and only the one(s) you actually use:

If you use… Install on the server
OpenAI, xAI Grok, DeepSeek, or a custom / local server (Ollama, LM Studio, vLLM) pip install "openai>=1.0.0"
Google Gemini pip install "google-genai>=1.0.0"
Anthropic Claude pip install "anthropic>=0.20.0"

If you do not configure any provider, MailDesk falls back to Odoo's built-in AI service, and none of these extra libraries are needed. AI can also be left switched off entirely. See What MailDesk AI can and cannot access.

No AI libraries are required just to install MailDesk

MailDesk Basic and Pro install and run without any AI SDK. You add an AI library only when you decide to connect a specific AI provider.

Hosting notes

Odoo.sh

  1. Add the MailDesk module folders to your Odoo.sh Git repository (in your addons path).
  2. Add the core Python libraries — and any optional AI library you intend to use — to your repository's requirements.txt so the build installs them.
  3. Push to the branch for your environment. Odoo.sh creates a build; once it is green, install the modules from Apps on that environment.

Self-hosted

  1. Place the MailDesk module folders in a directory that is on your Odoo addons_path (in odoo.conf).
  2. Install the core Python libraries (and any optional AI library) into the same Python environment Odoo uses, as the user that runs the Odoo service.
  3. Restart Odoo, then Apps → Update Apps List, search MailDesk, and install Basic, Pro, and your integration modules.

Always test an upgrade before production

Whether on Odoo.sh or self-hosted, take a full database backup and test any MailDesk install or upgrade on a staging or development environment first. Never upgrade a production system without testing it elsewhere first, and check whether a new MailDesk version changes its Python dependencies.

Prefer not to do this yourself?

Metzler IT offers professional installation, upgrade execution, and initial configuration and validation on request. These services are not included with the licence; contact us for a personalised offer.

After installation

Installing the modules does not connect any mailbox by itself. Next:

  1. Configure your OAuth credentials (once per company) if you use Gmail or Outlook — Gmail OAuth setup or Outlook / Microsoft 365 OAuth setup.
  2. Connect the first mailbox — Mailbox setup.
  3. Decide who may use MailDesk and who may see which mailbox — Users & permissions.
  4. Activate your licence if you have not already — Licensing & editions.