Docker Mailserver TLS Certificate Hostname Mismatch? Fix the Name

An email client connects to your Docker Mailserver host and warns that the certificate belongs to another name. Or an SMTP test reports a hostname mismatch even though the certificate is current and issued by a trusted authority. This is not an expiry problem: the client asked for one hostname, but the live certificate does not identify that hostname in its Subject Alternative Name list.

Do not fix this by disabling certificate verification, accepting a permanent warning, or putting Cloudflare’s web proxy in front of mail ports. Identify the exact name and endpoint the client reaches, then make the client configuration, public DNS, Docker Mailserver FQDN, certificate SANs, and live Postfix/Dovecot handshakes agree.

Keep real addresses, public server addresses, private-key paths, certificate automation credentials, and full configuration dumps out of tickets and public repositories. The examples below use reserved domains and placeholders.

What must match?

If the account is [email protected], the incoming and outgoing server can still be mail.example.com. Docker Mailserver’s documentation makes this distinction explicit: the server FQDN is used for service identity and certificate selection; it does not change the domain of mailbox addresses.

A normal arrangement has:

• the mail client configured to use mail.example.com for IMAP and submission;
• the MX record pointing to mail.example.com for inbound SMTP;
• mail.example.com resolving directly to the mail host;
• the Docker Mailserver service hostname set to mail.example.com;
• a public certificate whose SAN list includes mail.example.com;
• Postfix and Dovecot serving that certificate on their respective ports.

The certificate does not normally need every hosted email domain. If one Docker Mailserver instance handles example.com and example.net, users from both can connect to the same canonical server name.

1. Record the exact failing name, port, and TLS mode

Start with the client settings rather than the certificate directory. Record the hostname exactly as entered and classify the service:

Using an IP address, the bare domain, an old host alias, or the VPS provider’s generated hostname can all cause a mismatch even when mail.example.com is correctly covered. The TLS mode matters too: an implicit-TLS test against a STARTTLS port produces a different failure and should not be diagnosed as a certificate-name problem.

2. Inspect the certificate served to a real external client

Run the test from outside the VPS so it follows public DNS and reaches the same endpoint as users. For SMTP STARTTLS:

openssl s_client \
  -connect mail.example.com:587 \
  -starttls smtp \
  -servername mail.example.com \
  -verify_hostname mail.example.com \
  -showcerts </dev/null

For implicit TLS IMAP:

openssl s_client \
  -connect mail.example.com:993 \
  -servername mail.example.com \
  -verify_hostname mail.example.com \
  -showcerts </dev/null

Look for the peer certificate’s issuer, validity dates, SAN list, and final verification result. -servername sends SNI where supported; -verify_hostname actually checks the identity you care about. A generic Verify return code: 0 chain result alone does not prove that your chosen hostname matches unless the hostname check was requested.

3. Prove DNS is reaching one intended host

Check the mail name and MX without publishing the returned addresses:

dig +short MX example.com

dig +short A mail.example.com

dig +short AAAA mail.example.com

Test IPv4 and IPv6 separately when both exist:

openssl s_client -4 -connect mail.example.com:993 \
  -servername mail.example.com -verify_hostname mail.example.com </dev/null

openssl s_client -6 -connect mail.example.com:993 \
  -servername mail.example.com -verify_hostname mail.example.com </dev/null

If the two families serve different certificates, repair or remove the stale path deliberately. Also remember that Cloudflare’s normal orange-cloud proxy is for supported web traffic, not arbitrary SMTP or IMAP. Keep ordinary mail host records DNS-only unless you use a product specifically designed to proxy those protocols.

4. Align Docker Mailserver’s FQDN

Docker Mailserver documents the service hostname as the source of its FQDN. Inspect the effective Compose model and the running value privately:

docker compose config

docker compose exec mailserver hostname -f

A simplified service definition is:

services:
  mailserver:
    hostname: mail.example.com
    environment:
      SSL_TYPE: letsencrypt
    volumes:
      - /etc/letsencrypt:/etc/letsencrypt:ro

Do not copy that mount blindly. Use the certificate method and persistent host location appropriate to your installation. With the documented Let’s Encrypt method, mounting the whole tree matters because files under live/ commonly point into archive/ through symlinks.

5. Check the SANs and the full chain inside the container

Inspect the certificate Docker Mailserver can actually read, not only the one Certbot reports on the host. For the documented Let’s Encrypt layout:

docker compose exec mailserver \
  openssl x509 \
  -in /etc/letsencrypt/live/mail.example.com/fullchain.pem \
  -noout -subject -issuer -dates -ext subjectAltName

The SAN extension must cover the canonical mail name. A wildcard such as *.example.com can cover mail.example.com, but not the bare example.com and not a deeper name such as imap.mail.example.com. Prefer one clear canonical mail hostname unless there is a real need for several client-facing aliases.

If you use SSL_TYPE=manual, confirm that SSL_CERT_PATH points to a PEM-encoded full chain and SSL_KEY_PATH points to its matching unencrypted private key. Never print or copy the key into diagnostics.

6. Compare Postfix and Dovecot, not just one port

A renewal hook or mount error can leave services out of sync. Compare fingerprints without exposing private keys:

for test in \
  "587 -starttls smtp" \
  "993"; do
  set -- $test
  port=$1
  shift
  openssl s_client -connect mail.example.com:$port \
    -servername mail.example.com "$@" </dev/null 2>/dev/null \
    | openssl x509 -noout -fingerprint -sha256 -dates -ext subjectAltName
done

If SMTP and IMAP return different fingerprints, inspect the effective Postfix and Dovecot certificate paths inside the container and the recent startup/reload logs. Docker Mailserver notes that a restart may be necessary after certificate changes; use your pinned version’s change-detection behavior and recreate only after confirming the mounted source is correct.

7. Choose the smallest correct repair

• Client uses the wrong alias: change it to the canonical covered mail hostname.
• DNS points to an old endpoint: correct the stale A/AAAA or MX path and wait for normal DNS caching to expire.
• Container FQDN is wrong: update the Compose service hostname, validate the model, and recreate the service in a controlled window.
• Certificate lacks the name: reissue it with the intended SAN, then confirm the mounted chain and key pair before reload.
• Wrong lineage or bind mount: point Docker Mailserver at the maintained certificate tree; avoid a file-level bind mount when renewal replaces the file’s inode.
• Services are stale: reload or restart after confirming the new certificate is visible inside the running container.

Do not add every historical alias to the certificate merely to silence old clients. That expands public Certificate Transparency exposure and creates more names to renew and protect. Retire obsolete names when you can.

8. Verify a complete client path

1. Repeat external SMTP and IMAP tests with -verify_hostname.
2. Confirm the expected SAN, issuer, dates, and fingerprint on both services.
3. Test IPv4 and IPv6 independently if both are published.
4. Configure a real mail client with the canonical hostname and normal verification enabled.
5. Receive one message through the public MX path.
6. Submit one message through authenticated port 587 or 465 and confirm final delivery.
7. Re-run the checks after the next automated certificate renewal.

A green container health check does not prove hostname verification. The useful final evidence is a real external handshake on each published mail service, using the same DNS name and TLS mode as clients, with certificate-name verification enabled.

Compact diagnosis order

1. Record the exact client hostname, port, and TLS mode.
2. Inspect the live external certificate with SNI and hostname verification.
3. Split-test A and AAAA routes.
4. Confirm the Docker Mailserver FQDN.
5. Inspect SANs and the full chain inside the container.
6. Compare Postfix and Dovecot fingerprints.
7. Repair the narrowest wrong name, DNS route, mount, certificate, or stale service.
8. Verify receiving, authenticated submission, and the next renewal.

Authoritative references: Docker Mailserver’s official SSL/TLS configuration guide, including its FQDN, certificate provisioning, SAN inspection, SNI, IPv4/IPv6, and external-test guidance; its mail-port and TLS-mode guide; Postfix’s official TLS support documentation; and OpenSSL’s s_client reference. Match paths and behavior to the Docker Mailserver and OpenSSL versions you actually run.