This is a simple SMTP test server for CI/CD pipelines and development environments. It was designed for the case where a component is designed to communicate via SMTP - and we want to directly see if that was successful. Going over a real SMTP server complicates this a lot, introduces additional error sources - and in isolated environments may not be possible at all.
Many projects handle this by just not testing SMTP sending, or introducing a second codepath for CI that just writes the message out - which is similar to not testing it.
As a result of this design goal per default no validation of sender or recipient addresses is performed - and while there is limited support that can be enabled that does currently make it a bad candidate to test actual email clients. Adding required functionality to handle common SMTP delivery errors a client should handle would be trivial, though.
Currently supported features are:
- Pretty much complete SMTP protocol support (HELO, EHLO, MAIL FROM, RCPT TO, DATA, RSET, QUIT, NOOP)
- TLS support with three modes:
- STARTTLS (upgrade plain connection to TLS)
- Direct TLS (TLS from start)
- Disabled (plain text only)
- Auto-generated self-signed certificates for testing, if no certificate is provided
- Configurable filename templates for saved emails
- Automatic shutdown after receiving N emails
- Message size limits
- Connection timeouts
- Address validation with wildcard support (only supported when running with configuration file)
This needs go and make to build. Use make build to build for the current OS and architecture, or make build-all to build for all supported architectures. Binaries will be named debug-smtpd-<os>-arch>.
Alternatively binaries are also available from this repositories release page.
Options can be provided via a YAML file or CLI flags. If both are provided CLI flags will override YAML settings. examples/config.yaml is a fully documented example, this documentation only covers the CLI arguments.
The path to a YAML configuration file
The hostname or IP to bind to. Defaults to “0.0.0.0”.
As the assumption is that this server will only be used for a short time during test runs, and typically on isolated networks binding to all interfaces usually should not be an issue.
The port to bind to. Defaults to 2525 to avoid problems binding to unprivileged ports.
The template used for creating file names for emails, defaulting to {{.Index}}-{{.UnixTime}}-{{.From}}-{{.To}}.eml.
Available variables are:
- `{{.Index}}` - Sequential email number (1, 2, 3…)
- `{{.UnixTime}}` - Unix timestamp
- `{{.Timestamp}}` - Time object (use `.Format` for custom formatting)
- `{{.From}}` - Sanitized sender address
- `{{.To}}` - Sanitized recipient address
- `{{.MessageID}}` - Message-ID header (if present)
A custom date format would look like this: {{.Timestamp.Format "2006-01-02_15-04-05"}}-{{.From}}.eml
Specify how many emails the server should receive before exiting. If not specified defaults to 0 (=unlimited).
The maximum message size in bytes, defaulting to 10485760 (10MB).
The directory to save received emails in. Defaults to “./received”.
Set the TLS mode of the server, which can be one of starttls, direct or disabled. Default is disabled.
direct only accepts TLS connections, while starttls starts plain, and supports upgrading via starttls.
The path to a certificate file. This is relevant only when using TLS. If omitted, but required a self signed certificate will be generated.
The path to a key file. This is relevant only when using TLS. If omitted, but required a new key will be generated in memory.
Verbosity of the program, supported are debug, info, warn and error. The default is info.
Connection timeout for the server in seconds, defaulting to 300.
Show the version and exit. Typically the version should be the short git commit hash.