opentrashmail is a mail server and a web interface in one container

The mail server is part of the product

The description is an open source standalone trashmail solution that ships its own mail server, and the badge line says it is made with HTMX, with PHP 8.1 or newer and Python 3.11. The Python part is the mail server, described as powered and as working out of the box for any domain you throw at it, and it supports plaintext, STARTTLS and TLS on connect, so you can decide how much protection the transport gets. The PHP part is the web interface and the API, and the two are served together, which is why the Docker image carries both runtimes. The feature list also makes the point that no addresses need to be created in advance, since any valid email address can be sent to, and the web interface can generate random addresses for you. That property is what makes the whole thing usable as a test fixture, and it is also what makes a public instance interesting to everybody else.

Everything is a file, and there is no database

One line in the feature list says a hundred percent file based, no database needed, and the compose file shows what that means in practice, with a volume mounted at the data directory and another at the logs directory, both under the application path in the container. There is no migration to run, no database to back up, and no service to keep alive besides the container itself, which for a self-hosted utility is a genuine simplification. The trade is that the storage semantics are whatever the file system gives you, and the compose file has a `SKIP_FILEPERMISSIONS` setting that exists precisely because running as a non-root user in a mounted volume causes permission trouble. The logs directory is where the mail server's own output goes, and the admin view in the web interface is where you read it.

Four ways to read what arrived

The headline says it receives emails via a web interface, a JSON API, an RSS feed and custom webhooks, and each of those is aimed at a different consumer. The web interface is the human one, with an automatic dark and light mode switcher, downloading attachments, deleting emails, generating random addresses, and, for the administrator, viewing the server logs and listing all accounts. The RSS feed is per email address, which is the old, reliable way for a client to poll a mailbox without a client library. The JSON API is the one to build against, and the description says it can be used to automate 2FA emails. The webhooks are the one for systems that would rather be told, and they are configured per email address with customisable JSON payloads. For a test harness, the usual choice is a webhook, and for a human, the web interface.

The endpoints, and the two that can return a great deal

The API documentation is two tables, and reading them tells you the shape of the service. The general endpoints cover the RSS feed at `/rss/` followed by the address, the raw message at `/api/raw/` with the address and an id, the attachment at `/api/attachment` with the address and an attachment id, deletion of a single message at `/api/delete/`, deletion of a whole account at `/api/deleteaccount/`, and the webhook configuration with get, save and delete variants. The JSON API has the address form that returns an array of received emails with links to the attachments and the parsed text body, the per-message form that returns the raw and HTML body, and a list-accounts endpoint that only works when `SHOW_ACCOUNT_LIST` is enabled in the configuration. Two of these deserve a warning, and the documentation gives them. The raw endpoint can be as large as the email itself, which might be twenty megabytes for a mail with large attachments, and the per-message JSON endpoint can be huge because the body can contain all the attachments in base64.

One ini file, and access control that is off by default

Configuration is a single `config.ini`, and an `example.config.ini` sits in the repository. The settings worth knowing are the ones about access. `PASSWORD` means the site and the API cannot be used without it, and it can be supplied as a form field, a POST or GET variable called `password`, or an HTTP header called `PWD`, which is how a script authenticates. `ALLOWED_IPS` is a comma separated list of IPv4 or IPv6 CIDR blocks allowed to use the web interface or the API. `TRUSTED_PROXIES` is a comma separated list of CIDR ranges of reverse proxies whose `X-Forwarded-For` and `CF-Connecting-IP` headers are trusted for the purposes of the IP allow list, with proxies in private networks always trusted and the setting only needed when a public proxy such as Cloudflare connects straight to the application. Then there is `ADMIN`, an address that lists every email of every account, a kind of catch-all, and `DOMAINS`, the comma separated list of domains the server receives mail for.

Running it is a compose file and a port mapping

The published image is `hascheksolutions/opentrashmail`, and the compose file in the repository shows the whole deployment. The service mounts the data and logs directories and takes its settings from the environment:

    environment:
      - URL=http://localhost:8080
      - DOMAINS=example.com
      - DATEFORMAT=D.M.YYYY HH:mm

The environment block also shows the settings that are switched on by default and the ones that are left commented, which is a useful inventory of what the maintainers considered safe to enable. `SKIP_FILEPERMISSIONS`, `DISCARD_UNKNOWN` and `ADMIN_ENABLED` are on, and the commented lines show an admin password, a general password, an IP allow list, a maximum attachment size, the TLS port with a certificate and a private key, a webhook URL, the user and group IDs, and a notice string. Two ports are published:

    ports:
      - '2525:25'
      - '8080:80'

So the SMTP listener is on 2525 in the compose file rather than the default 25, and the web interface is on 8080. A development compose file sits alongside the production one, and the repository also carries a `python/` directory for the mail server, a `web/` directory for the interface, `tools/`, `docs/` and a `wordlists/` directory.

What it is for, and what a public instance attracts

The feature list names the uses it has in mind, an email honeypot, and programmatically solving 2FA emails, and the JSON API section says the same thing again, that the API can be used to automate 2FA emails. Both are legitimate uses of a disposable mailbox, and a self-hosted instance on a private network is the sensible way to get one. The other side is that a public instance accepting mail for any address on your domain, with an API that hands the content out, is exactly the tool that people use to receive account verification codes for other people's accounts. The configuration has the mitigations, the password, the IP allow list, the trusted proxy handling and the admin switch, but they are opt-in. The honest summary is that this is a well-built utility for testing and honeypots, and that putting it on the open internet without turning the access controls on is a decision with consequences that the documentation's feature list does not discuss.

Editorial conclusion

opentrashmail suits a developer who needs a throwaway mailbox for a test or a demo and wants the whole thing on their own machine, and it suits a security researcher who wants a honeypot address that logs what is sent to it. It is a poor fit if you intend to run a public instance without thinking about abuse, because a service that accepts mail for any address on any domain and hands it out over an API attracts the traffic you would expect, and the access controls in the configuration exist for that reason. Before you deploy it, check three things: the `PASSWORD` and `ALLOWED_IPS` settings, which are the difference between a private tool and an open relay for spam, the `DOMAINS` list, which feeds the random address generator, and the TLS options, because the default is plaintext and STARTTLS, which is fine on a private network and not fine anywhere else.

Frequently asked questions

Official sources

1. HaschekSolutions/opentrashmail on GitHub
2. Issues
3. License: Apache-2.0
4. README