Install MailDesk: choose your setup
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.
- Log in to Odoo as an administrator and turn on developer mode.
- Open Apps.
- Click Update Apps List and confirm.
- Remove the Apps filter in the search box, then search for MailDesk.
- On MailDesk Basic, click Install.
- 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.