---
title: "Connecting a mail client: IMAP, POP3, SMTP submission, app passwords and the ports"
url: https://www.hmailserver.co.uk/topic/28255/connecting-a-mail-client-imap-pop3-smtp-submission-app-passwords-and-the-ports
author: "Progressiverobot"
published: 2026-09-27T19:37:13.731Z
updated: 2026-09-27T19:37:13.731Z
category: "Webmail, portal & Control Deck"
tags: ["imap","smtp","tls","security","installation"]
site: hMailServer Community Forum
---

# 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](/topic/28277). 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](/topic/28278).*

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**, `you@yourcompany.com` | 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](/topic/28256).

| 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](/topic/28187).

**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](/topic/28241).

**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](/topic/28226) 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 alice@yourcompany.com 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:<you@yourcompany.com>
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](/topic/28253).

### 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](https://gitlab.com/hmailserver/hmailserver/-/wikis/Connecting-a-Mail-Client), [Ports Reference](https://gitlab.com/hmailserver/hmailserver/-/wikis/Ports-Reference), [Encryption and Certificates](https://gitlab.com/hmailserver/hmailserver/-/wikis/Encryption-and-Certificates), [Sign-in and Identity](https://gitlab.com/hmailserver/hmailserver/-/wikis/Sign-in-and-Identity).
- Documents: [SecureDefaults.md](https://gitlab.com/hmailserver/hmailserver/-/blob/v6.3.4/hmailserver/docs/SecureDefaults.md), [DevicesAndSessions.md](https://gitlab.com/hmailserver/hmailserver/-/blob/v6.3.4/hmailserver/docs/DevicesAndSessions.md).
- The public documentation: [7. Connecting a mail client](https://www.progressiverobot.com/hmailserver-documentation/#7-connecting-a-mail-client), [7.2 Automatic client configuration](https://www.progressiverobot.com/hmailserver-documentation/#72-automatic-client-configuration), [22. Ports reference](https://www.progressiverobot.com/hmailserver-documentation/#22-ports-reference).
- On this forum: [Let's Encrypt certificates are automatic](/topic/28187), [IMAP and POP3 on the server](/topic/28224) for shared mailboxes, [when a saved setting takes effect](/topic/28222), [First install on Linux](/topic/28190), [Upgrading to 6.3.4](/topic/28193) and the [6.3.4 announcement](/topic/28218).