10 KiB
Open Trashmail
Changelog
Features
- Python-powered mail server that works out of the box for any domain you throw at it
- RSS feed for every email address
- JSON API for integrating it in your own projects. Can be used to automate 2fa emails
- Handles attachments
- Web interface to manage emails
- Generates random email addresses
- 100% file based, no database needed
- Can be used as Email Honeypot or to programmatically solve 2fa emails
General API calls and functions
JSON API
Configuration
Just edit the config.ini
You can use the following settings
URL
-> The url under which the GUI will be hosted. No tailing slash! example: https://trashmail.mydomain.euDOMAINS
-> Comma separated list of domains this mail server will be receiving emails on. It's just so the web interface can generate random addressesMAILPORT
-> The port the Python-powered SMTP server will listen on.Default: 25
ADMIN
-> An email address (doesn't have to exist, just has to be valid) that will list all emails of all addresses the server has received. Kind of a catch-allDATEFORMAT
-> How should timestamps be shown on the web interface (moment.js syntax)PASSWORD
-> If configured, site and API can't be used without providing it via form, POST/GET variablepassword
or http headerPWD
(eg:curl -H "PWD: 123456" http://localhost:8080/json...
)ALLOWED_IPS
-> Comma separated list of IPv4 or IPv6 CIDR addresses that are allowed to use the web UI or APIATTACHMENTS_MAX_SIZE
-> Max size for each individual attachment of an email in Bytes
Docker env vars
In Docker you can use the following environment variables:
ENV var | What it does | Example values |
---|---|---|
URL | The URL of the web interface. Used by the API and RSS feed | http://localhost:8080 |
DISCARD_UNKNOWN | Tells the Mailserver to wether or not delete emails that are addressed to domains that are not configured | true, false |
DOMAINS | The whitelisted Domains the server will listen for. If DISCARD_UNKNOWN is set to false, this will only be used to generate random emails in the webinterface | |
SHOW_ACCOUNT_LIST | If set to true , all accounts that have previously received emails can be listed via API or webinterface |
true,false |
ADMIN | If set to a valid email address and this address is entered in the API or webinterface, will show all emails of all accounts. Kind-of catch-all | test@test.com |
DATEFORMAT | Will format the received date in the web interface based on moment.js syntax | "MMMM Do YYYY, h:mm:ss a" |
SKIP_FILEPERMISSIONS | If set to true , won't fix file permissions for the code data folder in the container. Useful for local dev. Default false |
true,false |
PASSWORD | If configured, site and API can't be used without providing it via form, POST/GET variable password or http header PWD |
yousrstrongpassword |
ALLOWED_IPS | Comma separated list of IPv4 or IPv6 CIDR addresses that are allowed to use the web UI or API | 192.168.5.0/24,2a02:ab:cd:ef::/60,172.16.0.0/16 |
ATTACHMENTS_MAX_SIZE | Max size for each individual attachment of an email in Bytes | 2000000 = 2MB |
Roadmap
- Mail server
- Storing received mails in JSON
- Storing file attachments
- Docker files and configs
- Web interface
- Choose email
- Get random email address
- Download attachments safely
- Display Text/HTML
- API so all features from the site can also be automated and integrated
- Automatically check for new emails while on site
- Admin overview for all available email addresses
- Option to show raw email
- Delete messages
- Make better theme
- Secure HTML, so no malicious things can be loaded
- Display embedded images inline using Content-ID
- Configurable settings
- Choose domains for random generation
- Choose if out-of-scope emails are discarded
- Automated cleanup of old mails
- Optionally secure whole site with a password
- Optionally allow site to be seen only from specific IP Range
- Honeypot mode where all emails are also saved for a catchall account (implemented with the ADMIN setting)
Quick start
Set the MX Records
In your DNS panel create a MX record for your domain pointing to the IP of the server hosting OpenTrashmail.
The following example will allow you to send emails to example.com
mail.example.com. IN A 93.184.216.34
example.com. 14400 IN MX 10 mail.example.com.
This advanced example will allow you to use a wildcard domain:
mail.example.com. IN A 93.184.216.34
*.example.com. 14400 IN MX 10 mail.example.com.
This in combination with the configuration option "DOMAINS" (eg docker parameter -e DOMAINS="*.example.com"
) will allow you to use any address with any subdomain of example.com (eg test@robot.example.com, john@lynn.example.com, etc..)
Running in docker (preferred)
Simple start with no persistence
docker run -it -p 25:25 -p 80:80 -e URL="https://localhost:80" hascheksolutions/opentrashmail:1
Saving data directory on host machine
docker run -p 80:80 -p 25:25 -e URL="https://localhost:80" -v /path/on/host/where/to/save/data:/var/www/opentrashmail/data hascheksolutions/opentrashmail:1
Complete example with running as daemon, persistence, a domain for auto-generation of emails, acceptng only emails for configured domains, cleanup for mails older than 90 days and auto restart
docker run -d --restart=unless-stopped --name opentrashmail -e "DOMAINS=mydomain.eu" -e "DATEFORMAT='D.M.YYYY HH:mm'" -e "DISCARD_UNKNOWN=false" -e "DELETE_OLDER_THAN_DAYS=90" -p 80:80 -p 25:25 -v /path/on/host/where/to/save/data:/var/www/opentrashmail/data hascheksolutions/opentrashmail:1
How it works
The heart of Open Trashmail is a Python-powered SMTP server that listens on incoming emails and stores them as JSON files. The server doesn't have to know the right email domain, it will just catch everything it receives. You only have to expose port 25 to the web and set an MX record of your domain pointing to the IP address of your machine.