MailDesk docs
Get MailDesk
Pro

Set up your AI provider

This is the one-time setup that switches on MailDesk's AI assistant. Once a provider is configured and active, everyone who uses a mailbox can run Security Scan, Summarise, Draft a reply, and the thread-aware Ask AI dialog on their email — with no further setup.

8 min read Pro

Available in: Pro. (The Cockpit integration reuses the same provider for manager briefings.) Basic has no AI.

This is the one-time setup that switches on MailDesk's AI assistant. Once a provider is configured and active, everyone who uses a mailbox can run Security Scan, Summarise, Draft a reply, and the thread-aware Ask AI dialog on their email — with no further setup.

What it does

You connect MailDesk to an AI provider of your choice — a major cloud service (OpenAI, Google Gemini, Anthropic Claude, xAI Grok, DeepSeek) or a local/self-hosted server running on your own hardware. You enter the provider's API key once, test the connection, and mark the provider active. From then on MailDesk routes every AI request to that provider.

Why it matters

  • You choose where AI runs. Pick a cloud provider, or keep everything on your own network with a local server — your call, per deployment.
  • Keys stay protected. API keys are stored in Odoo's system parameters, not in any exportable field, and are never shown again after you save them.
  • One setup, whole team. Administrators configure the provider once; users never enter keys.
  • Route by task if you want. Use a fast, cheap model for high-volume summaries and a stronger model for drafting replies — without changing the default for everything else.

Requirements

  • MailDesk Pro installed and licensed.
  • Administrator access to Odoo, including the technical settings.
  • One of the following:
    • An account and API key with a supported cloud provider (OpenAI, Google Gemini, Anthropic Claude, xAI Grok, or DeepSeek), or
    • A reachable OpenAI-compatible local server (for example Ollama, LM Studio, or vLLM).
  • Your Odoo server must be able to reach the provider over the network. A cloud provider needs outbound internet access; a local server must be reachable from the Odoo server, not just from your laptop.
  • The matching Python SDK installed on the Odoo server (see Install the provider SDK below).
  • MailDesk works on Odoo 17, 18, or 19 — the steps below are the same on each.

No provider configured? The security check and Ask AI still work

If no provider is active, the Security Scan and the editor's Ask AI fall back to Odoo's built-in AI service, so those keep working on existing installations. Summarise and Draft a reply do not fall back — they need a configured provider. Configuring your own provider above turns on every AI feature and gives you control over which model is used and where your data goes.

Permissions required

Setting up AI providers is an administrator task. Individual users never enter their own keys. Once a provider is active, each user only sees AI results for mailboxes they already have access to — standard Odoo access rules still apply, and there is no special elevation.

Install the provider SDK

Each provider talks through a small Python package on your Odoo server. These packages are optional — install only the one for the provider you intend to use. MailDesk loads the package the first time AI is used and, if it is missing, shows a clear message telling you exactly which package to install.

Provider Install command
OpenAI (ChatGPT) pip install "openai>=1.0.0"
Google Gemini pip install "google-genai>=1.0.0"
Anthropic Claude pip install "anthropic>=0.20.0"
xAI Grok pip install "openai>=1.0.0"
DeepSeek pip install "openai>=1.0.0"
Custom / Local Server pip install "openai>=1.0.0"

Install on the right machine

Install the package into the same Python environment Odoo runs in, then restart the Odoo service. On Odoo.sh or a managed host, add the package to your project's requirements so it survives a rebuild.

Step 1 — Open the AI Providers configuration

  1. In Odoo, open MailDesk → Configuration → MailDesk Settings → AI Providers and create a new provider record.

The MailDesk AI Providers list in Settings

Step 2 — Choose the provider and a model

  1. Give the record a clear name (for example GPT-4o Production).
  2. Choose the provider from the list: OpenAI (ChatGPT), Google Gemini, Anthropic Claude, xAI Grok, DeepSeek, or Custom / Local Server.
  3. Optionally set a model identifier. Leave it empty to use MailDesk's sensible default for that provider.

An AI provider record form with the provider, model, and Base URL fields, an API-key status of API Key Configured, a Not Tested connection status, and the Set API Key and Test Connection buttons

The built-in defaults are:

Provider Default model Other common choices
OpenAI (ChatGPT) gpt-4o gpt-4o-mini, gpt-4.1, gpt-4.1-mini
Google Gemini gemini-2.5-flash gemini-2.5-pro
Anthropic Claude claude-sonnet-4-6 claude-opus-4-7, claude-haiku-4-5-20251001
xAI Grok grok-4.20-0309-non-reasoning grok-4.20-0309-reasoning
DeepSeek deepseek-chat deepseek-reasoner
Custom / Local Server (set the model your server expects) —

Faster, cheaper models for high-volume inboxes

For mailboxes that process a lot of mail, a lighter model (for example gemini-2.5-flash, gpt-4o-mini, or deepseek-chat) keeps cost and latency down. Use a stronger model where the quality of a reply matters more than speed.

Step 3 — Enter your API key

  1. On the provider record, click Set API Key.
  2. Paste your provider key into the wizard.
  3. Save.

The key cannot be read back

Once saved, the key is masked and cannot be retrieved from MailDesk. Keep a copy in your password manager or your provider's portal. The key is stored in Odoo's system parameters, not in any exportable field, and is never written to logs.

Step 4 — Set the provider active

  1. From the AI Providers list, open the provider you want to use and click Set as Active (or set Active Provider on the record).
  2. Only one provider is active at a time — activating one automatically deactivates the others.

Step 5 — Test the connection

  1. Click Test Connection on the provider record.
  2. MailDesk sends a short health-check call to the provider and reports the result. A green Connected status means it works.

Expected result

Open an email and a security badge appears after a moment; Summarise and Ask AI become available on threads. The AI assistant is now live for every mailbox that has AI switched on (see Per-mailbox settings below).

Use a local / self-hosted server

If all AI processing must stay on your own infrastructure (regulated industry, sensitive data, a strict compliance requirement), choose the Custom / Local Server provider. No email content leaves your network — see Privacy: what is sent to your AI provider.

  1. Create a provider record and choose Custom / Local Server.
  2. Set the Base URL of your OpenAI-compatible server. This is required for the custom provider. Examples:
    • Ollama — http://localhost:11434/v1
    • LM Studio — http://localhost:1234/v1
    • vLLM — http://localhost:8000/v1
  3. Set the model name exactly as your server exposes it (for example llama3.2).
  4. If your server requires an authentication key, set it via Set API Key; otherwise leave it empty.
  5. Set as Active, then Test Connection.

The base URL must end in /v1

MailDesk expects an OpenAI-compatible endpoint. The base URL must point at the API root that ends in /v1 (for example http://localhost:11434/v1), and the server must be reachable from the Odoo server, not just from your workstation.

Route specific tasks to different providers (optional)

By default every AI task uses the single active provider. You can override individual tasks — for example, use Gemini for summaries (generous free tier) and OpenAI for reply drafting (higher quality) — without changing the global default.

  1. Go to Settings → MailDesk and find the AI provider overrides.
  2. For each task, choose a provider, or leave it on — Use active provider —.
Task setting Controls
Security Scan Provider The phishing / impersonation check that runs when you open an email
Thread Summary Provider The Summarise action on a thread
Reply Draft Provider The Draft a reply action
Ask AI / Editor Provider The thread-aware Ask AI dialog and the editor's "Ask AI"

Per-mailbox settings

A provider being active does not force AI on every mailbox. AI is controlled per mailbox, and each mailbox carries its own AI preferences.

Open MailDesk → Configuration → Mailbox Accounts → [account]:

  • Allow AI Features — must be on for AI to run for that mailbox. On by default; switching it off disables all AI for that mailbox, no exceptions.
  • Allow AI Attachment Analysis — off by default. Even when on, attachment content is only sent on an explicit user action. See Privacy.
  • Team / Mailbox Context — optional free-text background (team, role, communication style) the AI uses for summaries and drafts.
  • Default Reply Tone — Professional (default), Formal, Friendly & Warm, Technical & Precise, or Concise (Short).

Turn AI off

You can disable AI at several levels — each is enforced on the server, not just hidden in the interface:

  • For one mailbox — switch Allow AI Features off on that mailbox account.
  • For one feature (Security Scan, Summarise, etc.) or everything at once — an administrator can disable it in MailDesk settings.
  • Remove a provider — open the provider record and delete it; the stored key is cleared with it.

Troubleshooting

Symptom Likely cause What to do
No security badge on emails No provider configured or active Add a provider, Set as Active, and Test Connection
Test Connection reports an error Wrong/expired key, no network path, or wrong model name Re-enter the key (fresh copy, no stray spaces); confirm the Odoo server can reach the provider; check the model name
"Package not installed" message The provider's Python SDK is missing Run the pip install command for that provider, then restart Odoo
"API key invalid" Wrong or expired key Re-enter the key via Set API Key
"Quota exhausted" Provider rate or billing limit reached Raise your provider plan or switch to a cheaper model
AI options greyed out for a mailbox Allow AI Features is off for that mailbox Switch it on for that mailbox account
Local server "connection failed" Server not running, or wrong/unreachable URL Start the server; the base URL must end in /v1 and be reachable from the Odoo server
Features work but feel slow Network latency or a large model Try a faster model (for example gemini-2.5-flash or gpt-4o-mini)

Available in MailDesk Pro 18.0.4.1.0+. Provider list, labels, and defaults verified against the Pro AI code.