IMAP / SMTP server setup (administrator)

This page explains how to set up the incoming (IMAP) and outgoing (SMTP) mail servers that a MailDesk mailbox account points to, using a username and password. It is the right path for any mailserver that speaks standard IMAP and SMTP — your own mailserver, Mailcow, FastMail, ProtonMail Bridge, and similar — and for Gmail or Outlook when you cannot use OAuth and connect with an app password instead.

This page explains how to set up the incoming (IMAP) and outgoing (SMTP) mail servers that a MailDesk mailbox account points to, using a username and password. It is the right path for any mailserver that speaks standard IMAP and SMTP — your own mailserver, Mailcow, FastMail, ProtonMail Bridge, and similar — and for Gmail or Outlook when you cannot use OAuth and connect with an app password instead.

Available in: Basic. The incoming and outgoing servers are standard Odoo mail server records that the MailDesk engine drives, so this works the same with or without Pro.

How the pieces fit together

A working mailbox needs three records, and MailDesk links them:

flowchart LR
    A[Mailbox Account] -->|Incoming Mail Server| B[Incoming server<br/>IMAP — fetchmail.server]
    A -->|Outgoing SMTP Server| C[Outgoing server<br/>SMTP — ir.mail_server]

• The incoming server holds the IMAP host, port, encryption, username and password, and its Server Type decides how MailDesk authenticates (IMAP password, Gmail OAuth, or Outlook OAuth).
• The outgoing server holds the SMTP host, port, encryption, username and password.
• The mailbox account points to both. See Mailbox account setup for that record.

Requirements

• MailDesk Basic installed; works on Odoo 17, 18, or 19 — the steps below are the same on each.
• IMAP access enabled on the mailbox at your provider.
• The incoming (IMAP) host and port, and the outgoing (SMTP) host and port.
• The mailbox login and password — or an app password if the provider requires one.
• Your Odoo server allowed to make outbound connections to those hosts and ports.

Permissions required

• Configuring mail servers and mailbox accounts is a MailDesk Mailbox Admin task.
• The server menus live under MailDesk → Configuration → Mailboxes and are visible to administrators only.

Common provider settings

Use these as a starting point; always confirm against your provider's own documentation.

Step 1 — Create the incoming (IMAP) server

1. Open the MailDesk app.

2. Go to Configuration → Mailboxes → Incoming Mail Servers and click New.

3. Fill in the form (titled Incoming Mail Server): - Name — a label for this server (for example Support IMAP). - Server Type — choose IMAP Server for a standard mailbox. (The list also offers Gmail OAuth Authentication and Outlook OAuth Authentication for the sign-in path.) - Under Server Information: Server Name (the IMAP host, for example imap.example.com), Port, and SSL/TLS (turn on for an encrypted connection). - Under Login Information: Username (usually the full email address) and Password (the mailbox password or an app password).

4. Click Test & Confirm to verify the connection and credentials.

Expected result: the server status changes from Not Confirmed to Confirmed, meaning the IMAP login succeeded.

Step 2 — Create the outgoing (SMTP) server

1. In the MailDesk app, go to Configuration → Mailboxes → Outgoing Mail Servers and click New.

2. Fill in the form (titled Outgoing Mail Servers): - Name — a label for this server. - Connection Encryption — choose SSL/TLS or TLS (STARTTLS) to match your provider. - SMTP Server — the SMTP host (for example smtp.example.com). - SMTP Port — for example 465 (SSL/TLS) or 587 (STARTTLS). - Username and Password — the SMTP login (often the same as the IMAP credentials).

3. Click Test Connection to verify the server accepts the connection.

Expected result: a success notification confirms the SMTP server is reachable and the credentials work.

Step 3 — Attach the servers to a mailbox account

1. Open or create the mailbox account (see Mailbox account setup).
2. Set Incoming Mail Server to the IMAP server from Step 1 and Outgoing SMTP Server to the SMTP server from Step 2.
3. Save, then use Test Incoming Server and Test Outgoing Server in the form header, and finally Fetch folders.

Expected result: both tests show Connection Test Successful!, the folders appear on the Folders tab, and MailDesk begins filling the mailbox.

Gmail over IMAP (App Password)

Use this only when you cannot use the Gmail OAuth sign-in path.

1. In your Google Account, turn on 2-Step Verification.
2. Create a Google App Password for Mail and copy the 16-character code.
3. Create the incoming server with Server Name imap.gmail.com, Port 993, SSL/TLS on, Username = your full Gmail address, Password = the app password.
4. Create the outgoing server with SMTP Server smtp.gmail.com, SMTP Port 465 or 587, the matching encryption, and the same username and app password.

How the mailbox stays in sync

Once a server is attached and confirmed, MailDesk fetches mail with automatic background jobs — there is nothing to schedule by hand. New mail surfaces within the relevant polling interval, and the open MailDesk view refreshes itself as messages arrive. For the full picture (including the near-realtime push options), see Realtime & synchronization architecture.

Troubleshooting

Related

• Mailbox account setup — the account that points to these servers, plus shared mailboxes and access control.
• Gmail OAuth setup — connect Gmail/Google Workspace by sign-in instead of a password.
• Realtime & synchronization architecture — how new mail is fetched and the view kept fresh.