SMTP server
By default, the Mailpit SMTP server listens on port 1025 and does not use encryption or authentication.
There are several options you can set to enable both authentication as well as STARTTLS or SSL/TLS encryption.
SMTP with STARTTLS
When you add a TLS certificate and key to Mailpit, it enables (but does not require) the STARTTLS protocol.
STARTTLS is the default encryption protocol used in Mailpit (as opposed to TLS).
A client connects via plain text (unencrypted protocol) to the SMTP server and can then optionally negotiate a TLS upgrade.
To configure Mailpit to serve SMTP with STARTTLS, a TLS certificate and private key (see certificates)
must be provided via either the command flags or environment when starting Mailpit, for example:
mailpit --smtp-tls-cert /path/to/cert.pem --smtp-tls-key /path/to/key.pem
(env: MP_SMTP_TLS_CERT=/path/to/cert.pem MP_SMTP_TLS_KEY=/path/to/key.pem)
This option allows for both plain text and STARTTLS, providing the most flexibility for email clients.
If you require the client to use STARTTLS, you can add the --smtp-require-starttls (env: MP_SMTP_REQUIRE_STARTTLS=true).
SMTP with SSL/TLS
TLS (often referred to as SSL/TLS) is a different protocol that requires all communication to be done over TLS.
This is slightly more secure than STARTTLS, but requires an SMTP client with full SSL/TLS support.
To start SMTP with TLS, an additional flag --smtp-require-tls (env: MP_SMTP_REQUIRE_TLS=true) must be added:
mailpit --smtp-tls-cert /path/to/cert.pem --smtp-tls-key /path/to/key.pem --smtp-require-tls
Note: this option disables STARTTLS support entirely as the two cannot run together on the same port.
Adding SMTP authentication
You can set a password file using the --smtp-auth-file <file> flag (@env: MP_SMTP_AUTH_FILE=<file>).
Mailpit will accept either the PLAIN or LOGIN authentication mechanisms.
The last paragraph of RFC 4954 states:
A server implementation MUST implement a configuration in which
it does NOT permit any plaintext password mechanisms, unless either
the STARTTLS [SMTP-TLS] command has been negotiated or some other
mechanism that protects the session from password snooping has been
provided. Server sites SHOULD NOT use any configuration which
permits a plaintext password mechanism without such a protection
mechanism against password snooping.
This means that, by default, SMTP authentication must be configured together with a TLS certificate to enable and require either STARTTLS or SSL/TLS encryption.
For testing purposes, Mailpit does include a --smtp-auth-allow-insecure flag (@env: MP_SMTP_AUTH_ALLOW_INSECURE=true) to allow SMTP authentication over a plain text connection (i.e., not encrypted).
For testing purposes, Mailpit also allows you to accept any username and password (or none) by using the --smtp-auth-accept-any flag. This will literally accept any username and password (or none).
Passwords via environment
If you do not wish to use a password file, you can optionally export the MP_SMTP_AUTH environment variable with a space-separated list of your credentials, e.g., MP_SMTP_AUTH="user1:password1 user2:password".
For security reasons, this option is not available as a CLI flag.
Edit this page