Metadata-Version: 2.1
Name: smtp-logger
Version: 0.0.1
Summary: Mock SMTP server that logs the emails it receives
Author-email: Dave Peck <dave@literalgarage.com>
License: MIT
Project-URL: Homepage, https://github.com/literalgarage/smtp-logger
Project-URL: Changelog, https://github.com/literalgarage/smtp-logger/releases
Project-URL: Issues, https://github.com/literalgarage/smtp-logger/issues
Project-URL: CI, https://github.com/literalgarage/smtp-logger/actions
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: build
Requires-Dist: setuptools; extra == "build"
Requires-Dist: wheel; extra == "build"
Requires-Dist: build; extra == "build"

# smtp-logger

[![PyPI](https://img.shields.io/pypi/v/smtp-logger.svg)](https://pypi.org/project/smtp-logger/)
[![Tests](https://github.com/literalgarage/smtp-logger/actions/workflows/test.yml/badge.svg)](https://github.com/literalgarage/smtp-logger/actions/workflows/test.yml)
[![Changelog](https://img.shields.io/github/v/release/literalgarage/smtp-logger?include_prereleases&label=changelog)](https://github.com/literalgarage/smtp-logger/releases)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/literalgarage/smtp-logger/blob/main/LICENSE)

Mock SMTP server that logs the emails it receives.

Listens to inbound connections from SMTP clients. Supports a very minimal set of SMTP features, but probably enough that most clients will communicate happily and emails will get "delivered" as expected.

## Why?

This is useful in development, typically as part of a `docker-compose.yml`.

There have been a couple cases recently where I wanted to work with an OSS tool that required a configured SMTP server (for instance, to send password reset or login link emails). The tool itself didn't offer an alternative, so creating a simple logging SMTP service seemed like the best way to go.

## Installation and usage via Docker

This is probably how you want to use `smtp-logger`. This way your project does not need to depend on python (even though the docker image does).

The latest version of `smtp-logger` is packaged in a docker image available at `ghcr.io/literalgarage/smtp-logger:latest`.

For instance, to create an `smtp` logger service in your `docker-compose.yml`:

```
smtp:
  image: ghcr.io/literalgarage/smtp-logger:latest
  environment:
    - SMTP_LOGGER_PORT=8025
  ports:
    - "8025:8025"
```

## Installation and usage locally

Install this library using `pip`:

```bash
pip install smtp-logger
```

This provides an `smtp-logger` binary:

```
> smtp-logger --host 0.0.0.0 --port 8025
```

It accepts only `--host` and `--port` parameters. These are optional.

If not supplied, the `SMTP_LOGGER_HOST` and `SMTP_LOGGER_PORT` environment variables are used. These are also optional.

If configuration is missing then, by default, `SMTP_LOGGER_HOST` is `0.0.0.0` and `SMTP_LOGGER_PORT` is `8025`.

## Development

This is the simplest SMTP logging implementation that worked for the specific cases I ran into. There are an enormous number of basic and advanced SMTP features this server doesn't yet support. Its handling of `content-transfer-encoding`s is weak at the moment. It doesn't support TLS. etc.

I'd love your help improving this tool!

To contribute to this library, first checkout the code. Then create a new virtual environment:

```bash
cd smtp-logger
python -m venv .venv
source .venv/bin/activate
```

Now install the dependencies and test dependencies:

```bash
pip install -e '.[dev]'
```

To run tests:

```bash
make test
```

To run a full lint/typecheck/test pass:

```bash
make check
```
