Mail. Connecting a mailbox to a mail client

A mailbox created with BeAdmin can be connected to any mail client that works over IMAP and SMTP: Thunderbird, Apple Mail, Outlook, Gmail on Android, and others. This article is the part common to all clients: it covers where to find the password and the connection settings, which values to enter, and what to do if the client warns you about the certificate. The steps in specific clients are in separate articles, listed in the Mail client guides section. Creating a mailbox and changing its password are covered in Mail. Mailboxes, aliases, and domains.

If you only need to read mail in the browser, you do not need a client: sign in to Roundcube as described in How to deploy a mail server with BeAdmin.

How the connection works

A mail client connects to the server at the mail server address you set when installing the module. It receives incoming mail over IMAP, sends outgoing mail over SMTP, and signs in with the mailbox login and password; the login is the full mailbox address. The connection is protected by a certificate issued for the mail server address specifically, so enter that address in the client rather than the primary domain or the server's IP address: otherwise the client will warn you about the certificate.

Each mailbox has its own password, which is different from your panel password. The server generates it when the mailbox is created, and you can change it later.

Where to find the settings

The server generates the password of a new mailbox and shows it only once, when you create the mailbox, in the "Mailbox created" dialog: the panel cannot read the password back. Save it right away: "Copy all" copies the password together with the login, server, and ports, and you can paste them into a password manager or a note. The password cannot be shown again, only changed. The old password stops working immediately, so you need to enter the new one in every mail client and on every device where the mailbox is already connected.

You can open the connection settings without the password in the panel at any time: expand the mailbox you need.

If no mail server address was set when the module was installed, the connection settings show "Not set" instead of the server, and the server's certificate is self-signed. For what to do about it, see The server has a self-signed certificate.

Server settings

You will need the values from the table to set up the client. In the table and below, mail.example.com and info@example.com are examples: use the address of your own mail server and your own mailbox address.

Setting	Incoming mail (IMAP)	Outgoing mail (SMTP)
Server	mail.example.com	mail.example.com
Port and encryption	993, SSL/TLS	465, SSL/TLS
Alternative	143, STARTTLS	587, STARTTLS
Username (login)	info@example.com	info@example.com
Password	mailbox password	mailbox password
Authentication	normal password	normal password

• Server — the mail server address you entered when installing the module. It is the same for incoming and outgoing mail. Enter exactly that address, not the primary domain or the server's IP address.
• Ports 993 and 465 are the main option: the connection is encrypted right away. Ports 143 and 587 are the alternative with STARTTLS, where encryption is switched on after the connection starts. Use it if your client or network does not work with the main option.
• Username — the full mailbox address. An alias cannot be used to sign in: it only forwards messages.
• Outgoing mail requires authentication: turn it on for the outgoing mail server and use the same username and password as for incoming mail. The server accepts a normal password only over an encrypted connection, so signing in without encryption does not work. The "Encrypted password", NTLM, Kerberos, and OAuth2 methods do not work.
• The mailbox is also available over POP3: the same server, port 995 (SSL/TLS) or 110 (STARTTLS). The guides use IMAP throughout: it keeps messages on the server, so the mailbox looks the same in every client and on every device.

Mail client guides

• Thunderbird — Windows, macOS, and Linux.
• Apple Mail — the Mail app on Mac and iPhone.
• Outlook — new and classic Outlook for Windows, Outlook for Mac.
• Gmail on Android — the Gmail app on an Android phone.

If your client is not on the list, choose manual IMAP account setup in it and enter the values from the table.

If the mail client warns about the certificate

A mail client warns about the certificate when it cannot make sure it has connected to your server. Usually this means the client has the wrong address or the server has a self-signed certificate.

The client has the wrong server address

The certificate is issued for the mail server address you set when installing the module. If the client has the primary domain (example.com), an IP address, or another name, the warning appears even on a healthy server. Usually it says that the name in the certificate does not match the server address. Enter the mail server address in the client, for example mail.example.com.

The server has a self-signed certificate

The panel requests a Let's Encrypt certificate for the mail server address. If it could not be issued, the server runs with a self-signed certificate, and the client reports that it cannot be trusted. This happens if no address was set during installation, or if the A record for the mail server address did not yet point to the server at the time of installation. To fix it, you need to:

1. Create an A record for the mail server address at your registrar and wait for it to update: Let's Encrypt issues a certificate only for an address that points to your server. For how to do it, see the A record section of the DNS article.
2. Reinstall the module and set the mail server address. The panel requests the certificate from Let's Encrypt again, and the clients stop warning. Domains, mailboxes, and aliases are kept when you reinstall.

⚠️ Do not add a certificate exception

Mail clients offer to add an exception, continue connecting, or accept any certificate. Do not agree: your password and messages would go to a server whose identity the client has not verified. Fix the cause of the warning as described above.

If the mail client does not connect

Check the following in order:

• The username field contains the full mailbox address — not the part before the @ and not an alias.
• The password is the mailbox password, not your panel password. If you forgot it, change the mailbox password and enter the new one in the client.
• The mailbox is enabled: you cannot sign in to a disabled mailbox.
• SSL/TLS encryption is selected for ports 993 and 465, STARTTLS for 143 and 587. The server does not accept the option without encryption.
• The mail server is running. To check, see the Managing the service section.
• Ports 993 and 465 are not blocked by a firewall on the server or at your hosting provider.

What's next

• Mail. Mailboxes, aliases, and domains — creating a mailbox, changing its password, aliases and catch-all, connecting a domain to mail.
• How to deploy a mail server with BeAdmin — installing the module and the Roundcube web client.
• Mail. Managing the module — starting the service and reinstalling the module.
• How to configure DNS records for a mail server — the A record for the mail server address, MX, SPF, DKIM, and DMARC.