### Manage Custom Domain Gateway Instance

Source: https://github.com/vaultsandbox/gateway/blob/main/README.md

Commands to start the gateway and retrieve the auto-generated API key for a custom domain setup.

```bash
# Start the gateway
docker compose up -d

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

--------------------------------

### Start Development with Remote Proxy

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Command to start the development server after configuring the proxy.

```bash
npm start
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Commands to clone the repository and install required Node.js packages.

```bash
# Clone the repository (if not already done)
git clone https://github.com/vaultsandbox/gateway.git
cd gateway/frontend

# Install dependencies
npm install
```

--------------------------------

### Start Development Servers

Source: https://github.com/vaultsandbox/gateway/blob/main/backend/README.md

Commands to launch the backend and frontend services with hot reloading enabled.

```bash
# Terminal 1: Backend with hot reload
cd backend
npm run start:dev

# Terminal 2: Frontend with hot reload
cd frontend
npm start
```

--------------------------------

### Start Gateway Backend in Development Mode

Source: https://github.com/vaultsandbox/gateway/blob/main/backend/README.md

Starts the backend server with hot-reloading for development. Access the web UI at http://localhost:80/app and health checks at http://localhost:80/health.

```bash
# Start backend in development mode (hot reload)
npm run start:dev
```

--------------------------------

### Install Gateway Backend Dependencies

Source: https://github.com/vaultsandbox/gateway/blob/main/backend/README.md

Installs the necessary Node.js dependencies for the Gateway backend. Ensure Node.js 18+ is installed.

```bash
cd gateway/backend
npm install
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/vaultsandbox/gateway/blob/main/README.md

Steps to clone the VaultSandbox gateway repository and install backend and frontend dependencies using npm. Includes configuring environment variables for the backend.

```bash
# 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
```

--------------------------------

### Start Standalone Development Server

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Command to launch the Angular development server with hot module replacement.

```bash
# Start Angular development server with hot reload
npm start

# Access the application
# - Web UI: http://localhost:4200
# - Proxy to backend: http://localhost:4200/api (configured in angular.json)
```

--------------------------------

### Start and Retrieve API Key with Docker Compose

Source: https://github.com/vaultsandbox/gateway/blob/main/README.md

Commands to start the gateway in detached mode using Docker Compose and retrieve the auto-generated API key from the container.

```bash
docker compose up -d

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

--------------------------------

### Gateway Management Commands

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Common CLI commands for starting the gateway, retrieving metadata, and viewing logs.

```bash
# Start the gateway
docker compose up -d

# Get your assigned domain (VSX DNS mode)
docker compose exec gateway cat /app/data/certificates/metadata.json | jq -r '.domain'

# Get your API key
docker compose exec gateway cat /app/data/.api-key

# View logs
docker compose logs -f gateway
```

--------------------------------

### Manage VSX DNS Gateway Instance

Source: https://github.com/vaultsandbox/gateway/blob/main/README.md

Commands to start the gateway and retrieve configuration details like the assigned domain and API key.

```bash
# 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
```

--------------------------------

### Frontend Development Commands

Source: https://github.com/vaultsandbox/gateway/blob/main/README.md

Common commands for frontend development, including starting the development server, building for production, running tests, and linting.

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

--------------------------------

### Run frontend development server

Source: https://github.com/vaultsandbox/gateway/blob/main/CONTRIBUTING.md

Starts the Angular frontend development server. The frontend will be accessible at http://localhost:4200.

```bash
npm run start
```

--------------------------------

### Backend Development Commands

Source: https://github.com/vaultsandbox/gateway/blob/main/README.md

Common commands for backend development, including starting with hot reload, building the project, running tests, and linting.

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

--------------------------------

### Get Metrics

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Returns real-time server metrics for monitoring purposes.

```APIDOC
## GET /api/metrics

### Description
Returns real-time server metrics including uptime, connection counts, email statistics, and certificate status. Useful for monitoring dashboards.

### Method
GET

### Endpoint
/api/metrics

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200 OK)
- **uptime** (integer) - Server uptime in seconds.
- **connections** (object) - Connection statistics.
  - **total** (integer) - Total number of connections.
  - **active** (integer) - Number of active connections.
  - **rejected** (integer) - Number of rejected connections.
- **emails** (object) - Email processing statistics.
  - **received** (integer) - Number of emails received.
  - **stored** (integer) - Number of emails stored.
  - **rejected** (integer) - Number of emails rejected.
- **auth** (object) - Authentication statistics.
  - **spf** (object) - SPF authentication results.
    - **pass** (integer) - SPF passes.
    - **fail** (integer) - SPF failures.
    - **none** (integer) - SPF no result.
  - **dkim** (object) - DKIM authentication results.
    - **pass** (integer) - DKIM passes.
    - **fail** (integer) - DKIM failures.
    - **none** (integer) - DKIM no result.
  - **dmarc** (object) - DMARC authentication results.
    - **pass** (integer) - DMARC passes.
    - **fail** (integer) - DMARC failures.
    - **none** (integer) - DMARC no result.
- **certificate** (object) - SSL certificate information.
  - **domain** (string) - The domain the certificate is for.
  - **expiresAt** (string) - The expiration date of the certificate.
  - **daysUntilExpiry** (integer) - Number of days until the certificate expires.

### Response Example
```json
{
  "uptime": 86400,
  "connections": {
    "total": 1500,
    "active": 3,
    "rejected": 12
  },
  "emails": {
    "received": 850,
    "stored": 845,
    "rejected": 5
  },
  "auth": {
    "spf": { "pass": 800, "fail": 45, "none": 5 },
    "dkim": { "pass": 750, "fail": 50, "none": 50 },
    "dmarc": { "pass": 700, "fail": 100, "none": 50 }
  },
  "certificate": {
    "domain": "your-domain.com",
    "expiresAt": "2024-04-15T00:00:00.000Z",
    "daysUntilExpiry": 90
  }
}
```
```

--------------------------------

### Get Metrics

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Retrieves real-time server performance data, including connection counts, email statistics, and authentication pass/fail rates.

```bash
# Get server metrics
curl -X GET "https://your-gateway.example.com/api/metrics" \
  -H "X-API-Key: your-api-key"

# Response (200 OK)
{
  "uptime": 86400,
  "connections": {
    "total": 1500,
    "active": 3,
    "rejected": 12
  },
  "emails": {
    "received": 850,
    "stored": 845,
    "rejected": 5
  },
  "auth": {
    "spf": { "pass": 800, "fail": 45, "none": 5 },
    "dkim": { "pass": 750, "fail": 50, "none": 50 },
    "dmarc": { "pass": 700, "fail": 100, "none": 50 }
  },
  "certificate": {
    "domain": "your-domain.com",
    "expiresAt": "2024-04-15T00:00:00.000Z",
    "daysUntilExpiry": 90
  }
}
```

--------------------------------

### API Response Examples

Source: https://context7.com/vaultsandbox/gateway/llms.txt

JSON response structures for valid and invalid link status checks.

```json
{
  "valid": true,
  "status": 200,
  "contentType": "text/html"
}
```

```json
{
  "valid": false,
  "status": 404,
  "contentType": null
}
```

--------------------------------

### Get Storage Metrics

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Provides statistics on email storage, memory usage, and eviction history.

```bash
# Get storage metrics
curl -X GET "https://your-gateway.example.com/api/metrics/storage" \
  -H "X-API-Key: your-api-key"

# Response (200 OK)
{
  "inboxCount": 25,
  "emailCount": 450,
  "memoryUsage": {
    "heapUsed": 125829120,
    "heapTotal": 268435456
  },
  "evictions": {
    "ttlExpired": 150,
    "manualDelete": 45
  }
}
```

--------------------------------

### Get Webhook Templates

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Fetches a list of available built-in webhook templates.

```APIDOC
## GET /api/webhooks/templates

### Description
Returns available built-in webhook templates with their payload formats.

### Method
GET

### Endpoint
/api/webhooks/templates

### Response
#### Success Response (200 OK)
- **templates** (array of strings) - A list of available template names.

#### Response Example
```json
{
  "templates": ["slack", "discord", "teams", "zapier", "default"]
}
```
```

--------------------------------

### Configure Gateway with VSX DNS

Source: https://github.com/vaultsandbox/gateway/blob/main/README.md

Use the VSX DNS option for zero-config setup. Requires ports 25, 80, and 443 to be publicly reachable.

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

--------------------------------

### Run backend development server

Source: https://github.com/vaultsandbox/gateway/blob/main/CONTRIBUTING.md

Starts the NestJS backend in development mode with watch mode enabled. The backend will be accessible at http://localhost:9999.

```bash
npm run start:dev
```

--------------------------------

### Get Storage Metrics

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Returns email storage metrics.

```APIDOC
## GET /api/metrics/storage

### Description
Returns email storage metrics including memory usage, eviction statistics, and inbox counts.

### Method
GET

### Endpoint
/api/metrics/storage

### Parameters
None

### Response
#### Success Response (200 OK)
- **inboxCount** (integer) - The total number of inboxes.
- **emailCount** (integer) - The total number of emails stored.
- **memoryUsage** (object) - Memory usage statistics.
  - **heapUsed** (integer) - Heap memory used in bytes.
  - **heapTotal** (integer) - Total heap memory available in bytes.
- **evictions** (object) - Statistics on evicted emails.
  - **ttlExpired** (integer) - Number of emails evicted due to TTL expiration.
  - **manualDelete** (integer) - Number of emails manually deleted.

### Response Example
```json
{
  "inboxCount": 25,
  "emailCount": 450,
  "memoryUsage": {
    "heapUsed": 125829120,
    "heapTotal": 268435456
  },
  "evictions": {
    "ttlExpired": 150,
    "manualDelete": 45
  }
}
```
```

--------------------------------

### Get Available Webhook Templates

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Fetches a list of available built-in webhook templates. These templates define standard payload formats for various services.

```bash
curl -X GET "https://your-gateway.example.com/api/webhooks/templates" \
  -H "X-API-Key: your-api-key"
```

```json
{
  "templates": ["slack", "discord", "teams", "zapier", "default"]
}
```

--------------------------------

### Get Server Info

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Retrieves cryptographic information required for clients to support encrypted inbox functionality.

```bash
# Get server cryptographic info
curl -X GET "https://your-gateway.example.com/api/server-info" \
  -H "X-API-Key: your-api-key"

# Response (200 OK)
{
  "serverSigPk": "base64url-encoded-ML-DSA-65-public-key"
}
```

--------------------------------

### Get Chaos Configuration

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Retrieves the chaos engineering configuration for a specific inbox. Requires `VSB_CHAOS_ENABLED=true` to be set globally.

```APIDOC
## GET /api/inboxes/{inbox_id}/chaos

### Description
Retrieves the chaos engineering configuration for an inbox.

### Method
GET

### Endpoint
/api/inboxes/{inbox_id}/chaos

### Parameters
#### Path Parameters
- **inbox_id** (string) - Required - The email address of the inbox.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200 OK)
- **enabled** (boolean) - Indicates if chaos engineering is enabled for the inbox.
- **latency** (object) - Configuration for latency injection.
  - **enabled** (boolean) - Whether latency injection is enabled.
  - **minDelayMs** (integer) - Minimum delay in milliseconds.
  - **maxDelayMs** (integer) - Maximum delay in milliseconds.
  - **probability** (number) - Probability of latency injection.
- **connectionDrop** (object) - Configuration for connection dropping.
  - **enabled** (boolean) - Whether connection dropping is enabled.

### Response Example
```json
{
  "enabled": true,
  "latency": {
    "enabled": true,
    "minDelayMs": 500,
    "maxDelayMs": 5000,
    "probability": 0.5
  },
  "connectionDrop": {
    "enabled": false
  }
}
```
```

--------------------------------

### Get Server Info

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Returns server cryptographic information including the public signature key used for verifying server-signed data. Required for clients implementing encrypted inbox functionality.

```APIDOC
## GET /api/server-info

### Description
Returns server cryptographic information including the public signature key used for verifying server-signed data.

### Method
GET

### Endpoint
/api/server-info

### Parameters
#### Headers
- **X-API-Key** (string) - Required - The API key for authentication.

### Response
#### Success Response (200 OK)
- **serverSigPk** (string) - Base64URL-encoded server's public signature key.

#### Response Example
```json
{
  "serverSigPk": "base64url-encoded-ML-DSA-65-public-key"
}
```
```

--------------------------------

### Build Gateway Backend and Frontend

Source: https://github.com/vaultsandbox/gateway/blob/main/backend/README.md

Commands to build the backend, frontend, or both. Use 'npm run build:all' to build both the frontend and backend.

```bash
# Build backend only
npm run build
```

```bash
# Build frontend only
npm run build:frontend
```

```bash
# Build both frontend and backend
npm run build:all
```

--------------------------------

### Production Build

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Creates a production-ready build of the frontend application, outputting to dist/frontend/browser.

```bash
npm run build
```

--------------------------------

### Configure Gateway Backend Environment

Source: https://github.com/vaultsandbox/gateway/blob/main/backend/README.md

Copies the template environment file to a new file for customization. Review 'template-env' for all configuration options.

```bash
# Copy template and customize
cp template-env .env
```

--------------------------------

### Run Full Stack Development

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Commands to run the backend and frontend concurrently for full integration testing.

```bash
# Terminal 1: Start backend server
cd backend
npm run start:dev

# Terminal 2: Build frontend for backend serving
cd frontend
npm run build
# Or use watch mode for continuous rebuilds
npm run watch

# Access the application
# - Web UI: http://localhost:80/app (or configured VSB_SERVER_PORT)
# - Served by backend with production-like routing
```

--------------------------------

### Build Frontend for Production

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Command to generate production-ready assets for the frontend application.

```bash
# Build frontend
npm run build

# Build output is at dist/frontend/browser/
```

--------------------------------

### Get Email API

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Retrieves a specific email including parsed content, headers, attachments, and authentication results.

```APIDOC
## GET /api/inboxes/{inboxId}/emails/{emailId}

### Description
Retrieves a specific email including parsed content, headers, attachments, and authentication results. For encrypted inboxes, content is encrypted with the inbox's public key.

### Method
GET

### Endpoint
/api/inboxes/{inboxId}/emails/{emailId}

### Parameters
#### Path Parameters
- **inboxId** (string) - Required - The ID or email address of the inbox.
- **emailId** (string) - Required - The unique ID of the email to retrieve.

#### Headers
- **X-API-Key** (string) - Required - The API key for authentication.

### Response
#### Success Response (200 OK)
- **id** (string) - Unique identifier for the email.
- **receivedAt** (string) - Timestamp when the email was received.
- **from** (string) - The sender's email address.
- **subject** (string) - The subject of the email.
- **isRead** (boolean) - Indicates if the email has been read.
- **auth** (object) - Authentication results.
  - **spf** (object) - SPF check results.
    - **result** (string) - SPF check result (e.g., `pass`, `fail`).
  - **dkim** (object) - DKIM check results.
    - **result** (string) - DKIM check result (e.g., `pass`, `fail`).
  - **dmarc** (object) - DMARC check results.
    - **result** (string) - DMARC check result (e.g., `pass`, `fail`).
- **encryptedParsed** (object) - Full email content, including headers, body, and attachments. For encrypted inboxes, this content is encrypted with the inbox's public key.

#### Response Example
```json
{
  "id": "email-uuid-1",
  "receivedAt": "2024-01-15T10:30:00.000Z",
  "from": "sender@example.com",
  "subject": "Test Email",
  "isRead": false,
  "auth": {
    "spf": { "result": "pass" },
    "dkim": { "result": "pass" },
    "dmarc": { "result": "pass" }
  },
  "encryptedParsed": {
    "headers": {
      "Content-Type": "text/plain; charset=utf-8",
      "Subject": "Test Email"
    },
    "body": "This is the email body.",
    "attachments": []
  }
}
```
```

--------------------------------

### Run Gateway Backend in Production Mode

Source: https://github.com/vaultsandbox/gateway/blob/main/backend/README.md

Executes the Gateway backend in production mode. Ensure all necessary configurations are set in the environment.

```bash
# Run in production mode
npm run start:prod
```

--------------------------------

### Webhook Payload Verification

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Information and code examples for verifying the authenticity of incoming webhook payloads using HMAC-SHA256 signatures.

```APIDOC
## Webhook Payload Verification

### Description
Webhooks include HMAC-SHA256 signatures for payload verification. The signature is sent in the `X-Webhook-Signature` header. This section provides guidance and code examples for verifying these signatures.

### Node.js Verification Example
```javascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
```

### Express.js Webhook Handler Example
```javascript
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);
  console.log('Received event:', event.type, event.data);

  res.status(200).send('OK');
});
```
```

--------------------------------

### Build for Production

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Command to generate production build artifacts.

```bash
# Production build
npm run build

# Build output location
# dist/frontend/browser/   # Static files for backend serving
```

--------------------------------

### Run backend unit tests

Source: https://github.com/vaultsandbox/gateway/blob/main/CONTRIBUTING.md

Executes all unit tests for the backend. Ensure you are in the 'backend' directory.

```bash
npm run test
```

--------------------------------

### Run Unit Tests

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Commands to execute unit tests. Use `npm test` for interactive watch mode and `npm run test:h` for headless execution, suitable for CI environments.

```bash
# Run tests in watch mode
npm test

# Run tests headlessly (CI mode)
npm run test:h
```

--------------------------------

### Run backend e2e tests

Source: https://github.com/vaultsandbox/gateway/blob/main/CONTRIBUTING.md

Executes all end-to-end tests for the backend. Ensure you are in the 'backend' directory.

```bash
npm run test:e2e
```

--------------------------------

### Get Chaos Configuration

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Retrieves the current chaos engineering settings for a specific inbox. Requires the global VSB_CHAOS_ENABLED flag to be set to true.

```bash
# Get chaos config
curl -X GET "https://your-gateway.example.com/api/inboxes/test@your-domain.com/chaos" \
  -H "X-API-Key: your-api-key"

# Response (200 OK)
{
  "enabled": true,
  "latency": {
    "enabled": true,
    "minDelayMs": 500,
    "maxDelayMs": 5000,
    "probability": 0.5
  },
  "connectionDrop": {
    "enabled": false
  }
}
```

--------------------------------

### Get Raw Email

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Retrieves the raw RFC 5322 email content. Useful for debugging or when you need the original email exactly as received.

```APIDOC
## GET /api/inboxes/{email_address}/emails/{email_id}/raw

### Description
Retrieves the raw RFC 5322 email content.

### Method
GET

### Endpoint
/api/inboxes/{email_address}/emails/{email_id}/raw

### Parameters
#### Path Parameters
- **email_address** (string) - Required - The email address of the inbox.
- **email_id** (string) - Required - The unique identifier of the email.

### Response
#### Success Response (200 OK)
- **encryptedRaw** (string) - The raw email content.
```

--------------------------------

### Format code with Prettier

Source: https://github.com/vaultsandbox/gateway/blob/main/CONTRIBUTING.md

Runs Prettier to automatically format the code according to the project's style guidelines. Run this before committing.

```bash
npm run format
```

--------------------------------

### Gateway Backend Available Scripts

Source: https://github.com/vaultsandbox/gateway/blob/main/backend/README.md

Lists common scripts for managing the Gateway backend, including development, building, testing, and linting.

```bash
- npm run start:dev - Start development server with hot reload
- npm run build - Build backend
- npm run build:frontend - Build Angular frontend
- npm run build:all - Build both frontend and backend
- npm run start:prod - Run in production mode
- npm run test - Run unit tests
- npm run test:e2e - Run end-to-end tests
- npm run lint - Lint code with ESLint
- npm run format - Format code with Prettier
```

--------------------------------

### Get Raw Email Content

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Retrieves the raw RFC 5322 email content. Useful for debugging or when the original email format is required.

```bash
# Get raw email content
curl -X GET "https://your-gateway.example.com/api/inboxes/test@your-domain.com/emails/email-uuid-1/raw" \
  -H "X-API-Key: your-api-key"
```

```json
{
  "encryptedRaw": "Return-Path: <sender@example.com>\r\nReceived: from mail.example.com...\r\n..."
}
```

--------------------------------

### Create Test Email via REST API

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Creates a test email with specific authentication results. Requires VSB_SDK_DEVELOPMENT=true.

```bash
# Create test email with specific auth results
curl -X POST "https://your-gateway.example.com/api/test/emails" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "test@your-domain.com",
    "from": "sender@example.com",
    "subject": "Test with auth results",
    "text": "This is a test email body",
    "html": "<p>This is a test email body</p>",
    "auth": {
      "spf": "pass",
      "dkim": "fail",
      "dmarc": "none",
      "reverseDns": true
    }
  }'
```

```json
# Response (201 Created)
{
  "emailId": "test-email-uuid"
}
```

--------------------------------

### Get Email

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Fetches a specific email by ID, including headers and attachments. Encrypted inboxes return content encrypted with the inbox public key.

```bash
# Get email by ID
curl -X GET "https://your-gateway.example.com/api/inboxes/test@your-domain.com/emails/email-uuid-1" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### Run Unit Tests

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Executes unit tests using Karma.

```bash
npm test
```

--------------------------------

### Add New Route to Angular Application

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Example of how to add a new route configuration to an Angular application's routing module. This maps a URL path to a specific component.

```typescript
// src/app/app.routes.ts
export const routes: Routes = [
  { path: 'my-feature', component: MyFeatureComponent }
];
```

--------------------------------

### Create Webhook

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Allows the creation of new webhooks, supporting both predefined templates (like Slack) and custom templates with specific body and content types.

```APIDOC
## POST /api/webhooks

### Description
Creates a new webhook to receive event notifications.

### Method
POST

### Endpoint
/api/webhooks

### Request Body
- **url** (string) - Required - The URL where webhook events will be sent.
- **events** (array of strings) - Required - A list of event types to subscribe to.
- **template** (string or object) - Required - Either a string representing a built-in template name (e.g., "slack") or an object for a custom template.
  - If object: 
    - **type** (string) - Required - Must be "custom".
    - **body** (string) - Required - The template body, using Handlebars syntax for data injection.
    - **contentType** (string) - Required - The Content-Type header for the webhook request (e.g., "application/json").
- **filter** (object) - Optional - Rules to filter which events trigger the webhook.
  - **mode** (string) - Required - "all" or "any".
  - **rules** (array of objects) - Required - List of filter rules.
    - **field** (string) - Required - The field to filter on (e.g., "from.address").
    - **operator** (string) - Required - The comparison operator (e.g., "domain", "contains").
    - **value** (string) - Required - The value to compare against.
- **description** (string) - Optional - A human-readable description for the webhook.

### Request Example
```json
{
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "events": ["email.received", "email.stored"],
  "template": "slack",
  "filter": {
    "mode": "all",
    "rules": [
      { "field": "from.address", "operator": "domain", "value": "github.com" },
      { "field": "subject", "operator": "contains", "value": "pull request" }
    ]
  },
  "description": "GitHub PR notifications"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the webhook.
- **url** (string) - The configured URL for the webhook.
- **events** (array of strings) - The list of events the webhook is subscribed to.
- **template** (string or object) - The template used for the webhook.
- **filter** (object) - The filter configuration for the webhook.
- **description** (string) - The description of the webhook.
- **enabled** (boolean) - Indicates if the webhook is currently enabled.
- **secret** (string) - The signing secret for webhook payload verification.
- **createdAt** (string) - The timestamp when the webhook was created.

#### Response Example
```json
{
  "id": "webhook-uuid-1",
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "events": ["email.received", "email.stored"],
  "template": "slack",
  "filter": {
    "mode": "all",
    "rules": [
      { "field": "from.address", "operator": "domain", "value": "github.com" },
      { "field": "subject", "operator": "contains", "value": "pull request" }
    ]
  },
  "description": "GitHub PR notifications",
  "enabled": true,
  "secret": "whsec_xxxxxxxxxxxxxxxx",
  "createdAt": "2024-01-15T10:00:00.000Z"
}
```
```

```APIDOC
## POST /api/webhooks

### Description
Creates a new webhook with a custom template configuration.

### Method
POST

### Endpoint
/api/webhooks

### Request Body
- **url** (string) - Required - The URL where webhook events will be sent.
- **events** (array of strings) - Required - A list of event types to subscribe to.
- **template** (object) - Required - Configuration for a custom template.
  - **type** (string) - Required - Must be "custom".
  - **body** (string) - Required - The template body, using Handlebars syntax for data injection.
  - **contentType** (string) - Required - The Content-Type header for the webhook request (e.g., "application/json").

### Request Example
```json
{
  "url": "https://api.example.com/email-hook",
  "events": ["email.received"],
  "template": {
    "type": "custom",
    "body": "{\"email\": \"{{data.from.address}}\", \"subject\": \"{{data.subject}}\"}",
    "contentType": "application/json"
  }
}
```
```

--------------------------------

### Get Inbox Sync Status

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Returns a hash of the email list and count for quick synchronization checks. Useful for polling strategies to detect inbox changes without fetching all emails.

```APIDOC
## GET /api/inboxes/{email_address}/sync

### Description
Returns a hash of the email list and count for quick synchronization checks.

### Method
GET

### Endpoint
/api/inboxes/{email_address}/sync

### Parameters
#### Path Parameters
- **email_address** (string) - Required - The email address of the inbox.

### Response
#### Success Response (200 OK)
- **emailsHash** (string) - A hash representing the current state of the email list.
- **emailCount** (integer) - The total number of emails in the inbox.
```

--------------------------------

### Retrieve API Key

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Use this command to retrieve the API key generated by the backend. Check backend logs or the specified file path.

```bash
cat /app/data/.api-key
```

--------------------------------

### Run Headless Unit Tests

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Runs unit tests headlessly, suitable for CI environments.

```bash
npm run test:h
```

--------------------------------

### Get Inbox Sync Status

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Returns a hash of the email list and count for quick synchronization checks. Useful for polling strategies to detect inbox changes without fetching all emails.

```bash
# Get sync status
curl -X GET "https://your-gateway.example.com/api/inboxes/test@your-domain.com/sync" \
  -H "X-API-Key: your-api-key"
```

```json
{
  "emailsHash": "sha256-hash-of-email-list",
  "emailCount": 5
}
```

--------------------------------

### List All Global Webhooks

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Retrieves a list of all global webhooks configured on the gateway. Useful for auditing or managing existing webhooks.

```bash
curl -X GET "https://your-gateway.example.com/api/webhooks" \
  -H "X-API-Key: your-api-key"
```

```json
{
  "webhooks": [
    {
      "id": "webhook-uuid-1",
      "url": "https://hooks.slack.com/...",
      "events": ["email.received"],
      "enabled": true,
      "description": "Slack notifications"
    }
  ],
  "count": 1
}
```

--------------------------------

### Watch Mode Build

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Enables watch mode for continuous rebuilding of the application as files change.

```bash
npm run watch
```

--------------------------------

### Check Code Formatting

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Checks the code formatting without making changes, useful for CI.

```bash
npm run format:check
```

--------------------------------

### Local Development Docker Compose Configuration

Source: https://github.com/vaultsandbox/gateway/blob/main/README.md

Use this docker-compose.yml file to set up the VaultSandbox gateway for local development. It maps ports and sets up persistent data storage.

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

--------------------------------

### Create Webhook with Custom Template

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Use this to create a webhook with a custom JSON payload template. The template allows dynamic insertion of email data using Jinja-like syntax.

```bash
curl -X POST "https://your-gateway.example.com/api/webhooks" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/email-hook",
    "events": ["email.received"],
    "template": {
      "type": "custom",
      "body": "{\"email\": \"{{data.from.address}}\", \"subject\": \"{{data.subject}}\"}",
      "contentType": "application/json"
    }
  }'
```

--------------------------------

### Docker Compose Configuration

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Production deployment configuration for the gateway with VSX DNS auto-discovery and health checks.

```yaml
# docker-compose.yml
version: '3.8'

services:
  gateway:
    image: vaultsandbox/gateway:latest
    ports:
      - "25:25"    # SMTP
      - "80:80"    # HTTP (ACME + API)
      - "443:443"  # HTTPS
    environment:
      # Zero-config with VSX DNS
      - VSB_VSX_DNS_ENABLED=true
      # Or use custom domain:
      # - VSB_SMTP_ALLOWED_RECIPIENT_DOMAINS=qa.example.com
      # - VSB_CERT_ENABLED=true

      # Optional: Chaos engineering
      - VSB_CHAOS_ENABLED=true

      # Optional: Persistence
      - VSB_PERSISTENCE_POLICY=enabled

      # Optional: Clear all inboxes endpoint
      - VSB_LOCAL_ALLOW_CLEAR_ALL_INBOXES=true
    volumes:
      - gateway-data:/app/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  gateway-data:
```

--------------------------------

### Configure Gateway with Custom Domain

Source: https://github.com/vaultsandbox/gateway/blob/main/README.md

Use a custom domain for branding or existing infrastructure. Requires pre-configured A and MX records.

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

--------------------------------

### Memory Model Architecture

Source: https://github.com/vaultsandbox/gateway/blob/main/backend/docs/tech-briefs/email-storage.md

Diagram showing the relationship between EmailStorageService tracking and InboxStorageService data maps.

```text
EmailStorageService                 InboxStorageService
┌─────────────────────┐            ┌─────────────────────┐
│ emails[] (tracking) │            │ inboxes Map         │
│ - emailId           │───────────▶│   └─ emails Map     │
│ - inboxEmail        │            │       └─ encrypted  │
│ - size              │            │          payloads   │
│ - receivedAt        │            └─────────────────────┘
│ - isTombstone       │
└─────────────────────┘
     │
     ▼
currentMemoryUsage (sum of all email sizes)
```

--------------------------------

### Lint code with ESLint

Source: https://github.com/vaultsandbox/gateway/blob/main/CONTRIBUTING.md

Runs ESLint to identify and report on code patterns and potential issues. Run this to check your code before committing.

```bash
npm run lint
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/README.md

Environment-specific configurations for API endpoints. Use development for local proxying and production for absolute URLs.

```typescript
// src/environments/environment.development.ts
export const environment = {
  apiUrl: '/api',              // Proxied to backend (port 80)
};
```

```typescript
// src/environments/environment.ts
export const environment = {
  apiUrl: 'https://qa.mydomain.com/api',  // Production backend URL
};
```

--------------------------------

### Test a Webhook

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Sends a test event to a specified webhook to verify its configuration and connectivity. Use the webhook's ID to target it.

```bash
curl -X POST "https://your-gateway.example.com/api/webhooks/webhook-uuid-1/test" \
  -H "X-API-Key: your-api-key"
```

```json
{
  "success": true,
  "statusCode": 200,
  "responseTime": 145
}
```

```json
{
  "success": false,
  "error": "Connection refused",
  "statusCode": null
}
```

--------------------------------

### Generate backend coverage report

Source: https://github.com/vaultsandbox/gateway/blob/main/CONTRIBUTING.md

Generates a merged coverage report for all backend tests. Ensure you are in the 'backend' directory.

```bash
npm run test:cov:all
```

--------------------------------

### Subscribe to Email Events (SSE)

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Establishes a Server-Sent Events (SSE) connection to receive real-time notifications for new emails. Clients must specify inbox hashes to subscribe to specific inboxes.

```bash
# Subscribe to email events for specific inboxes
curl -N "https://your-gateway.example.com/api/events?inboxes=abc123,xyz789" \
  -H "X-API-Key: your-api-key" \
  -H "Accept: text/event-stream"
```

```text
# Event stream output:
# data: {"type":"email.new","inboxHash":"abc123","emailId":"email-uuid-1","timestamp":"2024-01-15T10:30:00.000Z"}
# 
# data: {"type":"heartbeat","timestamp":"2024-01-15T10:30:30.000Z"}
```

```javascript
// JavaScript EventSource example
const eventSource = new EventSource(
  'https://your-gateway.example.com/api/events?inboxes=abc123,xyz789',
  { headers: { 'X-API-Key': 'your-api-key' } }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'email.new') {
    console.log(`New email received: ${data.emailId}`);
    // Fetch the email content
    fetchEmail(data.inboxHash, data.emailId);
  }
};

eventSource.onerror = (error) => {
  console.error('SSE connection error:', error);
};
```

--------------------------------

### Validate API Key

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Verifies the provided API key via the X-API-Key header. Returns 200 OK on success or 401 Unauthorized if the key is invalid.

```bash
# Validate API key
curl -X GET "https://your-gateway.example.com/api/check-key" \
  -H "X-API-Key: your-api-key"

# Response (200 OK)
{
  "ok": true
}

# Response (401 Unauthorized)
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

--------------------------------

### Create Slack Webhook with Filter

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Use this to create a Slack webhook that triggers on specific email events and filters based on sender domain and subject. Requires 'email.received' or 'email.stored' events.

```bash
curl -X POST "https://your-gateway.example.com/api/webhooks" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.slack.com/services/T00/B00/xxx",
    "events": ["email.received", "email.stored"],
    "template": "slack",
    "filter": {
      "mode": "all",
      "rules": [
        { "field": "from.address", "operator": "domain", "value": "github.com" },
        { "field": "subject", "operator": "contains", "value": "pull request" }
      ]
    },
    "description": "GitHub PR notifications"
  }'
```

```json
{
  "id": "webhook-uuid-1",
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "events": ["email.received", "email.stored"],
  "template": "slack",
  "filter": {
    "mode": "all",
    "rules": [
      { "field": "from.address", "operator": "domain", "value": "github.com" },
      { "field": "subject", "operator": "contains", "value": "pull request" }
    ]
  },
  "description": "GitHub PR notifications",
  "enabled": true,
  "secret": "whsec_xxxxxxxxxxxxxxxx",
  "createdAt": "2024-01-15T10:00:00.000Z"
}
```

--------------------------------

### List Global Webhooks

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Retrieves a list of all globally configured webhooks on the gateway.

```APIDOC
## GET /api/webhooks

### Description
Returns all global webhooks configured on the gateway.

### Method
GET

### Endpoint
/api/webhooks

### Response
#### Success Response (200 OK)
- **webhooks** (array of objects) - A list of webhook configurations.
  - **id** (string) - The unique identifier for the webhook.
  - **url** (string) - The configured URL for the webhook.
  - **events** (array of strings) - The list of events the webhook is subscribed to.
  - **enabled** (boolean) - Indicates if the webhook is currently enabled.
  - **description** (string) - The description of the webhook.
- **count** (integer) - The total number of webhooks returned.

#### Response Example
```json
{
  "webhooks": [
    {
      "id": "webhook-uuid-1",
      "url": "https://hooks.slack.com/...",
      "events": ["email.received"],
      "enabled": true,
      "description": "Slack notifications"
    }
  ],
  "count": 1
}
```
```

--------------------------------

### Key Derivation Process

Source: https://github.com/vaultsandbox/gateway/blob/main/backend/docs/tech-briefs/crypto-module.md

Details the Key Derivation Function (KDF) process using HKDF-SHA-512, including the input key material (IKM), salt, and info parameters. The context string is 'vaultsandbox:email:v1'.

```text
ikm = KEM shared secret
salt = SHA-256(ct_kem)           // Unique per encryption
info = context || aad_length || aad
key = HKDF-SHA-512(ikm, salt, info, 32 bytes)
```

--------------------------------

### Subscribe to Email Events (SSE)

Source: https://context7.com/vaultsandbox/gateway/llms.txt

Establishes a Server-Sent Events connection to receive real-time notifications when new emails arrive. Clients must specify inbox hashes to subscribe to.

```APIDOC
## GET /api/events

### Description
Establishes a Server-Sent Events connection to receive real-time notifications for new emails.

### Method
GET

### Endpoint
/api/events

### Parameters
#### Query Parameters
- **inboxes** (string) - Required - A comma-separated list of inbox hashes to subscribe to.

### Response
#### Success Response (200 OK)
- The response is a Server-Sent Events stream. Events include:
  - `email.new`: Notification for a new email.
  - `heartbeat`: Periodic keep-alive signal.
```

--------------------------------

### Create a new branch for feature or bug fix

Source: https://github.com/vaultsandbox/gateway/blob/main/CONTRIBUTING.md

Use this command to create a new branch for your work. Replace 'feat/my-awesome-feature' or 'fix/that-annoying-bug' with a descriptive name for your changes.

```bash
git checkout -b feat/my-awesome-feature
git checkout -b fix/that-annoying-bug
```

--------------------------------

### Create Inbox Open Custom Inbox Settings

Source: https://github.com/vaultsandbox/gateway/blob/main/frontend/src/app/features/mail/mailbox-sidebar/mailbox-sidebar.html

Placeholder for functionality related to creating custom inbox settings for 'Inbox Open'. No specific code provided.