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.

Termux (Android)

Install MailSpoof on Android with a single command in the Termux app:

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

This installs python and git via pkg, clones the repository, and sets up the CLI globally on your device.

Docker Deployment

Deploy MailSpoof on any server or cloud VPS without installing dependencies:

bash
$ git clone https://github.com/syed-sameer-ul-hassan/MailSpoof.git
$ cd MailSpoof
$ docker-compose up -d

The container runs the SMTP server and HTTP Tracking Server concurrently. Audit logs and custom templates are persisted via mounted volumes.

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 test 1 --target-list targets.csv  # Bulk CSV targeting (v1.2.0)
$ mailspoof test 1 target@company.com --attach file.pdf  # With attachment (v1.2.0)
$ mailspoof test 1 target@company.com --reply-to x@evil.com  # Header injection (v1.2.0)
$ 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

Bulk CSV Targeting

Send simulations to hundreds of targets at once using a CSV file:

bash
$ mailspoof test 1 --target-list employees.csv --profile gmail
# CSV format: one email per row, address in first column

The --target-list flag works with both test and custom commands. Each target is logged independently in the audit log.

Attachment Payloads

Attach one or more files to test email gateway security against malicious attachments:

bash
$ mailspoof test 47 target@company.com --attach HR_Policy.pdf
$ mailspoof test 47 target@company.com --attach file1.pdf --attach file2.docx

Header Injection

Inject custom email headers to simulate specific mail clients or test header-based filtering:

bash
$ mailspoof test 1 target@company.com \
  --reply-to attacker@evil.com \
  --x-mailer "Microsoft Outlook 16.0"

Documentation