High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:The Email Platform is a self-hosted, multi-domain system designed for managing inbound emails through disposable or temporary inboxes. Its primary purpose is to allow users to add their own domains, create email aliases on the fly, and view received messages through a modern web interface. The architecture is centered around an inbound-only email pipeline, with optional hybrid capabilities for sending emails via third-party services.
The system is designed for developers and teams who need temporary inboxes for QA, testing, or service sign-ups without exposing their primary email addresses. It emphasizes ease of deployment through Docker, security, and automation via a RESTful API. The core non-goals include becoming a full-fledged email provider (like Gmail) or an open, public temp-mail service, due to the high risk of abuse.
Sources: blueprint.md:10-27, README.md:5-9
System Components
The platform is a containerized, multi-service application. The main components are orchestrated using Docker Compose. The architecture is split into a frontend, a backend API, an SMTP server for receiving mail, databases, and services for deployment and monitoring.
Sources: README.md:19-26, blueprint.md:100-110, deployment_guide.md:83-91
Component Diagram
This diagram shows the primary services and their interactions within the system.
Component Breakdown
| Component | Technology | Role |
|---|---|---|
| Web Frontend | React 19 + Vite + TailwindCSS | Provides the user interface for managing domains, inboxes, and viewing emails. It is a Single Page Application (SPA). |
| Backend API | Node.js + Fastify | The core of the application. Manages users, domains, inboxes, and messages. Provides a RESTful API for the frontend and handles business logic. |
| Inbound SMTP | smtp-server + mailparser | A Node.js-based SMTP server that listens for incoming emails, parses them, and forwards them to the API for processing and storage. |
| Database | PostgreSQL + Prisma | The primary data store for all persistent data, including users, domains, inboxes, and email metadata. |
| Cache / Queue | Redis + BullMQ | Used for caching and managing background jobs, such as email retention policies. |
| Reverse Proxy | Caddy | Manages incoming HTTP/S traffic, provides automatic SSL certificates via Let's Encrypt, and routes requests to the appropriate services. |
| Monitoring | Prometheus + Grafana | Collects metrics from the API (/metrics endpoint) and provides dashboards for system monitoring. |
| Attachment Storage | Local Disk / S3 (Optional) | Stores email attachments. The default is local disk, with S3 compatibility as an option. |
Sources: README.md:19-26, blueprint.md:101-109, services/api/package.json:28-48, services/web/package.json:16-26
Inbound Email Flow
The system is primarily designed to process inbound emails. The flow begins when an external mail server sends an email to a domain managed by the platform.
Sources: blueprint.md:94-99
This sequence diagram illustrates the journey of an email from an external sender to its storage within the platform.
Sources: blueprint.md:94-99, README.md:21, deployment_guide.md:14-18
Deployment Architecture
The application is designed for deployment using Docker Compose. A production-ready configuration is provided that includes automated HTTPS.
Sources: deployment_guide.md:78-100, blueprint.md:149-160
Production Setup
For production, the docker-compose.prod.yml file is used. It leverages Caddy as a reverse proxy to handle TLS termination and certificate management.
Key environment variables for production include:
DOMAIN: The primary domain for the service (e.g.,yourdomain.com).ACME_EMAIL: The email address for Let's Encrypt registration.POSTGRES_PASSWORD: A secure password for the database.OUTBOUND_SMTP_*: Credentials for an external SMTP relay service (e.g., Amazon SES, SendGrid) if outbound mail is enabled.
Sources: deployment_guide.md:81-95
DNS Configuration
Proper DNS setup is mandatory for the system to receive emails. The following records must be configured to point to the server's public IP address.
| Type | Host/Name | Value | Priority | Purpose |
|---|---|---|---|---|
| A | mail | <YOUR_SERVER_IP> | - | Points the mail server hostname to the VPS. |
| A | api | <YOUR_SERVER_IP> | - | Points the API subdomain to the VPS. |
| A | app | <YOUR_SERVER_IP> | - | Points the Web UI subdomain to the VPS. |
| MX | @ or yourdomain.com | mail.yourdomain.com | 10 | Directs email for the domain to your mail server. |
Sources: deployment_guide.md:12-18, blueprint.md:131-135
Data Model
The database schema is designed to support the multi-tenant nature of the platform, separating users, domains, inboxes, and messages.
Sources: blueprint.md:203-217
Entity Relationship Diagram
This ER diagram shows the proposed data model and the relationships between the core entities.
Sources: blueprint.md:203-217
Application Structure
Frontend (Web)
The frontend is a React application built with Vite. It uses react-router-dom for routing and lazy loading for performance. Key components like Dashboard and Admin are loaded on demand.
The main application routes are defined in services/web/src/App.tsx and are separated into public-facing pages (Landing, Login, Legal) and protected routes that require authentication, which are wrapped in the MainLayout.
Sources: services/web/src/App.tsx:13-52
Backend (API)
The backend is a Fastify server. It exposes several key API routes for managing the platform's resources. Authentication is handled via JWT, and a preHandler (app.authenticate) protects most routes.
Core API routes include:
- Authentication:
POST /auth/login - Domains:
GET /domains,POST /domains,POST /domains/:id/verify - Inboxes:
GET /inboxes,POST /inboxes - Messages:
GET /inboxes/:id/messages,GET /messages/:id,DELETE /messages/:id,GET /messages/:id/export - Attachments:
GET /attachments/:id/download - Observability:
GET /health,GET /metrics
The API includes features like pagination, search (q parameter), and filtering on many of its list endpoints. For example, the message listing endpoint supports filtering by query string, attachments, and read status.
Sources: README.md:52-58, services/api/src/routes/messages.ts:4-31
Conclusion
The high-level architecture of the Email Platform is a modern, container-based system optimized for self-hosting and managing inbound emails. It clearly separates concerns between the frontend UI, backend API, and the SMTP ingestion layer. By leveraging Docker and Caddy, it simplifies deployment and security. The focus on an inbound-only pipeline with optional outbound relays makes it a practical and less risky solution compared to building a full email provider from scratch.
Sources: blueprint.md:46-56, 149-152, README.md:5-9