MailDesk docs
Get MailDesk
Basic

Mailbox account setup (administrator)

A mailbox account is the MailDesk record that ties one email address to its incoming and outgoing mail servers and decides which Odoo users may see and use it. This page is for the Odoo administrator who creates and shares those accounts. It also covers how an ordinary user joins a shared mailbox without seeing any server settings.

8 min read Basic

A mailbox account is the MailDesk record that ties one email address to its incoming and outgoing mail servers and decides which Odoo users may see and use it. This page is for the Odoo administrator who creates and shares those accounts. It also covers how an ordinary user joins a shared mailbox without seeing any server settings.

Available in: Basic. Mailbox accounts, shared mailboxes, and the access list are part of the MailDesk engine, so they behave the same whether or not Pro is installed. A few extra fields (AI options, the Remove Mailbox action) appear only when Pro is installed — these are called out below and marked Available in: Pro.

What it does

Each mailbox account gives MailDesk a friendly name, the email address, the sender name shown to recipients, an optional signature, and a link to the two servers that move mail in and out:

  • an Incoming Mail Server (where mail is fetched from), and
  • an Outgoing SMTP Server (where mail is sent from).

Mailbox Accounts list showing each account's name, email address, owner, and active toggle

The provider — Gmail, Outlook/Microsoft 365, or generic IMAP — is decided by the Server Type of the incoming server you attach, not by a setting on the mailbox account itself. The incoming and outgoing servers are configured separately; see IMAP / SMTP setup for the password-based path and Gmail OAuth setup for the sign-in path.

Why it matters

  • One inbox, many mailboxes. A single Odoo user can hold several mailbox accounts (their own plus shared team mailboxes) and switch between them inside MailDesk.
  • Controlled access. You decide, per mailbox, exactly which users may open it. A user only ever sees the mailboxes you grant them — this is enforced on the server, not just hidden in the interface.
  • Shared team mailboxes. A support@ or info@ address can be opened by a whole team without sharing one login.

Requirements

  • MailDesk Basic installed; works on Odoo 17, 18, or 19 — the steps below are the same on each.
  • An incoming mail server and an outgoing mail server already configured (or configure them while creating the account — see IMAP / SMTP setup).
  • For Gmail or Outlook over OAuth, the company-wide OAuth credentials configured first (see Gmail OAuth setup).

Permissions required

Task Who can do it
Create / edit / delete a mailbox account MailDesk Mailbox Admin
Choose which users may access a mailbox MailDesk Mailbox Admin
Open and use a mailbox you have been granted MailDesk Mailbox User
Join a shared mailbox yourself (with its share password) MailDesk Mailbox User

Users cannot create mailbox accounts

A Mailbox User can only read and use accounts on which they appear in Users with Access; they cannot create or delete accounts. Account creation is an administrator task.

Create a mailbox account (administrator)

  1. Open the MailDesk app.

  2. Go to Configuration → Mailboxes → Mailbox Accounts and click New.

  3. Fill in the top section: - Account Name — a friendly label shown inside Odoo (for example Support, Sales, John Doe). - Email Address — the full address used for login and sending (for example [email protected]). It must contain an @. - Sender Name (optional) — the name recipients see on outgoing mail. If left empty, only the email address is shown.

  4. Attach the two servers in the right-hand group: - Incoming Mail Server — the record that fetches mail (IMAP, Gmail OAuth, or Outlook OAuth). Only servers belonging to the same company can be selected. - Outgoing SMTP Server — the record used to send mail.

  5. Click Save.

  6. Use the header buttons to verify the connection: - Test Incoming Server — checks that incoming mail can be reached and logs in. - Test Outgoing Server — checks that the outgoing server accepts a connection. - Fetch folders — discovers the folders on the server and lists them on the Folders tab.

Expected result: both tests show Connection Test Successful!, and after Fetch folders the Inbox and other folders appear on the Folders tab. MailDesk then starts filling the mailbox automatically.

Mailbox account form with the two server fields and the header test buttons

Gmail and Outlook over OAuth

If the incoming server's Server Type is Gmail OAuth Authentication or Outlook OAuth Authentication, you connect with a provider sign-in instead of a stored password. For Outlook, a Connect Microsoft Graph (OAuth) button appears in the form header; for the full Gmail and Outlook walkthroughs see Gmail OAuth setup and the Outlook setup guide.

Choose who can access a mailbox

Access is controlled by the Users with Access list on the mailbox account. A user can open a mailbox in MailDesk only if they are on this list.

  1. Open the mailbox account.
  2. In the Users with Access field, add each Odoo user who should be able to open this mailbox.
  3. Save.

Expected result: the listed users now see this mailbox when they open MailDesk; everyone else does not.

Removing a user from the list removes their access immediately

Access is checked on every read. Removing a user from Users with Access stops them from opening the mailbox right away, including its messages and folders.

Shared mailboxes

A shared mailbox (for example support@) is one mailbox account that several users open. There are two ways to populate its Users with Access list.

Option A — the administrator adds the users

Simply add each team member to Users with Access (above). Nothing else is required.

Option B — let users connect themselves with a share password

You can let users add themselves to a shared mailbox by entering its email address and a shared password, instead of you adding them one by one.

  1. Open the mailbox account.
  2. Turn on Allow Personal Connection.
  3. A Share Password field appears. Enter the password you will give to the team.
  4. Save and hand the email address and share password to the team.

Expected result: the mailbox is now self-service. Any user with the email address and share password can join it from the Connect Mailbox menu (below).

Connect to a shared mailbox (any user)

A user who has been given a shared mailbox's address and share password can join it themselves — no administrator action and no server settings needed.

  1. Open the MailDesk app.
  2. Click Connect Mailbox in the MailDesk menu.
  3. In the Connect to Mailbox dialog, enter: - Email Address — the shared mailbox address. - Password — the share password.
  4. Click Connect.

Expected result: MailDesk reloads and the shared mailbox now appears for that user.

Troubleshooting the connect dialog

Message Meaning What to do
No shared mailbox found with this email. No active mailbox with that address has Allow Personal Connection turned on Check the address; ask the administrator to enable Allow Personal Connection
You already have access to this mailbox. You are already on the access list No action needed — the mailbox is already available to you
Incorrect password. The share password does not match Re-enter the share password provided by the mailbox owner

Mailbox account settings

Open a mailbox account and use the tabs and the Settings tab to fine-tune behaviour.

Setting Where What it does
Append Sent to IMAP Settings → Sent Settings Manually copies sent messages into the server's Sent folder. Turn off if your server already saves sent mail itself (typical for Gmail/Outlook). On by default.
Convert attachments to links for emails over … MB Settings → Sent Settings Large attachments on outgoing mail are turned into links above this size.
Keep Attachments Settings → Email Settings When on, attachments are downloaded and stored in Odoo; when off, they stay on the mail server and are fetched when an email is opened.
Block Tracking URLs Settings → Email Settings Attempts to strip known tracking pixels and links from incoming mail.
Signature Signature tab HTML signature added to every email sent from this account.

Reset a mailbox if its view gets out of step

On the Maintenance tab (administrators only), Reset Mailbox Sync State clears the cached view of a mailbox and lets it rebuild automatically. No provider settings or sign-in tokens are touched, and emails already linked to Odoo records are preserved. Mail is briefly unavailable while the rebuild runs.

Extra settings with Pro

Available in: Pro. When MailDesk Pro is installed, the mailbox account form also offers:

  • Enable AI features (per mailbox) and an AI Settings tab with a Default Reply Tone and a Team / Mailbox Context field. See What MailDesk AI can and cannot access.
  • A Manage Signatures button for per-user and shared signatures.
  • A Remove Mailbox action in the form header that safely retires a mailbox while keeping any emails already linked to Odoo records.

Troubleshooting

Symptom Likely cause Fix
Test Incoming Server fails Wrong host/port/credentials, or the server type is not set Re-check the incoming server — see IMAP / SMTP setup; for Gmail/Outlook use the OAuth sign-in
Incoming server company must match the mailbox account company. The attached server belongs to a different company Use a server from the same company, or change the account's company
Incoming mail server … is already linked to another mailbox account. One incoming/outgoing server cannot be shared between two mailbox accounts Create a separate server record for each mailbox
No folders after saving Folders not fetched yet Click Fetch folders in the form header
A user cannot see a mailbox you set up They are not on Users with Access Add them to the list (or have them self-connect to a shared mailbox)
This mailbox has N email(s) linked to Odoo records… when deleting Deleting would destroy linked business history Use Remove Mailbox (Pro) to keep the linked emails as an archive, or confirm a full delete there