Home

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• blueprint.md
• deployment_guide.md
• services/api/src/routes/messages.ts
• services/web/src/pages/LandingPage.tsx
• services/api/package.json

The Email Platform, "TempMail Pro," is a self-hosted, multi-domain inbound email system designed for creating disposable or temporary inboxes. It is primarily intended for developers and teams to use for QA, testing, internal onboarding, and as a developer sandbox, mitigating the risks of using public temp-mail services. The platform focuses on receiving and viewing emails via a web UI and a comprehensive REST API, with optional capabilities for sending emails via a hybrid model (e.g., using Amazon SES or SendGrid).

The system is architected as a set of containerized microservices, making it easy to deploy and manage using Docker. It includes a full-featured backend API, an inbound SMTP server for receiving mail, a modern React-based web frontend, and integrated monitoring tools. The project is production-ready, with a live demo available at manhquy.click.

Sources: README.md:3-7, blueprint.md:5-13, 29-39

Architecture Overview

The platform is built on a modern technology stack, containerized with Docker for consistent deployment across development and production environments. The core components are designed to be scalable and maintainable.

Sources: README.md:18-25, blueprint.md:65-76

Technology Stack

Component	Technology	Purpose
Backend	Node.js, Fastify, Prisma	Serves the RESTful API, handles business logic, and manages database interactions.
Database	PostgreSQL, Redis	PostgreSQL for persistent data (users, domains, messages); Redis for job queues and caching.
SMTP Server	smtp-server, mailparser	Listens for inbound emails on port 25, parses them, and stores content.
Frontend	React 19, Vite, TailwindCSS	Provides a modern, responsive web interface for users to manage domains and view emails.
Reverse Proxy	Caddy	Manages incoming HTTP/S traffic, provides automatic SSL via Let's Encrypt.
Monitoring	Prometheus, Grafana	Collects and visualizes application metrics for observability.
Containerization	Docker Compose	Defines and runs the multi-container application services.

Sources: README.md:18-25, blueprint.md:16-24, 69-76, services/api/package.json:20-39

System Components Diagram

This diagram illustrates the high-level interaction between the system's main components.

Key Features

The platform offers a range of features designed for managing temporary email addresses efficiently and securely.

Feature	Description
Multi-Domain Support	Users can add and manage an unlimited number of their own custom domains.
Disposable Inboxes	Instantly create temporary email addresses under any verified domain.
Modern UI/UX	A responsive, glassmorphism-inspired interface built with React and TailwindCSS.
RESTful API	Provides full programmatic access to all features for automation and integration.
Admin Panel	A dedicated interface for managing users, viewing logs, and monitoring system statistics.
Real-time Delivery	Emails are received and displayed instantly in the web UI.
Docker Ready	Simplified one-command deployment using Docker Compose.
Abuse Controls	Includes rate limiting, quotas, and configurable block/allow rules to prevent misuse.
Data Retention	Automatic deletion of emails and inboxes after a configurable Time-to-Live (TTL).

Sources: README.md:9-16, blueprint.md:52-58, 86-92, services/web/src/pages/LandingPage.tsx:10-41

Data Model

The core data structure revolves around Users, Domains, Inboxes, and the Messages they receive. The blueprint.md file outlines a clear entity-relationship model for the system.

Sources: blueprint.md:162-177

ER Diagram

This diagram shows the relationships between the main database entities.

Core Workflows

Inbound Email Pipeline

The primary function of the platform is to receive emails. This process is handled by a dedicated pipeline.

1. An email is sent from the internet to an address like test@yourdomain.com.
2. The sender's mail server performs a DNS lookup for the MX record of yourdomain.com.
3. The MX record points to the IP address of the server hosting the Email Platform.
4. The email is delivered to the platform's Inbound SMTP Server (listening on port 25).
5. The SMTP server accepts the email and passes it to the Backend API for processing.
6. The API uses mailparser to parse the email's headers, body (text and HTML), and attachments.
7. The parsed message metadata is stored in the PostgreSQL database, and any attachments are saved to Disk or S3-compatible storage.
8. The new message appears in the user's inbox in the Web App.

This flow is visualized in the diagram below.

Message Management via API

The API provides several endpoints for managing messages, including listing, searching, reading, and deleting.

A common use case is fetching messages for a specific inbox. The GET /inboxes/:id/messages endpoint supports pagination, filtering, and searching.

// Example from services/api/src/routes/messages.ts
app.get("/inboxes/:id/messages", { preHandler: app.authenticate }, async (request, reply) => {
    // ... validation ...
    const where = {
      inboxId: inbox.id,
      deletedAt: null,
      ...(query.data.q
        ? {
          OR: [
            { subject: { contains: query.data.q, mode: "insensitive" as const } },
            { fromAddress: { contains: query.data.q, mode: "insensitive" as const } },
            // ... more filters
          ],
        }
        : {}),
      // ... other filters like isRead, hasAttachments, date ranges
    };

    const [messages, total] = await Promise.all([
      prisma.message.findMany({
        where,
        orderBy: { receivedAt: "desc" },
        take: query.data.limit ?? 50,
        skip: query.data.offset ?? 0,
        include: { attachments: { where: { deletedAt: null } } },
      }),
      prisma.message.count({ where }),
    ]);
    return { data: messages, meta: { total } };
});

This endpoint demonstrates the powerful filtering capabilities available through the API, allowing clients to build complex search queries.

Sources: services/api/src/routes/messages.ts:51-110