gh-whamp-whamp-claude-tools-mailhog-plugin/skills/mailhog/SKILL.md

---
name: mailhog
description: This skill should be used when the user asks to "set up MailHog", "test email functionality", "configure MailHog", "send test emails", "check MailHog messages", "configure SMTP testing", or "manage email capture". Provides comprehensive MailHog email testing server setup and management.
version: 1.0.0
---

# MailHog Email Testing Server Management

MailHog provides a comprehensive email testing solution for development and testing environments. This skill enables complete MailHog server management, email testing workflows, and integration with development pipelines.

## Core Concepts

**MailHog Architecture**: MailHog consists of SMTP server (port 1025 by default) for receiving emails and HTTP API/UI (port 8025 by default) for viewing and managing captured emails.

**Storage Options**: Memory (default, ephemeral), MongoDB (persistent), or Maildir (file-based) for email storage.

**Jim Simulation**: Built-in chaotic network simulation for testing email resilience under adverse conditions.

## Essential Setup Commands

### Start Basic MailHog Server

Start MailHog with default settings (memory storage, ports 1025/8025):

```bash
# Basic start
mailhog

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

# Background execution
mailhog &
```

### Start with Persistent Storage

Configure MongoDB storage:

```bash
mailhog -storage mongodb -mongo-uri 127.0.0.1:27017 -mongo-db mailhog_test -mongo-coll messages
```

Configure Maildir storage:

```bash
mailhog -storage maildir -maildir-path ./mail_storage
```

## Configuration Management

### Custom SMTP Configuration

```bash
# Custom hostname for EHLO/HELO
mailhog -hostname mailhog.test.local

# Custom bind addresses
mailhog -smtp-bind-addr 0.0.0.0:1025 -ui-bind-addr 0.0.0.0:8025

# CORS configuration
mailhog -cors-origin "http://localhost:3000,http://localhost:5173"
```

### Authentication Setup

```bash
# Create bcrypt password file
echo "admin:$(bcrypt-hash 'password123')" > auth_file.txt

# Enable authentication
mailhog -auth-file auth_file.txt
```

### Outgoing SMTP Configuration

Create outgoing SMTP configuration for email forwarding:

```json
{
  "server": "smtp.gmail.com",
  "port": 587,
  "username": "test@gmail.com",
  "password": "app-password",
  "tls": true
}
```

```bash
mailhog -outgoing-smtp outgoing_config.json
```

## Testing Email Functionality

### Send Test Emails via CLI

Use built-in test utilities or SMTP clients:

```bash
# Using telnet for basic SMTP test
telnet localhost 1025
EHLO test.local
MAIL FROM:test@sender.local
RCPT TO:recipient@test.local
DATA
Subject: Test Email
From: test@sender.local
To: recipient@test.local

This is a test email.
.
QUIT
```

### Send Test Emails with Scripts

Execute test email sending script:

```bash
./scripts/send_test_email.sh --to test@recipient.local --subject "Test Message" --body "Test content"
```

### API Interaction Examples

Query captured emails via API:

```bash
# Get all messages
curl http://localhost:8025/api/v1/messages

# Get recent messages
curl http://localhost:8025/api/v1/messages?limit=10

# Search emails
curl -X POST http://localhost:8025/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "subject:test"}'
```

## Development Integration

### Environment Setup for Testing

Configure application environments for MailHog integration:

```bash
# Environment variables
export SMTP_HOST=localhost
export SMTP_PORT=1025
export SMTP_USER=
export SMTP_PASS=
export SMTP_TLS=false
```

### Framework Integration Patterns

**Node.js/Nodemailer Configuration:**
```javascript
const transporter = nodemailer.createTransporter({
  host: 'localhost',
  port: 1025,
  secure: false,
  auth: false
});
```

**Python/SMTP Configuration:**
```python
import smtplib
server = smtplib.SMTP('localhost', 1025)
server.sendmail(sender, recipients, message)
```

### Testing Workflow Automation

Execute automated testing script:

```bash
./scripts/test_email_workflow.sh --config test_config.json
```

## Advanced Configuration

### Network Simulation (Jim)

Enable Jim for chaotic network testing:

```bash
# Enable Jim with default settings
mailhog -invite-jim

# Custom Jim behavior
mailhog -invite-jim \
  -jim-accept 0.95 \
  -jim-reject-sender 0.1 \
  -jim-reject-recipient 0.1 \
  -jim-disconnect 0.02 \
  -jim-linkspeed-affect 0.2
```

### Production-Ready Configuration

```bash
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.example.com:27017 \
  -mongo-db mailhog_prod \
  -cors-origin "https://app.example.com" \
  -hostname mailhog.example.com
```

## Monitoring and Debugging

### Health Checks

Verify MailHog is running correctly:

```bash
# Check SMTP port
telnet localhost 1025

# Check UI/API
curl http://localhost:8025

# Check API status
curl http://localhost:8025/api/v1/messages
```

### Log Analysis

Monitor MailHog operations and troubleshoot issues:

```bash
# Start with verbose logging (if available)
mailhog 2>&1 | tee mailhog.log

# Monitor message count
watch -n 5 'curl -s http://localhost:8025/api/v1/messages | jq ".total"'
```

### Performance Optimization

Optimize for high-volume testing:

```bash
# Memory cleanup for long-running instances
curl -X DELETE http://localhost:8025/api/v1/messages

# MongoDB indexing for performance
# Execute via mongo shell on mailhog database
db.messages.createIndex({ "created": -1 })
db.messages.createIndex({ "From": 1 })
```

## Common Workflows

### Development Email Testing Setup

1. Start MailHog with appropriate configuration
2. Configure application SMTP settings to point to MailHog
3. Send test emails from application
4. Verify emails in MailHog UI (`http://localhost:8025`)
5. Use API for automated testing assertions

### Automated CI/CD Integration

1. Include MailHog in test docker-compose or CI configuration
2. Configure test environment SMTP settings
3. Run application tests that send emails
4. Use API assertions to verify email content/delivery
5. Clean up messages between test runs

### Bulk Email Testing

1. Use scripts to generate multiple test emails
2. Test rate limiting and performance
3. Verify email queue handling
4. Monitor resource usage during high-volume scenarios

## Troubleshooting

### Common Issues

**Port Conflicts**: Kill existing processes or change ports:
```bash
lsof -i :1025 -i :8025
kill -9 <PID>
```

**MongoDB Connection Issues**: Verify MongoDB is running and accessible:
```bash
mongo mongodb://127.0.0.1:27017/mailhog_test
```

**Email Not Appearing**: Check SMTP client configuration and network connectivity.

**UI Not Loading**: Verify API bind address and check for port conflicts.

### Debug Commands

```bash
# Test SMTP connection manually
telnet localhost 1025

# Check MailHog process
ps aux | grep mailhog

# Verify API accessibility
curl -v http://localhost:8025/api/v1/messages
```

## Security Considerations

**Production Usage**: Never expose MailHog directly to internet without authentication and proper firewall configuration.

**Email Privacy**: Captured emails may contain sensitive information - secure MailHog instance appropriately.

**Authentication**: Always use authentication in production environments with `-auth-file`.

## Migration and Backup

### MongoDB Backup

```bash
# Backup MailHog messages
mongodump --db mailhog_prod --collection messages --out ./backup

# Restore messages
mongorestore --db mailhog_prod --collection messages ./backup/messages.bson
```

### Maildir Backup

```bash
# Backup maildir storage
tar -czf mailhog_maildir_backup.tar.gz ./mail_storage
```

## Additional Resources

### Reference Files

For detailed configurations and advanced patterns, consult:
- **`references/configurations.md`** - Advanced configuration examples
- **`references/api-endpoints.md`** - Complete API reference
- **`references/integration-patterns.md`** - Framework integration guides

### Scripts

Utility scripts for common operations:
- **`scripts/send_test_email.sh`** - Send test emails via SMTP
- **`scripts/test_email_workflow.sh`** - Automated testing workflow
- **`scripts/mailhog_manager.sh`** - Server management utility

### Examples

Working configurations and setups:
- **`examples/docker-compose.yml`** - Docker container setup
- **`examples/app-configs/`** - Application configuration examples
- **`examples/terraform/`** - Infrastructure as code examples