Connecting a mail client: IMAP, POP3, SMTP submission, app passwords and the ports

Written for 6.3.4. hMailServer 6.3.7 (17 October 2026) accepts the UTF8 that classic Outlook for Windows (Outlook 2016 to 2024) sends after the POP3 login, at which its downloads had stopped; SMTP, POP3 and ManageSieve refuse a SASL PLAIN sign-in that asks to act as another account, and IMAP takes an authzid naming the client itself as none; IMAP's COPY and MOVE by message number read their set in the client's numbering and refuse one that names a message another session has just expunged (NO [EXPUNGEISSUED]), FETCH BODY[N.MIME] and BODY[N] of a multipart are the stored octets, and a refusal by the access control is NO [NOPERM]; and the IMAP and POP3 listeners can take the client's address from a PROXY protocol header, as the SMTP listener does, off by default. An authenticated submission is DKIM-signed as another hosted domain only when the account may send as the address its From names. See the 6.3.7 announcement. hMailServer 6.3.8 (2 November 2026) signs a client in only when its user name is the account's stored address, compared in lower case after a domain alias and the default domain. A user name that differs from it in more than the case of the letters A to Z, or has white space at either end, may no longer sign in: such a name fails as a name that does not exist fails, so correct the user name in the client. See the 6.3.8 announcement.

This topic covers connecting a mail client to hMailServer 6.3.4: ports, authentication, folders, automatic configuration, app passwords and devices. The one thing to know first: a new installation of 6.3.4 refuses a password from any machine but itself until the session is encrypted, and an upgraded server is not changed. On either, the TLS ports 465, 993 and 995 exist only once you create them.

The settings your users need

Setting	Value	Why, and what goes wrong
Incoming server (IMAP)	mail.yourcompany.com, port 993, SSL/TLS	Implicit TLS: the handshake comes before the greeting. On a port not configured as SSL/TLS the client hangs, then times out
Incoming server (POP3)	mail.yourcompany.com, port 995, SSL/TLS	The same. Only use POP3 if you have a reason to
Outgoing server (SMTP)	mail.yourcompany.com, port 587, STARTTLS	Port 25 is for other servers, not for your users; many ISPs block outbound 25 from residential lines
User name	The full email address, [email protected]	A bare name works only with Maintenance → Advanced → Default domain (for unqualified logons) set
Password	The account's password, or an app password if the account is enrolled in TOTP	See the app passwords section below
Encryption	Never "none", never "auto-detect"	"Auto-detect" is how a client ends up sending a password in the clear

The ports, and what 6.3.4 changes on a new installation

A new database is seeded with four rows - SMTP 25, SMTP 587, POP3 110 and IMAP 143 - and up to 6.3.3 all four were without encryption. Add 465, 993 and 995 yourself under Connections & protocols → TCP/IP ports in the Windows Control Panel, or on the Control Deck, once you have a certificate of your own.

Connection security	What the server does
None (0)	Plain text; STARTTLS is not advertised. Everything, including the password, is in the clear
SSL/TLS (1)	Handshake first, banner after. Correct for 465, 993 and 995
STARTTLS optional (2)	Advertises STARTTLS and accepts both. The right setting for port 25 only: on a submission port it lets a misconfigured client send its password in the clear
STARTTLS required (3)	Answers 530 5.7.0 Must issue STARTTLS first. to every command except NOOP, EHLO, STARTTLS and QUIT. Right for 587, and for 143 and 110 if you keep them; on port 25 it silently refuses mail from every server that cannot do TLS

With TLS chosen and no certificate selected the listener does not start at all: HM5113, Error initializing SSL. Certificate not set., in the application log, connection refused, nothing in the SMTP log; pick a certificate on the port. A port already in use is HM4316, and the rest of the server starts normally.

A new installation of 6.3.4 has all four seeded listeners at STARTTLS optional with a self-signed certificate, which a mail client warns about until it is replaced, and the Internet IP range requires TLS for authentication; My computer (127.0.0.1) is left as it was. So from another machine, until the client sends STARTTLS:

• SMTP AUTH is not offered, and is refused with 530 A SSL/TLS-connection is required for authentication. if it is sent;
• IMAP advertises LOGINDISABLED, and LOGIN and AUTHENTICATE answer BAD A SSL/TLS-connection is required for authentication.;
• POP3 USER and AUTH answer -ERR.

After STARTTLS every one of them works: the range's rule, not the port's, is what protects the password. When ACME's first certificate arrives it is given to every listener holding the self-signed one: see Let's Encrypt certificates are automatic.

An upgraded or attached database is never changed. On Linux the defaults are applied at the unit's first start only when it comes within a day of --create-database. Which databases get them, the verb that applies them by hand and the checklist item that judges an upgraded server are in Hardening a public mail server.

The IP range, not the port. RequireTLSForAuth lives on the IP range (Access & abuse protection → IP ranges, the Require auth tab). A range that requires TLS is offered no authentication mechanism at all on a cleartext connection, and IMAP additionally advertises LOGINDISABLED, so a client learns before it sends the password. DisableAUTHList is a comma-separated list of local ports on which SMTP AUTH is neither advertised nor accepted; use it to keep authentication off port 25. Since 6.3.4 such [Settings] keys are kept in the database: change them in the Control Panel, over REST (PUT /api/v1/settings/ini/{name}) or on Linux with hmailserver --set-setting NAME=VALUE. The database's value is the one used; where the service can write hMailServer.ini, a line edited there is put back (HM5804).

Which port, decided once. For sending, 587 with STARTTLS required, or 465 if the client does not do STARTTLS properly; for receiving, 993, or 995 for POP3 on exactly one device. Never 143 or 110 without STARTTLS required, and deny 143 and 110 at the firewall once no client is left on them.

What the server will actually accept

Protocol	Mechanism	Advertised when	Default on a fresh install
SMTP	AUTH LOGIN	AUTH is enabled on the port	Yes
SMTP	AUTH PLAIN	Allow plain-text authentication is on	No - authallowplaintext is seeded 0
SMTP	AUTH SCRAM-SHA-256	Always, when AUTH is enabled	Yes
SMTP	AUTH SCRAM-SHA-256-PLUS	On a TLS connection	Yes, on a TLS connection
SMTP	AUTH XOAUTH2 / OAUTHBEARER	OAuth2 is enabled, and by default over TLS	No
SMTP	AUTH EXTERNAL	The handshake verified a client certificate on that port	No
IMAP	LOGIN command	Unless the port or the IP range requires TLS on a cleartext connection	Yes
IMAP	AUTH=PLAIN, AUTH=SCRAM-SHA-256	Allow SASL PLAIN authentication is on	No - EnableImapSASLPlain is seeded 0
IMAP	SASL-IR	Allow SASL initial client response is on	No
POP3	USER/PASS, SASL PLAIN, SASL SCRAM-SHA-256	Unless authentication is refused on this cleartext connection	Yes

The switches are on Connections & protocols → Protocols, the SMTP and IMAP tabs. Two consequences look like client bugs when they are not. On a default install, an IMAP client that insists on AUTHENTICATE PLAIN finds no AUTH= capability at all and must fall back to LOGIN. And SCRAM is always the account's own password, so an account with a second factor enrolled, or whose password has passed PasswordPolicyMaximumAgeDays, cannot sign in over SCRAM at all. Outlook on the desktop will not use SCRAM: it needs LOGIN or PLAIN.

What the conversation looks like

An extract of IMAP on a default install:

* OK IMAPrev1
a002 LOGIN alice secret
a002 NO Invalid user name or password. Please use full email address as user name.
a003 LOGIN [email protected] secret
a003 OK LOGIN completed

The hint is given because the user name has no @. SMTP submission on 587, STARTTLS required:

220 MAIL01 ESMTP
EHLO laptop.example.net
250-MAIL01
250-SIZE 20971520
250-8BITMIME
250-PIPELINING
250-CHUNKING
250-BINARYMIME
250-SMTPUTF8
250-ENHANCEDSTATUSCODES
250-DSN
250-STARTTLS
250 HELP
MAIL FROM:<[email protected]>
530 5.7.0 Must issue STARTTLS first.
STARTTLS
220 Ready to start TLS

There is no AUTH line in that first answer, because the port requires TLS. After the handshake the client must send EHLO again, since the session starts afresh (RFC 3207 section 4.2). The second answer carries 250-AUTH LOGIN SCRAM-SHA-256 SCRAM-SHA-256-PLUS.

Folders your users will look for

A brand-new mailbox contains INBOX and nothing else. Drafts, Sent, Trash and Junk are created only when Create Drafts, Sent, Trash and Junk for new accounts is switched on (Connections & protocols → Protocols → IMAP), and the setting is seeded off. That is the usual explanation for "my sent mail is not on the server": the client fell back to a local folder because it found nothing designated \Sent.

Fact	Value
Hierarchy delimiter	., so a subfolder of Work is Work.Invoices
Public folders namespace	#Public
Other users' folders namespace	#Users, only when ACL (shared folder permissions) is on - it is on by default
Special-use designations	\Drafts \Sent \Trash \Junk, advertised as SPECIAL-USE and CREATE-SPECIAL-USE

IMAP or POP3. hMailServer advertises EXPIRE NEVER, so "leave mail on server" means for good, and a second POP3 session on the same mailbox gets -ERR [IN-USE].

What 6.3.4 changed in IMAP's answers

Dovecot's imaptest was first run against this server on 25 September 2026: 31 of its 71 scripts failed, and 4 after 6.3.4 made the server answer as the RFCs say. The capability list is unchanged. A client that relied on the old answers may notice these:

When the client	6.3.4 answers
Names a mailbox that does not exist, or needs a right the account lacks	NO, where it used to answer BAD; a failed SELECT or EXAMINE leaves no mailbox selected
Sends an unknown LIST selection or return option	BAD
Fetches any BODY[<section>] without .PEEK	Sets \Seen, BODY[HEADER] and BODY[1.MIME] included
Appends a message	Stores the literal byte for byte, where it used to add a CRLF, so RFC822.SIZE of a newly appended message is two octets smaller
Pipelines a command behind an APPEND with a non-synchronising literal	Answers it; it used to be thrown away, which stopped mbsync after one message
Sorts, or threads	Uses every criterion and builds the RFC's trees, so either can order messages differently
Is the first session to be told of new messages	Counts them as \Recent, where it said * 0 RECENT

Automatic client configuration

The server can configure clients, so users type only their address and password. AutoconfigEnabled is already 1; giving the web-services listener a port is what turns it on (WebServicesHttpPort=80, WebServicesHttpsPort=443), at the next reinitialise or restart, since the listener binds when it starts. Both port keys default to 0. Then point autoconfig.yourcompany.com (Thunderbird) and autodiscover.yourcompany.com (Outlook) at the server; both are ordinary host records.

URL path	Format	Fetched by
/mail/config-v1.1.xml, /.well-known/autoconfig/mail/config-v1.1.xml	Thunderbird autoconfig XML	Thunderbird and its relatives
/autodiscover/autodiscover.xml	Outlook POX autodiscover XML	Outlook
/email.mobileconfig, /mail/config.mobileconfig	Apple configuration profile	iOS and macOS Mail

Which port ends up in the answer. The server reads your actual port rows and picks the best one per protocol:

Rank	Port configuration	socketType written
100	SSL/TLS (implicit)	SSL
90, 80	STARTTLS required on port 587; on any other port	STARTTLS
70, 60	STARTTLS optional on port 587; on any other port	STARTTLS
10	No encryption	plain

A protocol with no port at all is omitted. The host name is AutoconfigClientHost if set, otherwise the server's configured host name; with both empty the endpoint answers 404.

Delegated mailboxes (since 6.3.4). The Outlook answer also names an AlternativeMailbox for every account that has opened a folder to the address asked about, but only to a request with HTTP Basic credentials, over HTTPS, for that very address. An Outlook IMAP profile never sees it: Outlook reads the element only for an Exchange account, and sends credentials only after a 401, which this server never returns here. What puts a delegated mailbox into a client's folder tree is the IMAP #Users namespace. None of this has been measured in Thunderbird or Outlook.

Accounts with a second factor: app passwords

A mail client has nowhere to type a six-digit code. Once a TOTP secret exists on an account, the account password is no longer a mailbox credential, and an app password is the only one. The order matters, and the Windows Control Panel puts the tabs in that order on purpose:

1. Open the account: Accounts & domains → Domains → your domain → Accounts → the account.
2. App passwords tab: create one per device, and write down the generated value; it is shown once.
3. Two-factor tab: enrol the secret.

Do it the other way round and every configured client stops working with no way back in. App passwords work for Active Directory accounts too, and are unaffected by password expiry, so enabling PasswordPolicyMaximumAgeDays does not silently break configured clients. A person makes their own on the webmail's Security page, which asks for the account's password again.

Passkeys and single sign-on do not reach a mail client (since 6.3.4). They sign a person in to the webmail and the Control Deck and nothing else. An account that single sign-on or SCIM made has a random password nobody was told, so it needs a password set by an administrator before its person can make an app password for a phone. A recovery code is not a mail-client credential either.

A mailbox encrypted at rest takes its own password only (since 6.3.4). It cannot enrol a TOTP second factor; on IMAP and POP3 its app passwords, an OAuth2 token, a client certificate and a Kerberos ticket are refused, and SCRAM does not open a key that is closed, so the client signs in with IMAP LOGIN or AUTHENTICATE PLAIN, or POP3 USER/PASS or AUTH PLAIN; and a client that was signed in when the switch was made is disconnected once.

Devices: what revoking does

Every client that has authenticated is one entry on the account's Devices list. Revoking a mail client's entry drops a live IMAP, POP3 or SMTP connection where it stands; a CalDAV, CardDAV or ManageSieve client has no connection to drop, so revoking one means revoking its app password. A revoke is not a ban: a client whose credential still works signs in again, so turn off its app password too, or change the account's password, which drops every connection of the account. Where the list is and what revoking does exactly are in Signing in.

When it does not work

What the user sees	What the server said	Cause	Fix
"Invalid user name or password", with a hint	NO Invalid user name or password. Please use full email address as user name.	Bare user name, no default domain	Use the full address
"Invalid user name or password", no hint	NO Invalid user name or password.	Wrong password, inactive account or domain, a TOTP-enrolled account given its account password, or, since 6.3.8, a user name that differs from the stored address in more than the case of the letters A to Z or has white space at either end	Check both are active; issue an app password; give the address as stored
"Authentication required" on sending	530 5.7.0 SMTP authentication is required.	The client is not logged in for outgoing mail, or is on port 25	Tick "my server requires authentication"; move to 587
"Must issue STARTTLS"	530 5.7.0 Must issue STARTTLS first.	Client encryption set to none on a STARTTLS-required port	Set the client to STARTTLS
A new 6.3.4 installation refuses the password from another machine	530 A SSL/TLS-connection is required for authentication.	The Internet range requires TLS for authentication	Set the client to STARTTLS, or use 465, 993, 995 once created
Client hangs on connect, then times out	Nothing: no session is created	Implicit TLS expected on a STARTTLS port, or the reverse	Match the port's connection security
Repeated logon failures, then silence	NO Too many invalid logon attempts. and a BYE	Ten failures on one connection, the per-name lockout, or the per-IP auto-ban	Access & abuse protection → Auto-ban
Large attachment rejected	552 5.3.4 Message size exceeds fixed maximum message size	The maximum message size, default 20480 KB	Max message size, or the domain's own limit

While diagnosing on Windows, look at Monitoring & troubleshooting → Live logs and Server status, which lists the listeners the service actually brought up. Per client: if Thunderbird offers "no encryption" it found a plain port, so fix the port, not the client.

Where to read more

• Wiki: Connecting a Mail Client, Ports Reference, Encryption and Certificates, Sign-in and Identity.
• Documents: SecureDefaults.md, DevicesAndSessions.md.
• The public documentation: 7. Connecting a mail client, 7.2 Automatic client configuration, 22. Ports reference.
• On this forum: Let's Encrypt certificates are automatic, IMAP and POP3 on the server for shared mailboxes, when a saved setting takes effect, First install on Linux, Upgrading to 6.3.4 and the 6.3.4 announcement.