vaultsandbox/gateway repository overview

⁠VaultSandbox 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.

Supported Architectures: amd64, arm64

⁠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)
• Encryption: Secure in-memory storage
• Spam Analysis⁠: scoring and detection
• Webhooks⁠: HTTP notifications for email events
• Chaos Engineering⁠: Test email pipeline resilience

⁠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.

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)

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

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

⁠Option 3: Local Development

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

⁠What You Get (Public Deployment)

• 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)

⁠Configuration

⁠Environment Variables

⁠VSX DNS Mode

⁠Custom Domain Mode

⁠Ports

• 25 (SMTP): Receive inbound email.
• 80 (HTTP): ACME certificate issuance (Let's Encrypt).
• 443 (HTTPS): Secure API and UI access.

⁠Documentation & Support

• Website: vaultsandbox.com⁠
• Documentation: vaultsandbox.dev⁠
• Source: github.com/vaultsandbox/gateway⁠

License: Apache License 2.0⁠