OpenTrashmail

OpenTrashmail is a lightweight, self‑hosted email interception service that exposes its functionality through a web UI, RSS feeds, and a REST‑style JSON API. Built with modern PHP 8.1+ for the web layer and a Python mail server that automatically accepts any domain, it eliminates the need for pre‑configured mailbox accounts. The entire state is stored in a flat‑file hierarchy—no relational or NoSQL database required—which simplifies deployment and reduces operational overhead. The application is distributed as a ready‑to‑run Docker image (hascheksolutions/opentrashmail) and can also be run directly from source, making it ideal for rapid prototyping or production use on a single server.

Technical Stack

• Backend: PHP 8.1 (Slim‑like micro framework, powered by HTMX for partial page updates), Python 3.11 (mail server handling SMTP/STARTTLS/TLS‑on‑connect).
• Storage: File system only. Each mailbox is a directory containing email_{id}.eml, metadata.json, and an optional attachments/ folder. This design avoids schema migrations and allows simple backup via tar or rsync.
• Containerization: A single‑service Dockerfile exposes ports 80 (HTTP) and 25/587 (SMTP). The image is ~200 MB, with automatic rebuilds triggered by GitHub Actions.
• Licensing: Apache 2.0, encouraging commercial use without license fees.

Core Capabilities

• Dynamic Addressing: Any RFC‑5322 address is accepted; no pre‑creation needed. The server auto‑creates the mailbox directory on first receipt.
• API Surface:
  • GET /rss/{email} – RSS feed per address, enabling mail‑to‑RSS clients.
  • GET /api/raw/{email}/{id} – Raw RFC‑822 email, useful for parsing or forwarding.
  • GET /api/attachment/{email}/{id} – Direct attachment download.
  • Webhooks: configurable per‑address, emitting JSON payloads that include headers, body, and attachment metadata.
• Web UI: HTMX‑driven, includes dark/light mode, random address generator, attachment downloads, and an admin view that lists all mailboxes.
• Security: Supports plain SMTP, STARTTLS, and TLS‑on‑connect. No authentication required for receipt; optional relay restrictions can be added via host‑level firewall rules.

Deployment & Infrastructure

The minimal footprint means a single VPS (e.g., 1 vCPU, 2 GB RAM) is sufficient for hundreds of concurrent mailboxes. Because the data layer is file‑based, scaling horizontally requires a shared filesystem (NFS or cloud object store with FUSE) or a stateful load balancer that preserves sticky sessions. Docker Compose can spin up the service alongside an SMTP relay like Postfix for outbound mail, while Kubernetes users may deploy it as a stateless pod with an attached PersistentVolumeClaim.

Integration & Extensibility

• Webhook Customization: Developers can define per‑address JSON payloads, filter headers, and trigger downstream services (e.g., Slack, Zapier).
• Plugin Hooks: The Python mail server exposes a mail_received callback that can be overridden to inject custom logic (e.g., spam scoring, auto‑reply).
• API Consumption: The JSON endpoints are stateless and cacheable; clients can integrate them into CI pipelines to consume 2FA emails or monitor honeypot activity.
• Extensible UI: HTMX allows developers to replace or augment components without a full SPA rewrite.

Developer Experience

• Documentation: The README provides concise API examples, and the codebase is heavily commented. The Dockerfile and GitHub Actions workflows serve as a reference for CI/CD integration.
• Community & Support: The project is active on GitHub, with frequent releases and a permissive license that removes licensing friction for commercial projects.
• Testing: Unit tests cover the API endpoints and webhook logic; integration tests simulate SMTP delivery, ensuring reliability.

Use Cases

1. Two‑Factor Authentication (2FA) Automation – Capture 2FA emails via the JSON API and feed them into an MFA workflow without exposing a real inbox.
2. Email Honeypot – Deploy on a public domain to attract spam or phishing attempts; analyze payloads via the RSS feed or webhook system.
3. Temporary Mailboxes – Provide disposable addresses for developers testing email integrations, with instant attachment download and log access.
4. Service‑to‑Service Communication – Use the webhook system to trigger microservices on inbound mail events, enabling event‑driven architectures.

Advantages Over Alternatives

• Zero‑Database: Eliminates database maintenance, migrations, and complex backups.
• All‑in‑One Package: Combines SMTP server, web UI, API, and RSS in a single container.
• High Flexibility: Dynamic address handling removes the need for account provisioning scripts.
• Open Source & License Friendly: Apache 2.0 allows unrestricted commercial use and modification.
• Performance: Python’s async SMTP handling paired with PHP’s HTMX UI keeps latency low, even under moderate load.

OpenTrashmail offers a developer‑centric, opinionated solution for capturing and processing inbound emails with minimal operational friction, making it a compelling choice for projects that need disposable mailboxes, automated 2FA handling, or email