VaultSandbox: Zero‑Trust In‑VPC Email Testing for Production‑Parity CI

VaultSandbox offers a production‑grade email testing environment that runs entirely inside your VPC, yet exposes every authentication and transport check you face in live deployments. --- ## The Problem *Mocks hide the exact email failures that break production* In many projects the email client is mocked to keep CI fast and flaky tests minimal. The mock often skips critical transport validation – TLS negotiation, DNS MX lookup, and SPF/DKIM/DMARC signatures – and may even disable certificate checks (`rejectUnauthorized: false`). As a result, a build that passes in CI may bounce in production, or worse, leak customer data when sent to a public SaaS inbox. Typical pitfalls: - "Works on My Machine" shortcuts: fake SMTP that does not enforce TLS, MX records, or real DNS. - Polling and `sleep()` constructs that produce flaky pipelines. - Public cloud tools that expose test data to third‑party services. - Authentication failures that surface only when real domains are used. - Rendering differences between plain‑text viewers and modern HTML clients. --- ## The Solution – VaultSandbox VaultSandbox removes blind spots by letting CI and QA run against a sandbox that behaves exactly like a real SMTP gateway. You keep your production provider (Postmark, SendGrid, SES, Resend, etc.) and simply change the recipient to a sandbox address. Email is sent over real TLS, the DNS stack is fully validated, and authentication checks (SPF, DKIM, DMARC, rDNS) are performed on every message. Key benefits: - **Zero risk to customer data** – encrypted in‑memory storage, no persistent logs. - **True isolation** – inbound mail is hard‑blocked once it leaves the container. - **Deterministic CI** – no polling or `sleep()`, thanks to server‑side SSE and automatic cleanup. - **Data sovereignty** – all traffic remains inside your VPC. - **Compliance‑ready** – optional enterprise controls such as SSO, audit logs, and retention. --- ## Architecture Overview ### Prerequisites - Public IP address. - Ports 25, 80, 443 open to the Internet. - Either a fully‑managed domain name with A and MX records pointing to the container’s IP, or use the zero‑config `vsx.email` subdomain (your IP is encoded in the host). Subdomains are supported. ### Auto‑Provisioning - ACME (Let’s Encrypt) certificates for SMTP (STARTTLS) and HTTPS are generated automatically. - DNS, SPF, DKIM, DMARC, and rDNS checks run on every injected email. ### Storage & Security - Emails never reach disk; they are encrypted in‑memory on receipt. - Private keys are generated locally and never leave the client. - The server cannot decrypt email even if compromised – a true zero‑knowledge architecture. --- ## Use Cases 1. **Signup Flow Testing** – A tester creates a sandbox address, signs up, and verifies the confirmation email without exposing real credentials. 2. **Password‑Reset Integration** – CI triggers a real password‑reset via Postmark, vaultsandbox receives and extracts the link, and the test “clicks” it for an end‑to‑end verification. 3. **DKIM/SPF Rotation Checks** – After rotating keys, a single test email is sent to the sandbox and validity is verified instantly. 4. **Rendering Tests** – HTML emails are parsed for MIME boundaries, attachments, and structural correctness before rendering. --- ## Deployment – One‑Line Docker‑Compose ```yaml services: vaultsandbox: image: vaultsandbox/gateway:latest ports: - "25:25" - "80:80" - "443:443" environment: VSB_VSX_DNS_ENABLED: 'true' # Auto‑provision TLS & Domain volumes: - vsb_data:/app/data volumes: vsb_data: ``` **Why this works** – The container binds to SMTP, HTTP, and HTTPS, auto‑installs Let’s Encrypt certs, and exposes a simple HTTP API for inbox management. --- ## Roadmap 1. **Phase 1 – Core Foundation** – Complete API, SDKs (Java, .NET, Go, Python, Node), 100% test coverage, and full documentation. 2. **Phase 2 – Enterprise Control Plane** – SSO via OIDC/SAML, audit logs, data retention policies, and enterprise‑grade deployment options. 3. **Phase 3 – Feature Extensions** – Rate limiting, inbound filtering, integration hooks, and optional hard‑mode blocking. --- ## Frequently Asked Questions - **Do I need a dedicated public IP?** Yes – ports 80, 443 for ACME, and 25 for inbound SMTP. - **Is the core gateway free?** The AGPLv3 core is open‑source and has no limits. Only optional enterprise features (SSO, audit) come at a cost. - **What about spam?** The SMTP server rejects non‑configured domains, validates RCPT TO against existing inboxes, and enforces per‑IP rate limits. - **What happens on container restart?** In‑memory emails are cleared; configuration, API keys, and certificates persist. - **Can I use the REST API directly?** Absolutely; SDKs wrap the API and automate key generation and decryption. --- ## Get Started Spin up VaultSandbox in minutes with Docker Compose, point your transactional email provider to a sandbox address, and run your CI pipeline against real SMTP. Stop guessing whether your emails will land – the only blind spot left is yourself. --- **Stay in the loop** – Subscribe to our newsletter for product updates, security releases, and deep dives on building production‑grade email testing inside your VPC.