<picture> <source media="(prefers-color-scheme: dark)" srcset="./docs/images/logo-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="./docs/images/logo-light.svg"> <img alt="Project Logo" src="./docs/images/logo-dark.svg"> </picture>

VaultSandbox is in Public Beta. Join the journey to 1.0. Share feedback on GitHub.

Gateway

VaultSandbox is a self-hosted SMTP testing gateway designed to replicate production email behavior—including TLS, DNS, authentication, and spam scoring—so your email tests reflect real-world conditions.

This repository contains the Gateway: the core backend service and web interface for receiving, validating, and inspecting test emails.

🎯 Key Features

• Zero-Config Setup: 1 env var (VSX DNS) or 2 env vars (custom domain)
• Production-Ready SMTP: Receive-only server on port 25 with automatic TLS
• Email Authentication: Full SPF, DKIM, DMARC, and reverse DNS validation
• Automatic Certificates: Let's Encrypt integration with hot-reload
• Web Interface: Modern Angular UI at /app endpoint
• Configurable Retention: Defaults to 7 days (easily adjusted)
• Multi-Node Support: Optional distributed coordination for clusters
• Encryption: Secure in-memory storage
• Spam Analysis: SpamAssassin-style scoring and detection
• Webhooks: HTTP notifications for email events
• Chaos Engineering: Test email pipeline resilience
• Persistence: Optional inbox and webhook persistence with automatic restoration on startup

📦 Monorepo Components

This repository is a monorepo containing two main components:

• /backend: A NestJS-based backend application providing:

  • Receive-only SMTP server with SPF/DKIM/DMARC validation
  • REST API for email access with auto-generated API keys
  • Automatic Let's Encrypt TLS certificate management
  • Optional quantum-safe encryption for backend forwarding
  • Health monitoring and metrics endpoints

  👉 Read the Backend Documentation

• /frontend: An Angular-based single-page application providing:

  • Email management
  • Visual display of authentication results (SPF, DKIM, DMARC)
  • Custom inbox management
  • Real-time updates via Server-Sent Events
  • Dark/light theme with automatic switching
  • Quantum-safe payload decryption

  👉 Read the Frontend Documentation

Quick Start

Option 1: VSX DNS (Recommended)

Zero-config setup with automatic DNS. No domain registration, no DNS configuration, no waiting for propagation. Your public IP is encoded into a subdomain (e.g., 1mzhr2y.vsx.email) that automatically resolves with proper MX records.

Requirement: Ports 25, 80, and 443 must be publicly reachable.

# docker-compose.yml
services:
  gateway:
    image: vaultsandbox/gateway:latest
    ports:
      - "25:25"   # SMTP
      - "80:80"   # HTTP (ACME + VSX verification)
      - "443:443" # HTTPS
    environment:
      - VSB_VSX_DNS_ENABLED=true
    volumes:
      - gateway-data:/app/data

volumes:
  gateway-data:

# Start the gateway
docker compose up -d

# Find your assigned domain
docker compose exec gateway cat /app/data/certificates/metadata.json; echo

# Retrieve auto-generated API key
docker compose exec gateway cat /app/data/.api-key; echo

You can also find your domain by entering your IP at vsx.email.

Total setup time: ~5 minutes

Option 2: Custom Domain

Use your own domain for branding, compliance, or existing infrastructure. Requires DNS configuration pointing to your server.

DNS Requirements: Before starting, configure these records:

• A record: qa.example.com → your server IP
• MX record: qa.example.com → qa.example.com (priority 10)

# docker-compose.yml
services:
  gateway:
    image: vaultsandbox/gateway:latest
    ports:
      - "25:25"   # SMTP
      - "80:80"   # HTTP (ACME challenge)
      - "443:443" # HTTPS
    environment:
      - VSB_SMTP_ALLOWED_RECIPIENT_DOMAINS=qa.example.com
      - VSB_CERT_ENABLED=true
    volumes:
      - gateway-data:/app/data

volumes:
  gateway-data:

# Start the gateway
docker compose up -d

# Retrieve auto-generated API key
docker compose exec gateway cat /app/data/.api-key; echo

What You Get (Public Deployment)

After starting the gateway, you have:

✅ SMTP server accepting emails on port 25 ✅ Automatic TLS certificates from Let's Encrypt ✅ Web UI at https://your-domain/app ✅ REST API with auto-generated API key ✅ 7-day email retention (configurable) ✅ Full email authentication validation (SPF, DKIM, DMARC)

Option 3: Local Development

# docker-compose.yml
services:
  vaultsandbox:
    image: vaultsandbox/gateway:latest
    ports:
      - '127.0.0.1:2525:25'
      - '127.0.0.1:8080:80'
    volumes:
      - vsb_data:/app/data

volumes:
  vsb_data:

docker compose up -d

# Retrieve auto-generated API key
docker compose exec vaultsandbox cat /app/data/.api-key; echo

What You Get (Local)

✅ SMTP server on localhost:2525 (no TLS) ✅ Web UI at http://localhost:8080/app ✅ REST API at http://localhost:8080/api ✅ 7-day email retention (configurable)

Development Environment Setup

# Clone the repository
git clone https://github.com/vaultsandbox/gateway.git
cd gateway

# Backend development
cd backend
npm install
cp template-env .env  # Configure your environment
npm run start:dev

# Frontend development (separate terminal)
cd frontend
npm install
npm start  # Runs on http://localhost:4200

Architecture

The gateway consists of two tightly integrated components:

Backend (NestJS)

• SMTP Module: Handles email reception and validation
• Certificate Module: Automatic Let's Encrypt certificate management
• Inbox Module: Local email storage with TTL
• Crypto Module: Quantum-safe encryption for backend mode
• API: RESTful endpoints for email access
• Static Serving: Serves the Angular frontend at /app

Frontend (Angular)

• Email Management: Browse received emails
• Authentication Display: Visual SPF/DKIM/DMARC results
• Custom Inboxes: Organize emails into virtual inboxes
• Real-Time Updates: SSE for instant notifications
• Metrics Dashboard: Monitor gateway health and performance

Integration Points

┌────────────────────────────────────────┐
│  Frontend (Angular)                    │
│  - Served at /app                      │
│  - API calls via /api                  │
│  - SSE at /api/inbox/sse               │
└──────────────┬─────────────────────────┘
               │
               │ HTTP(S)
               │
┌──────────────▼─────────────────────────┐
│  Backend (NestJS)                      │
│  ┌─────────────────────────────────┐   │
│  │ Static Files (@nestjs/serve)    │   │
│  │ /app → frontend/dist/browser    │   │
│  └─────────────────────────────────┘   │
│  ┌─────────────────────────────────┐   │
│  │ REST API                        │   │
│  │ /api/inbox, /api/emails, etc    │   │
│  └─────────────────────────────────┘   │
│  ┌─────────────────────────────────┐   │
│  │ SMTP Server (port 25)           │   │
│  │ SPF/DKIM/DMARC validation       │   │
│  └─────────────────────────────────┘   │
│  ┌─────────────────────────────────┐   │
│  │ Certificate Management          │   │
│  │ Let's Encrypt ACME              │   │
│  └─────────────────────────────────┘   │
└────────────────────────────────────────┘

Development

Backend Development

cd backend
npm run start:dev        # Hot reload
npm run build:all        # Build backend + frontend
npm run test             # Unit tests
npm run lint             # ESLint

Full Backend Documentation →

Frontend Development

cd frontend
npm start                # Dev server (port 4200)
npm run build           # Production build
npm test                # Unit tests
npm run lint            # ESLint

Full Frontend Documentation →

Documentation

• Backend README: Complete backend documentation

  • Configuration options
  • SMTP server setup
  • Certificate management
  • Clustering and orchestration
  • API endpoints

• Frontend README: Complete frontend documentation

  • Component architecture
  • State management
  • Email authentication display
  • Quantum-safe encryption
  • Styling and theming

• Contributing Guide: Development setup and contribution guidelines

• Code of Conduct: Community guidelines

• Security Policy: Vulnerability reporting and security practices

• Changelog: Version history and release notes

• Design Philosophy: Our open source philosophy and architecture decisions

License

This project is licensed under the Apache License 2.0.

Code of Conduct

All contributors are expected to adhere to our Code of Conduct. Please ensure you are familiar with its contents.

Support

• Documentation
• Issue Tracker
• Discussions
• Website