AI troubleshooting
integration (manager briefings). MailDesk Basic has no AI, so nothing on this page applies to a Basic-only install.
integration (manager briefings). MailDesk Basic has no AI, so nothing on this page applies to a Basic-only install.*
This page collects the things that can go wrong with MailDesk AI and how to fix them. Most problems fall into one of five buckets: no provider / missing key, the Pro module is not present, a usage limit was reached, a wrong or unreachable address for a self-hosted server, or a feature or mailbox has AI switched off. Work down the matrix; the fixes are short.
Before you start
- Setting up and testing AI providers, and switching AI on or off, is an administrator task. Individual users never enter their own keys.
- If the AI actions are missing entirely on a Basic-only install, that is expected — AI ships with Pro.
The AI troubleshooting matrix
| Symptom | Likely cause | What to do |
|---|---|---|
| No security badge on emails; Summarise / Ask AI absent | No AI provider configured, or none active | Add and activate a provider: Settings → MailDesk → AI Providers, then Set API Key → Test Connection → Set as Active |
| "API key invalid" / authentication error | Wrong, expired, or mistyped key | Re-paste the key freshly from the provider portal (no leading/trailing spaces) on the provider record |
| Test connection fails for a cloud provider | Your Odoo server cannot reach the provider | Check the server's outbound internet access — a corporate firewall or proxy may be blocking it |
| Test connection fails for OpenAI specifically | The account has no billing set up | Enable billing in the provider portal; free trials are limited |
| "Quota exhausted" from the provider | The provider's own rate or billing limit | Switch model, or raise your plan with the provider |
| Local / self-hosted server "connection failed" | Server not running, or wrong address | Start the server; the base URL must be reachable from the Odoo server (not just your laptop) and, for an OpenAI-compatible endpoint, end in /v1 |
| Local server reachable from your laptop but not from MailDesk | The URL points at localhost or a private address the Odoo server cannot see |
Use an address the Odoo server can reach; confirm with a request from the server itself |
| AI options greyed out for one mailbox | Enable AI features is off for that mailbox | Switch it on: MailDesk → Configuration → Mailbox Accounts → [account] → Enable AI features |
| One feature (e.g. summarise) unavailable, others work | That feature was switched off | An administrator can re-enable it by setting the System Parameter maildesk.ai.feature.<feature>.enabled back to 1 |
| No AI anywhere, all mailboxes | AI is switched off globally | An administrator can re-enable AI by setting the System Parameter maildesk.ai.enabled back to 1 |
| Attachment analysis never runs | Attachments are opt-in and must be requested explicitly | Have an administrator opt the mailbox in to AI attachment analysis, then ask the AI about the attachment on that message |
How AI access is decided (four layers)
AI only runs when all four of these allow it. They are checked on the server every time — not just hidden in the interface. If AI is unexpectedly unavailable, one of these is the reason:
- Global switch — an administrator can disable all AI at once via the System Parameter
maildesk.ai.enabled(default on; set to0to disable). - Per-feature switch — individual features (summarise, reply draft, security check, and so on) can be
turned off one at a time via the System Parameter
maildesk.ai.feature.<feature>.enabled(default on per feature). - Per-mailbox switch — "Enable AI features" — off for a mailbox means no AI for that mailbox, period. This is the toggle on the mailbox account form, and it is enforced on the server.
- A working provider — a configured provider with a valid key, or a reachable self-hosted server.
You only ever see AI for mailboxes you can access
There is no special AI permission group. AI follows your existing mailbox access plus the switches above (and, in the Cockpit, the per-tier limits). Standard Odoo access rules still apply.
Self-hosted (custom) provider checklist
If you keep all AI processing on your own infrastructure with the Custom provider, and the test fails, check each of these:
- The endpoint URL is an OpenAI-compatible API and ends in
/v1(for example a local Ollama or LM Studio server). - The model name you entered is one your endpoint actually serves.
- Any authentication key your endpoint requires is set.
- The endpoint is reachable from the Odoo server, not only from your own machine.
When a self-hosted provider is used, email content never leaves your network.
Cockpit manager briefings
If the Cockpit's manager briefings misbehave, the cause is usually tier, quota, or a missing Pro provider:
| Symptom | Likely cause | What to do |
|---|---|---|
| Generate daily briefing is missing | Below the Cockpit Manager tier, or no provider ready | Get the Cockpit Manager tier; confirm a Pro AI provider is active |
| "Configure the MailDesk AI provider … to enable daily briefings" | No working Pro provider | Set up and test a provider (above) |
| "Daily AI quota reached for …" | The per-day limit for that operation is used up | Try again tomorrow, or ask an administrator (administrators have no limit) |
| "Operation … is restricted to Cockpit Manager or higher" | An Operator triggered a manager-only briefing | Run manager tools as a Manager |
| "MailDesk Pro is not installed …" | The Pro module is missing | Install MailDesk Pro — Cockpit AI reuses Pro's provider |
See Cockpit AI briefings for managers for the full quota table and tier model.
Privacy reminder
AI is given only the email or thread you are working on — never your whole inbox, never other people's mail, never your Odoo business records. Binary attachments are sent only when a mailbox is opted in and you explicitly ask. For the full data-handling detail see What MailDesk AI can and cannot access.