gh-whamp-whamp-claude-tools-mailhog-plugin/skills/mailhog/references/configurations.md

MailHog Advanced Configurations

Complete Configuration Reference

Basic Configuration

# Minimal configuration
mailhog

# Custom ports
mailhog -smtp-bind-addr :1025 -ui-bind-addr :8025 -api-bind-addr :8025

Storage Configurations

Memory Storage (Default)

mailhog -storage memory

MongoDB Storage

# Basic MongoDB
mailhog -storage mongodb -mongo-uri 127.0.0.1:27017 -mongo-db mailhog -mongo-coll messages

# With authentication
mailhog -storage mongodb \
  -mongo-uri "mongodb://user:pass@mongodb.example.com:27017/mailhog_prod" \
  -mongo-db mailhog_prod \
  -mongo-coll messages

# With replica set
mailhog -storage mongodb \
  -mongo-uri "mongodb://mongodb1:27017,mongodb2:27017,mongodb3:27017/mailhog?replicaSet=rs0" \
  -mongo-db mailhog_prod \
  -mongo-coll messages

Maildir Storage

mailhog -storage maildir -maildir-path /var/mailhog/storage

Network Configuration

Bind Addresses

# Bind to all interfaces
mailhog -smtp-bind-addr 0.0.0.0:1025 -ui-bind-addr 0.0.0.0:8025

# Bind to specific interface
mailhog -smtp-bind-addr 192.168.1.100:1025 -ui-bind-addr 192.168.1.100:8025

Hostname Configuration

mailhog -hostname mailhog.production.local

CORS Configuration

# Single origin
mailhog -cors-origin "https://app.example.com"

# Multiple origins
mailhog -cors-origin "https://app.example.com,https://admin.example.com"

Authentication Configuration

Basic Auth File Format

# auth-file.txt format
username1:$2b$12$hashedpassword1
username2:$2b$12$hashedpassword2

Generate Bcrypt Hash

# Python
python3 -c "import bcrypt; print(bcrypt.hashpw(b'password123', bcrypt.gensalt()).decode())"

# Node.js
node -e "const bcrypt = require('bcrypt'); console.log(bcrypt.hashSync('password123', 12));"

Outgoing SMTP Configuration

Gmail Configuration

{
  "server": "smtp.gmail.com",
  "port": 587,
  "username": "your-email@gmail.com",
  "password": "app-specific-password",
  "tls": true,
  "from": "your-email@gmail.com"
}

Office 365 Configuration

{
  "server": "smtp.office365.com",
  "port": 587,
  "username": "your-email@company.com",
  "password": "your-password",
  "tls": true,
  "from": "your-email@company.com"
}

Local SMTP Relay

{
  "server": "localhost",
  "port": 25,
  "tls": false,
  "from": "noreply@company.local"
}

Jim Network Simulation Configuration

Comprehensive Jim Configuration

mailhog -invite-jim \
  -jim-accept 0.98 \
  -jim-reject-sender 0.05 \
  -jim-reject-recipient 0.05 \
  -jim-reject-auth 0.03 \
  -jim-disconnect 0.01 \
  -jim-linkspeed-affect 0.15 \
  -jim-linkspeed-min 512 \
  -jim-linkspeed-max 20480

Jim Parameter Explanations

• jim-accept: Probability of accepting connection (0.0-1.0)
• jim-reject-sender: Probability of rejecting MAIL FROM command
• jim-reject-recipient: Probability of rejecting RCPT TO command
• jim-reject-auth: Probability of rejecting AUTH command
• jim-disconnect: Probability of random disconnection
• jim-linkspeed-affect: Probability of affecting link speed
• jim-linkspeed-min/ max: Range for simulated link speed (bytes/sec)

Production Configurations

High-Availability Setup

mailhog \
  -smtp-bind-addr 0.0.0.0:1025 \
  -ui-bind-addr 0.0.0.0:8025 \
  -api-bind-addr 0.0.0.0:8025 \
  -storage mongodb \
  -mongo-uri "mongodb://mongodb1:27017,mongodb2:27017,mongodb3:27017/mailhog_prod?replicaSet=rs0" \
  -mongo-db mailhog_prod \
  -mongo-coll messages \
  -cors-origin "https://app.example.com,https://admin.example.com" \
  -hostname mailhog.production.local \
  -auth-file /etc/mailhog/auth.txt \
  -outgoing-smtp /etc/mailhog/outgoing.json

Development Environment

mailhog \
  -smtp-bind-addr 127.0.0.1:1025 \
  -ui-bind-addr 127.0.0.1:8025 \
  -api-bind-addr 127.0.0.1:8025 \
  -storage memory \
  -hostname mailhog.dev.local \
  -cors-origin "http://localhost:3000,http://localhost:5173"

CI/CD Environment

mailhog \
  -smtp-bind-addr 0.0.0.0:1025 \
  -ui-bind-addr 0.0.0.0:8025 \
  -api-bind-addr 0.0.0.0:8025 \
  -storage memory \
  -hostname mailhog.ci.local \
  -ui-web-path mailhog

Docker Configurations

Dockerfile Example

FROM mailhog/mailhog:latest

# Copy custom configuration
COPY auth.txt /auth.txt
COPY outgoing.json /outgoing.json

# Custom entrypoint for additional config
ENTRYPOINT ["/bin/sh", "-c", "MailHog -auth-file /auth.txt -outgoing-smtp /outgoing.json"]

Docker Compose Example

version: '3.8'
services:
  mailhog:
    image: mailhog/mailhog:latest
    ports:
      - "1025:1025"
      - "8025:8025"
    environment:
      - MH_HOSTNAME=mailhog.docker.local
    volumes:
      - ./auth.txt:/auth.txt
      - ./outgoing.json:/outgoing.json
    command: ["MailHog", "-auth-file", "/auth.txt", "-outgoing-smtp", "/outgoing.json"]

  mongodb:
    image: mongo:latest
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:

Kubernetes Configurations

Basic Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mailhog
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mailhog
  template:
    metadata:
      labels:
        app: mailhog
    spec:
      containers:
      - name: mailhog
        image: mailhog/mailhog:latest
        ports:
        - containerPort: 1025
        - containerPort: 8025
        env:
        - name: MH_HOSTNAME
          value: "mailhog.k8s.local"
        - name: MH_SMTP_BIND_ADDR
          value: "0.0.0.0:1025"
        - name: MH_UI_BIND_ADDR
          value: "0.0.0.0:8025"
---
apiVersion: v1
kind: Service
metadata:
  name: mailhog-smtp
spec:
  selector:
    app: mailhog
  ports:
  - port: 1025
    targetPort: 1025
---
apiVersion: v1
kind: Service
metadata:
  name: mailhog-ui
spec:
  selector:
    app: mailhog
  ports:
  - port: 8025
    targetPort: 8025

Performance Tuning

High-Volume Configuration

mailhog \
  -smtp-bind-addr 0.0.0.0:1025 \
  -ui-bind-addr 0.0.0.0:8025 \
  -storage mongodb \
  -mongo-uri "mongodb://mongodb.example.com:27017/mailhog_perf" \
  -mongo-db mailhog_perf \
  -mongo-coll messages \
  -hostname mailhog.perf.local

MongoDB Indexing for Performance

// Connect to MongoDB and create indexes
use mailhog_perf

// Compound index for common queries
db.messages.createIndex({ "created": -1, "From": 1 })

// Index for sender searches
db.messages.createIndex({ "From": 1, "created": -1 })

// Index for recipient searches
db.messages.createIndex({ "To.Address": 1, "created": -1 })

// Text index for full-text search
db.messages.createIndex({
  "Content.Body": "text",
  "Subject": "text",
  "From": "text",
  "To.Address": "text"
})

Environment Variables

MailHog supports environment variable configuration. All command-line flags can be set as environment variables:

# Environment variable naming convention: MH_<FLAG_NAME_IN_UPPERCASE>
export MH_SMTP_BIND_ADDR=0.0.0.0:1025
export MH_UI_BIND_ADDR=0.0.0.0:8025
export MH_HOSTNAME=mailhog.env.local
export MH_STORAGE=mongodb
export MH_MONGO_URI=mongodb://localhost:27017/mailhog
export MH_MONGO_DB=mailhog
export MH_MONGO_COLL=messages

# Run with environment variables
mailhog

Configuration Validation

Validate Configuration Before Start

# Test MongoDB connection
mongo --eval "db.adminCommand('ismaster')" mongodb://localhost:27017/mailhog

# Test file permissions for auth file
test -r /path/to/auth.txt && echo "Auth file readable" || echo "Auth file not readable"

# Test port availability
netstat -tuln | grep :1025 && echo "Port 1025 in use" || echo "Port 1025 available"
netstat -tuln | grep :8025 && echo "Port 8025 in use" || echo "Port 8025 available"

Configuration Health Check Script

#!/bin/bash
# config_health_check.sh

echo "MailHog Configuration Health Check"

# Check required commands
command -v mailhog >/dev/null 2>&1 || { echo "MailHog not installed"; exit 1; }

# Test MongoDB if configured
if [[ "$MH_STORAGE" == "mongodb" ]]; then
    mongo --eval "db.adminCommand('ismaster')" "$MH_MONGO_URI" >/dev/null 2>&1 || { echo "MongoDB connection failed"; exit 1; }
    echo "✓ MongoDB connection OK"
fi

# Test auth file if configured
if [[ -n "$MH_AUTH_FILE" ]]; then
    test -r "$MH_AUTH_FILE" || { echo "Auth file not readable: $MH_AUTH_FILE"; exit 1; }
    echo "✓ Auth file readable"
fi

echo "✓ Configuration health check passed"