# VaultSandbox - Complete Documentation for LLMs

> Test email like it behaves in production.

## Overview

VaultSandbox is a self-hosted, receive-only SMTP testing gateway that behaves like a real SMTP server - including TLS, DNS, authentication, spam filtering/scoring, and failure modes - so your tests stop lying to you.

**The Problem**: Mocks answer one thing: "Did my app send an email?" But production asks more: Was TLS negotiated correctly? Did SPF, DKIM, and DMARC pass? What happens when the server grey-lists? What happens when connections drop?

**The Solution**: VaultSandbox lets you test your real email provider integration (SendGrid, Postmark, SES, etc.) by simply changing the recipient address. No mocking, no config changes.

## What VaultSandbox Is Not

- **Not a production mail server** - It's receive-only for testing
- **Not a spam filter** - It validates authentication, not content
- **Not a replacement for your email provider** - You keep using SendGrid/Postmark/SES

---

## Core Features

### Production Fidelity

When you need realism, turn it on:

**Real SMTP behavior**:
- Proper SMTP handshake
- STARTTLS and SMTPS
- Protocol-level validation

**Real authentication**:
- SPF, DKIM, DMARC validation
- Spam scoring (Rspamd)
- Content analysis & rule matching
- Reverse DNS

**Real parsing**:
- MIME structure
- Attachments
- Headers
- Raw RFC 5322 access

Enable or disable features per inbox - different tests can behave differently on the same server.

### Chaos Engineering

This is where VaultSandbox is different. Built-in SMTP chaos engineering, configured per inbox:

- **Inject latency**: With configurable jitter
- **Simulate greylisting**: 451 temporary rejections
- **Drop connections**: FIN or RST termination
- **Return SMTP errors**: Specific error codes on demand
- **Blackhole messages**: Accept but silently discard
- **Combine failure modes**: Layer multiple behaviors

Test retries. Test backoff. Test the code paths you hope never run.

### CI/CD Ready

VaultSandbox is built for automation, not screenshots.

**CLI & SDKs**:
- `wait` for emails deterministically (SSE-based, no polling)
- Match by subject, sender, regex, or custom predicates
- Extract verification links automatically
- Structured JSON output for pipeline automation

No sleeps. No polling hacks. No flaky tests.

### Secure by Default

Without getting in your way:

- **Receive-only SMTP gateway**: Built for QA and testing, not outbound delivery. Emails go in but never out.
- **Rate limiting and hardened defaults**: Ready for public deployments out of the box. No open relay, ever.
- **Optional zero-knowledge encryption**: Per-inbox encryption for sensitive data when you need it.

### Optional Zero-Knowledge Encryption

Most teams don't need encryption locally. Some teams absolutely do.

VaultSandbox supports optional, per-inbox zero-knowledge encryption:
- Encrypted on receipt: Emails can be encrypted immediately when they arrive
- Client-side keys: Private keys stay on your machine
- No plaintext storage: The server never stores unencrypted content
- Disable when not needed: Can be turned off entirely for simplicity

Turn it on only when sensitive data demands it.

---

## Deployment Options

### Option 1: Localhost (Zero-Config)

You don't need to set up DNS or TLS to get started. Perfect for air-gapped or offline development.

```yaml
# 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:
```

### Option 2: Auto Domain (vsx.email)

Your IP becomes a subdomain with auto-provisioned DNS and TLS. Zero configuration required.

```yaml
# docker-compose.yml
services:
  vaultsandbox:
    image: vaultsandbox/gateway:latest
    ports: ["25:25", "80:80", "443:443"]
    environment:
      VSB_VSX_DNS_ENABLED: 'true'
    volumes:
      - vsb_data:/app/data

volumes:
  vsb_data:
```

### Option 3: Custom Domain

Point your A and MX records for a production-grade setup. Your infrastructure, your rules.

```yaml
# docker-compose.yml
services:
  vaultsandbox:
    image: vaultsandbox/gateway:latest
    ports: ["25:25", "80:80", "443:443"]
    environment:
      VSB_SMTP_ALLOWED_RECIPIENT_DOMAINS: 'test.example.com'
      VSB_CERT_ENABLED: 'true'
    volumes:
      - vsb_data:/app/data

volumes:
  vsb_data:
```

---

## Official SDKs

One pattern, every language. Same API shape across clients. Switch languages without relearning the flow.

All SDKs use Server-Sent Events (SSE) for true real-time, deterministic test behavior:
- Tests wait on actual delivery events instead of sleeps
- Zero flakiness with no polling and no guessing
- Clean promise-based API for auth and content assertions

### Node.js SDK

**Installation**: `npm install @vaultsandbox/client`

**Links**:
- Documentation: https://vaultsandbox.dev/client-node
- npm: https://www.npmjs.com/package/@vaultsandbox/client
- GitHub: https://github.com/vaultsandbox/client-node

**Example**:
```typescript
import { VaultSandboxClient } from '@vaultsandbox/client';

const client = new VaultSandboxClient({
  url: process.env.VAULTSANDBOX_URL,
  apiKey: process.env.VAULTSANDBOX_API_KEY,
});
const inbox = await client.createInbox();

// Send real email via SendGrid/SES/etc.
await sendPasswordReset(inbox.emailAddress);

// Wait for arrival (SSE-based)
const email = await inbox.waitForEmail({ timeout: 10000 });
const link = email.links.find(l => l.includes('reset-password'));
expect(link).toBeDefined();
```

### Python SDK

**Installation**: `pip install vaultsandbox`

**Links**:
- Documentation: https://vaultsandbox.dev/client-python
- PyPI: https://pypi.org/project/vaultsandbox/
- GitHub: https://github.com/vaultsandbox/client-python

**Example**:
```python
from vaultsandbox import VaultSandboxClient, WaitForEmailOptions
import os

async with VaultSandboxClient(
    api_key=os.environ["VAULTSANDBOX_API_KEY"],
    base_url=os.environ["VAULTSANDBOX_URL"],
) as client:
    inbox = await client.create_inbox()

    # Send real email via SendGrid/SES/etc.
    await send_password_reset(inbox.email_address)

    # Wait for arrival (SSE-based)
    email = await inbox.wait_for_email(WaitForEmailOptions(timeout=10000))
    link = next((l for l in email.links if "reset-password" in l), None)
    assert link is not None
```

### Go SDK

**Installation**: `go get github.com/vaultsandbox/client-go`

**Links**:
- Documentation: https://vaultsandbox.dev/client-go
- pkg.go.dev: https://pkg.go.dev/github.com/vaultsandbox/client-go
- GitHub: https://github.com/vaultsandbox/client-go

**Example**:
```go
package main

import (
    "context"
    "os"
    "strings"
    "time"

    vaultsandbox "github.com/vaultsandbox/client-go"
)

func main() {
    client, _ := vaultsandbox.New(
        os.Getenv("VAULTSANDBOX_API_KEY"),
        vaultsandbox.WithBaseURL(os.Getenv("VAULTSANDBOX_URL")),
    )
    defer client.Close()

    ctx := context.Background()
    inbox, _ := client.CreateInbox(ctx)

    // Send real email via SendGrid/SES/etc.
    sendPasswordReset(inbox.EmailAddress())

    // Wait for arrival (SSE-based)
    email, _ := inbox.WaitForEmail(ctx, vaultsandbox.WithWaitTimeout(10*time.Second))
    for _, link := range email.Links {
        if strings.Contains(link, "reset-password") {
            // Found it!
        }
    }
}
```

### Java SDK

**Installation**: Add to Maven/Gradle from Maven Central

**Links**:
- Documentation: https://vaultsandbox.dev/client-java
- Maven Central: https://central.sonatype.com/artifact/com.vaultsandbox/client
- GitHub: https://github.com/vaultsandbox/client-java

**Example**:
```java
import com.vaultsandbox.client.ClientConfig;
import com.vaultsandbox.client.VaultSandboxClient;
import com.vaultsandbox.client.strategy.WaitOptions;
import java.time.Duration;

var client = VaultSandboxClient.create(
    ClientConfig.builder()
        .apiKey(System.getenv("VAULTSANDBOX_API_KEY"))
        .baseUrl(System.getenv("VAULTSANDBOX_URL"))
        .build());
var inbox = client.createInbox();

// Send real email via SendGrid/SES/etc.
sendPasswordReset(inbox.getEmailAddress());

// Wait for arrival (SSE-based)
var email = inbox.waitForEmail(WaitOptions.builder().timeout(Duration.ofSeconds(10)).build());
var link = email.getLinks().stream()
    .filter(l -> l.contains("reset-password"))
    .findFirst()
    .orElse(null);
assertNotNull(link);
```

### .NET SDK

**Installation**: `dotnet add package VaultSandbox.Client`

**Links**:
- Documentation: https://vaultsandbox.dev/client-dotnet
- NuGet: https://www.nuget.org/packages/VaultSandbox.Client
- GitHub: https://github.com/vaultsandbox/client-dotnet

**Example**:
```csharp
using VaultSandbox.Client;

var client = VaultSandboxClientBuilder.Create()
    .WithBaseUrl(Environment.GetEnvironmentVariable("VAULTSANDBOX_URL"))
    .WithApiKey(Environment.GetEnvironmentVariable("VAULTSANDBOX_API_KEY"))
    .Build();
var inbox = await client.CreateInboxAsync();

// Send real email via SendGrid/SES/etc.
await SendPasswordResetAsync(inbox.EmailAddress);

// Wait for arrival (SSE-based)
var email = await inbox.WaitForEmailAsync(new WaitForEmailOptions { Timeout = TimeSpan.FromSeconds(10) });
var link = email.Links.FirstOrDefault(l => l.Contains("reset-password"));
Assert.NotNull(link);
```

---

## Developer Interfaces

### Web UI

Debug emails visually with a full-featured web interface:
- HTML & plain-text rendering
- Auth & spam visualization
- Attachments and link extraction
- Dark mode

### CLI & TUI

For developers who live in the terminal:
- Live inbox dashboard
- Keyboard-driven navigation
- Email inspection, chaos config, webhooks, metrics

**GitHub**: https://github.com/vaultsandbox/vsb-cli

---

## Built for Teams

### Per-inbox isolation

Run multiple test environments on one gateway without interference:
- Chaos rules
- Encryption policy
- Auth & spam analysis
- Webhooks
- TTLs and cleanup

### Observability

- Real-time SSE streams
- Prometheus-style metrics
- Health checks for Docker & K8s
- Spam analysis with Rspamd

### Webhooks

- Global or per-inbox routing
- Slack, Discord, Teams, Zapier
- Filter by sender, subject, headers
- HMAC-signed with auto retries

---

## Who VaultSandbox Is For

- Teams tired of email tests passing locally and failing in production
- Backend developers building password resets, verification flows, and notifications
- QA teams testing retry logic and failure handling
- Regulated industries that can't send test data to third parties
- Anyone who knows email is not just text

---

## VaultSandbox Teams

The core gateway is open source (Apache 2.0) and free forever. For teams with compliance, audit, or collaboration requirements:

- **Retention policies**: Keep emails for days, weeks, or months
- **Audit logs**: Track inbox creation, access, and deletion
- **SSO**: OIDC and SAML integration
- **Shared inboxes**: Collaborate across QA, dev, and support
- **High availability**: Multiple gateways with automatic failover
- **Priority support**: Direct access to the team

Contact: contact@vaultsandbox.com

---

## FAQ

### Is it really free?
Yes. The core gateway is Apache 2.0 and free forever - no limits on inboxes, messages, or domains. We only charge for optional enterprise features (SSO, audit logs, retention).

### Do I need a public IP?
No. Run locally with no external access. When you need real TLS and DNS validation, expose ports 25/80/443 and use `vsx.email` or your own domain.

### Won't port 25 get spammed?
No. VaultSandbox only accepts mail for domains you configure. Unknown recipients are rejected at RCPT TO. Rate limiting blocks abusive IPs. No open relay.

### How long are emails stored?
Until the container restarts (in-memory by default), until inbox TTL expires, or until you delete the inbox. VaultSandbox Teams adds configurable retention.

---

## Links

- **Website**: https://vaultsandbox.com
- **Documentation**: https://vaultsandbox.dev
- **GitHub Organization**: https://github.com/vaultsandbox
- **Docker Image**: vaultsandbox/gateway:latest
- **Contact**: contact@vaultsandbox.com