MailSpoof - Documentation

Installation

MailSpoof supports Linux, macOS, and Termux. Clone the repo and run the installer:

bash
$ git clone https://github.com/syed-sameer-ul-hassan/MailSpoof.git
$ cd MailSpoof && bash install.sh

Or install directly without cloning:

bash
$ curl -fsSL https://raw.githubusercontent.com/syed-sameer-ul-hassan/MailSpoof/main/install.sh | bash

The installer auto-detects your distribution and installs Python, venv, and pip if needed.

Quick Start

Run without arguments to start the interactive session:

bash
$ mailspoof
# Starts SMTP server + interactive spoofing wizard

Commands

bash
$ mailspoof server     # Start SMTP server only
$ mailspoof start      # Start server + interactive session
$ mailspoof list       # List all templates
$ mailspoof test 1 target@company.com  # Run scenario by ID
$ mailspoof custom     # Fully custom spoofing test
$ mailspoof create     # Create custom template
$ mailspoof -t         # Alias for create
$ mailspoof preview 1   # Preview a template by ID
$ mailspoof remove-template 1 # Remove a custom template
$ mailspoof edit-template 1   # Edit a template in nano
$ mailspoof profile list   # List saved SMTP profiles
$ mailspoof logs       # View audit logs
$ mailspoof report     # Generate assessment report
$ mailspoof update     # Update from Git repository
$ mailspoof uninstall  # Remove MailSpoof
$ mailspoof help       # Show help banner

Additional flags: mailspoof help shows the help page, mailspoof -v prints the version.

SMTP Server

The built-in SMTP server implements a minimal state machine and relays by resolving MX records.

bash
$ mailspoof server --host 0.0.0.0 --port 2525
$ mailspoof start --server-only  # Server without interactive mode

Templates

Custom templates use a simple key-value header format saved to ~/.mailspoof/templates/custom/. Use raw HTML in the body for rich rendering; MailSpoof automatically generates a plain-text fallback and appends a test disclaimer to both parts. The {TODAY} placeholder is automatically replaced with the current date in built-in templates.

template.txt
Name: My Custom Template
Category: Social Engineering
Severity: High
From Email: security@company.com
From Name: Security Team
Subject: Action Required
Tags: urgent, billing
Body:
<html><body><h1>Action Required</h1>...</body></html>
Description: Custom test scenario.

Create interactively (type EOF on a new line to finish the body):

bash
$ mailspoof create

Filter templates when listing:

bash
$ mailspoof list --filter billing

Custom Tests

bash
$ mailspoof custom \
  --from-email "ceo@company.com" \
  --from-name "CEO" \
  --subject "Urgent" \
  --body "Please review" \
  --target "user@company.com" \
  --profile gmail \
  --verbose

Verbose Diagnostics

Trace every stage of SMTP communication with the --verbose flag. MailSpoof prints connection details, STARTTLS status, authentication steps, and provides actionable error explanations for blacklists, SPF/DKIM/DMARC rejections, and relay failures.

bash
$ mailspoof test 1 target@company.com --verbose

SMTP Relay

Direct MX delivery from residential IPs is blocked by most providers. Use an external relay inline or save a profile:

bash
$ mailspoof test 1 target@company.com \
  --smtp-host smtp.gmail.com \
  --smtp-port 587 \
  --smtp-user your-email@gmail.com \
  --smtp-pass your-app-password \
  --use-tls \
  --verbose

SMTP Profiles

Save relay credentials once and reuse them with --profile:

bash
$ mailspoof profile add gmail \
  --host smtp.gmail.com \
  --port 587 \
  --user you@gmail.com \
  --pass app-password \
  --use-tls

$ mailspoof test 1 target@company.com --profile gmail --verbose
$ mailspoof profile list
$ mailspoof profile remove gmail

Preview & Template Management

Inspect templates before sending and manage them from the CLI:

bash
$ mailspoof preview 1            # Preview rendered body
$ mailspoof preview 1 --raw      # Show raw HTML
$ mailspoof edit-template 1     # Open in $EDITOR or nano
$ mailspoof remove-template 1  # Delete custom template
$ mailspoof list --filter ceo  # Filter by keyword/tag

Audit Logs

View recent test activity from the structured JSON audit log:

bash
$ mailspoof logs           # Last 20 entries
$ mailspoof logs --lines 50  # Last 50 entries

Reporting

All tests are logged as JSON lines in ~/.mailspoof/audit.log. Generate a report with:

bash
$ mailspoof report --output /path/to/report.json
$ mailspoof report --format csv

The report includes total tests, success rate, breakdown by scenario and type, risk level (CRITICAL / HIGH / MEDIUM), and remediation recommendations. JSON format is ideal for automation; CSV exports the following columns: timestamp, test_type, scenario, target, from_email, success, category, severity, smtp_server, and error.

Update

bash
$ mailspoof update

Uninstall

Remove MailSpoof completely:

bash
$ mailspoof uninstall

Documentation