DOCSEARCHbyAlgolia
Submit Docs

Open Trashmail Documentation

repository·master·Indexed 21 days ago

https://github.com/hascheksolutions/opentrashmail

A self-hosted, Python-powered mail server for temporary email addresses. It is 100% file-based (no database required) and provides a Web UI, JSON API, RSS feeds, and webhooks. Key features include automated 2FA retrieval, email honeypot capabilities, attachment handling, and support for Plaintext, STARTTLS, and TLS on connect (TLSC). It can be deployed via Docker with configurable environment variables for domains, security, and administration.

Tokens
8.9K
Snippets
21
Records
32
Agent score
74%

What's inside Open Trashmail

  1. Overview of Open Trashmail features

    master

    Open Trashmail is a self-hosted, Python-powered mail server designed to receive emails via a Web UI, JSON API, RSS feeds, and custom webhooks. It is 100% file-based (no database required) and allows any valid email address to receive mail without pre-creation.

    Key features include:

    • Automated 2FA: Use the JSON API to automate 2FA email retrieval.
    • Honeypot Capability: Can be used as an email honeypot.
    • Attachments: Handles and allows downloading of email attachments.
    • Security: Supports Plaintext, STARTTLS, and TLS on connect (TLSC).
    • Web Interface: Includes dark/light mode, attachment management, email deletion, and random address generation.
    • Admin Tools: View server logs and list all accounts (if enabled).

  2. Understand TLS and STARTTLS in Open Trashmail

    master

    Open Trashmail supports two methods of using TLS for email:

    1. STARTTLS: The connection starts as plaintext and upgrades to TLS if the server advertises the STARTTLS command. This happens automatically if TLS_CERTIFICATE and TLS_PRIVATE_KEY are configured. It runs on the default MAILPORT (usually 25), so no additional ports need to be opened.

    2. TLS on Connect (TLSC): This wraps the entire connection in TLS from the start, making plaintext communication impossible. This requires a dedicated port, typically 465, configured via MAILPORT_TLS.

  3. Configure Per-Email Webhooks

    master

    OpenTrashmail allows you to trigger webhooks for specific email addresses. You can configure them via the Web UI or the API.

    Webhook Features

    • Custom Endpoints: Unique URL per email address.
    • Payload Templates: Use placeholders to customize the JSON sent to your server.
    • Retries: Automatic exponential backoff (up to 10 attempts).
    • Security: HMAC-SHA256 signatures using a secret_key.

    Payload Template Placeholders

    PlaceholderDescriptionExample
    {{to}}Recipient emailtest@example.com
    {{from}}Sender emailsender@domain.com
    {{subject}}Email subjectHello World
    {{body}}Plain text bodyEmail content...
    {{htmlbody}}HTML body<p>Email content...</p>
    {{sender_ip}}Sender's IP192.168.1.100
    {{attachments}}Attachment array[{"filename":"doc.pdf","size":1024}]

    Important: {{attachments}} outputs a JSON array; do not wrap it in quotes in your template.

    Example Template

    {
  "email": "{{to}}",
  "from": "{{from}}",
  "subject": "{{subject}}",
  "body": "{{body}}",
  "attachments": {{attachments}}
}
    {
  "email": "{{to}}",
  "from": "{{from}}",
  "subject": "{{subject}}",
  "body": "{{body}}",
  "attachments": {{attachments}}
}

  4. Run the Mailserver using Docker

    master

    Since the mailserver requires Python 2, it is recommended to run it via Docker. This command builds the image and runs a container that binds to port 2525 on your host machine. It also mounts your local data, logs, and config.ini files so that received emails are persisted to your local filesystem.

    Important: If you modify config.ini, you must restart the mailserver container for changes to take effect.

    docker build -f docker/Dockerfile -t opentrashmail .
docker run --rm -it --name trashmail -p 2525:25 \
-v $( pwd )/data:/var/www/opentrashmail/data \
-v $( pwd )/logs:/var/www/opentrashmail/logs \
-v $( pwd )/config.ini:/var/www/opentrashmail/config.ini:ro opentrashmail

  5. Run OpenTrashmail via Docker

    master

    OpenTrashmail is best run using Docker. Below are common deployment patterns.

    Simple Start (No Persistence)

    Runs the container with ports 25 (SMTP) and 80 (HTTP) exposed, without saving data across restarts.

    docker run -it -p 25:25 -p 80:80 -e URL="https://localhost:80" hascheksolutions/opentrashmail:1

    Persistent Storage

    Mount a host directory to /var/www/opentrashmail/data to ensure emails and configurations are saved.

    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

    Production-ready Daemon Mode

    A complete example including:

    • Running in background (-d)
    • Auto-restart (--restart=unless-stopped)
    • Domain restriction (DOMAINS)
    • Date formatting (DATEFORMAT)
    • Discarding unknown domains (DISCARD_UNKNOWN)
    • Automatic cleanup of old mail (DELETE_OLDER_THAN_DAYS)
    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
    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

  6. Run the Web UI locally

    master

    To test the OpenTrashmail Web UI, you must have PHP installed. Navigate to the web/ directory and start the built-in PHP server.

    Note: Because OpenTrashmail is database-less, the UI will load immediately, but you will not receive any emails unless the Python SMTP server (Mailserver) is also running.

    cd web
php -S localhost:8080 index.php

  7. Configure MX Records for OpenTrashmail

    master

    To receive emails, you must point your domain's MX records to the IP address of the server hosting OpenTrashmail. You can set up a standard domain or a wildcard domain to support any subdomain.

    Standard Domain Example

    To allow emails to be sent to example.com:

    mail.example.com.    IN    A        93.184.216.34
example.com.         14400  IN      MX      10      mail.example.com.

    Wildcard Domain Example

    To allow any subdomain (e.g., test@robot.example.com) to work, use a wildcard MX record in combination with the DOMAINS configuration option:

    mail.example.com.    IN    A        93.184.216.34
*.example.com.       14400  IN      MX      10      mail.example.com.

    When using a wildcard, ensure you set the Docker environment variable DOMAINS="*.example.com".

    mail.example.com.    IN    A        93.184.216.34
*.example.com.    14400   IN      MX      10      mail.example.com.

  8. Access control via ALLOWED_IPS

    master
    If the ALLOWED_IPS setting is configured, OpenTrashmail restricts access to specific IP ranges. The application retrieves the user's IP using getUserIP() and validates it against the allowed list using isIPInRange(). If the IP is not in the allowed range, the application terminates with the message: Your IP ([IP_ADDRESS]) is not allowed to access this site.

  9. Configure Open Trashmail via config.ini

    master

    You can configure the server by editing config.ini. Key settings include:

    • URL: The URL for the GUI (no trailing slash, e.g., https://trashmail.mydomain.eu).
    • DOMAINS: Comma-separated list of domains for receiving emails (used for random address generation).
    • MAILPORT: SMTP server port (Default: 25).
    • ADMIN: A valid email address that acts as a catch-all to view all emails on the server.
    • PASSWORD: If set, requires password in POST/GET or PWD in HTTP header for API/Web access.
    • ALLOWED_IPS: Comma-separated list of IPv4/IPv6 CIDR addresses allowed to use the UI/API.
    • ATTACHMENTS_MAX_SIZE: Max size for individual attachments in Bytes.
    • MAILPORT_TLS: Port for TLS on Connect (TLSC). Usually 465. Requires TLS_CERTIFICATE and TLS_PRIVATE_KEY.
    • TLS_CERTIFICATE: Path to the certificate chain.
    • TLS_PRIVATE_KEY: Path to the private key.
    • WEBHOOK_URL: Global webhook URL for POSTing email JSON data.
    • ADMIN_ENABLED: Enables the admin menu (Default: false).
    • ADMIN_PASSWORD: Password required to access the admin menu.

  10. Authentication methods for OpenTrashmail

    master

    OpenTrashmail supports several ways to authenticate when a PASSWORD is configured in the settings. The application checks for credentials in the following order:

    1. HTTP Header: The HTTP_PWD server variable.
    2. Request Parameters: A password variable provided via GET or POST requests.
    3. Session: An existing $_SESSION['authenticated'] flag.

    If authentication fails, the application renders the password.html template. If a wrong password is provided via request parameters, an error message is displayed.

  11. Routing and API endpoint structure

    master

    The application uses the URL path to determine how to handle requests. The path is parsed from $_SERVER['REQUEST_URI'].

    Key routing behaviors:

    • API/RSS/JSON: Requests starting with api, rss, or json are routed to the backend logic.
    • HTMX Requests: If the HTTP_HX_REQUEST header is set to 'true' and the path is exactly /api, the application renders the intro.html template.
    • Static/Template Fallback: If the requested path does not exist as a file and is not a reserved prefix (api, rss, json), the application renders the index.html template, passing the current url and settings to the view.

  12. Configure Open Trashmail via Docker environment variables

    master

    When running in Docker, use the following environment variables to configure the instance:

    | 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](https://momentjs.com/) 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` | `yourstrongpassword` |
| `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 |
| `MAILPORT_TLS` | If set to something higher than 0, this port will be used for TLSC (TLS on Connect). Which means plaintext auth will not be possible. Usually set to `465`. Needs `TLS_CERTIFICATE` and `TLS_PRIVATE_KEY` to work | `465` |
| `TLS_CERTIFICATE` | Path to the certificate (chain). Can be relative to the /python directory or absolute | `/certs/cert.pem` or `cert.pem` if it's inside the python directory |
| `TLS_PRIVATE_KEY` | Path to the private key of the certificate. Can be relative to the /python directory or absolute | `/certs/privkey.pem` or `key.pem` if it's inside the python directory |
| `WEBHOOK_URL` | If set, will send a POST request to this URL with the JSON data of the email as body. Can be used to integrate OpenTrashmail in your own projects | `https://example.com/webhook` |
| `ADMIN_ENABLED` | Enables the admin menu. Default `false` | `false` / `true` |
| `ADMIN_PASSWORD` | If set, needs this password to access the admin menu | `123456` |