Docker Mailserver SASL Authentication Failed? Fix SMTP Login

Your mail client reaches Docker Mailserver but cannot send. The client may report “authentication failed”, while Postfix logs something like SASL LOGIN authentication failed or Password verification failed. Re-entering the password sometimes helps, but that message does not prove the password is the only broken layer.

SMTP authentication on a normal Docker Mailserver setup crosses several boundaries: the client selects the correct submission service, negotiates the right TLS mode, receives an AUTH capability, submits a mailbox identity, and Postfix asks its configured SASL backend—normally Dovecot—to verify it. Fail2Ban may also block the source after repeated failures.

Test one controlled login while watching the matching server event. Do not paste passwords, AUTH payloads, complete logs, account hashes, or real server addresses into public troubleshooting posts.

First: identify which failure you actually have

These symptoms belong to different layers:

If no SMTP response arrives, use the port and timeout checklist first. If the log proves successful SASL authentication but Postfix refuses the recipient, move to the relay access denied guide.

1. Verify the submission route and TLS mode

Mail clients normally submit outbound messages on port 587 with STARTTLS or port 465 with implicit TLS. Port 25 is primarily for server-to-server SMTP transfer. The encryption setting must match the port:

• 587: connect in plain SMTP, issue STARTTLS, then continue inside TLS;
• 465: begin TLS immediately when the TCP connection opens.

A client configured for “SSL/TLS” on 587 or STARTTLS on 465 can fail before credentials are meaningfully checked. Probe capabilities without supplying a password:

# STARTTLS submission
openssl s_client -starttls smtp \
  -connect mail.example.com:587 \
  -servername mail.example.com -crlf

EHLO client.example.invalid
QUIT

After TLS, the EHLO response should advertise AUTH on the intended submission service. The certificate name should match the mail hostname. For implicit TLS, use openssl s_client -connect mail.example.com:465 -servername mail.example.com -crlf without -starttls smtp.

2. Match one attempt to the Docker Mailserver log

Start a short log view, make exactly one login attempt, then stop reading:

docker compose ps

docker compose logs --since 5m --follow mailserver

Use your actual Compose service name. Correlate the timestamp and client source privately. Useful distinctions include:

• Password verification failed: the request reached the authentication backend, which rejected the supplied identity or secret.
• unknown user: inspect the complete mailbox name and active account source.
• cannot connect or connection lost to authentication server: inspect Dovecot/backend health and socket configuration before resetting passwords.
• no new server event: the client may be reaching another address, another container, a blocked source, or no listener at all.
• a success event with sasl_username: authentication worked; follow the later transaction rather than changing the password.

Keep raw logs private. They can include account names, source addresses, recipient addresses, message IDs, internal hostnames, and other operational details.

3. Use the complete mailbox address as the login

For file-provisioned Docker Mailserver accounts, the expected identity is normally the full address, such as [email protected], not merely person. Check the outgoing-account settings independently from IMAP settings; some clients have a separate SMTP username or silently reuse an old saved credential.

Verify all of these:

• outgoing server hostname is the intended mail host;
• SMTP authentication is enabled;
• the full mailbox address is entered without whitespace;
• the password manager did not retain a superseded password;
• the client is not selecting a different saved SMTP identity for this From address;
• the password was copied without surrounding quotes or a trailing newline.

Do not test by manually typing AUTH LOGIN and publishing its base64 values. Base64 is reversible encoding, not secret protection.

4. Prove that the account exists in the active DMS configuration

For the default file-based provisioner, list accounts through DMS’s supported setup helper:

docker compose exec mailserver setup email list

Confirm the expected full address is present. Do not print the underlying account file: it contains password hashes and belongs in protected configuration and backups.

If the account is missing, add or update it with the setup helper documented for the exact Docker Mailserver image you have pinned. If you use LDAP, OAuth2, or another provisioner, test that provider and its mapping instead of modifying the file-based account database. Changing the wrong account source creates noise and can make rollback harder.

5. Change a password deliberately, not speculatively

Reset the password only when the logs and account inventory point to a credential mismatch, or when compromise is suspected. With the default provisioner, use the current DMS setup command interactively so the secret does not enter shell history:

docker compose exec mailserver \
  setup email update [email protected]

Enter the new value at the prompt. Then update one client and run one test. Avoid putting the password after the command, in Compose files, chat messages, process arguments, screenshots, or CI logs. If several devices suddenly fail after a deliberate rotation, update them one at a time rather than weakening authentication.

6. Inspect the effective Postfix-to-Dovecot SASL path

Docker Mailserver normally lets Postfix delegate submission authentication to Dovecot. Read only the relevant effective settings:

docker compose exec mailserver postconf \
  smtpd_sasl_auth_enable \
  smtpd_sasl_type \
  smtpd_sasl_path \
  smtpd_tls_auth_only

docker compose exec mailserver postconf -M | grep -E \
  '^(submission|submissions)/'

The submission service can have per-service overrides, so a global value alone is not the whole answer. Compare the output with the official documentation for your pinned version and your deliberate override files. Do not edit generated main.cf or master.cf inside a running container as a permanent fix: a recreation can erase the change.

If logs show a temporary backend failure, check recent container startup and Dovecot events, filesystem capacity, and whether an unsupported override changed the authentication socket or permissions:

docker compose logs --since 15m mailserver

docker compose exec mailserver doveconf -n

docker compose exec mailserver df -h

doveconf -n can be lengthy and reveal internal details, so inspect it privately. The official Postfix SASL guide notes that the SMTP server must be able to access its authentication service. In a maintained DMS image, use supported configuration paths rather than applying distribution-specific socket recipes blindly.

7. Check whether Fail2Ban blocked the test source

Repeated failed logins can trigger Docker Mailserver’s Fail2Ban protection. That is useful, but it means a corrected password may still appear broken from the already-banned source. Inspect status through DMS:

docker compose exec mailserver setup fail2ban status

If the source is banned, first confirm the failures were your own tests and that no device or attacker is continuing to submit bad credentials. Stop the faulty client before applying the version-appropriate unban command. Do not disable Fail2Ban globally or allowlist a broad public range just to make one login work.

A continuing stream of unfamiliar failures is a security event. Preserve relevant logs, rotate the affected credential if necessary, review mailbox/application access, and keep rate controls enabled.

8. Separate client authentication from relay-host authentication

There can be two different SASL relationships:

1. your mail client authenticates to Docker Mailserver on 587 or 465;
2. Docker Mailserver optionally authenticates to an upstream smarthost when delivering queued mail.

A client-side failure appears during submission and uses Postfix’s SMTP server settings. An upstream failure appears after the message has been accepted and queued, and uses Postfix’s SMTP client settings. Their logs, credentials, and configuration parameters are different. If a message is accepted locally but sits deferred with an upstream 535, follow the deferred queue runbook and inspect the relay-host route.

9. Verify recovery with a small test matrix

1. Confirm the corrected client negotiates the expected TLS mode and certificate.
2. Send one harmless message to an external mailbox you control.
3. Verify the matching log transaction records successful SASL authentication.
4. Verify Postfix accepts the recipient and assigns a queue ID.
5. Follow that ID until status=sent or preserve the next exact delivery error.
6. Confirm a deliberately wrong password is rejected without excessive repeated attempts.
7. Confirm unauthenticated external relay remains denied.

SMTP login success is only the first checkpoint. A message can authenticate correctly and still fail sender policy, queue delivery, DNS authentication, or recipient acceptance. Keep each boundary separate.

Compact diagnosis order

1. Classify timeout, TLS, missing AUTH, credential rejection, temporary backend failure, or post-login relay denial.
2. Verify 587 with STARTTLS or 465 with implicit TLS.
3. Match one controlled attempt to one redacted server event.
4. Use the complete mailbox address and clear stale client credentials.
5. Confirm the account exists in the active DMS provisioner.
6. Reset a password interactively only when evidence supports it.
7. Inspect the effective submission and Postfix-to-Dovecot SASL path.
8. Check Fail2Ban without disabling it broadly.
9. Retest one message and follow its queue ID to final delivery.

The authoritative references are Docker Mailserver’s account-management overview, its port and submission guidance, its Fail2Ban documentation, and the official Postfix SASL guide. Match commands and supported override paths to the DMS image version you actually run.