Spamscanner
Spam Scanner is a Node.js anti-spam, email filtering, and phishing prevention tool and service. Built for @ladjs, @forwardemail, @cabinjs, @breejs, and @lassjs.
Install / Use
/learn @spamscanner/SpamscannerREADME
[!NOTE] Spam Scanner is actively maintained and used in production at Forward Email to protect millions of emails daily.
Table of Contents
- Foreword
- Installation
- CLI (Command Line Interface)
- Why Spam Scanner
- Features
- Comparison
- Architecture
- Requirements
- Quick Start
- API Documentation
- Advanced Usage
- ARF (Abuse Reporting Format)
- Mail Server Integration
- Performance
- Contributing
- License
- Support
- Acknowledgments
Foreword
Spam Scanner is a tool and service created after hitting countless roadblocks with existing spam-detection solutions. In other words, it's our current plan for spam and our better plan for spam.
Our goal is to build and utilize a scalable, performant, simple, easy to maintain, and powerful API for use in our service at Forward Email to limit spam and provide other measures to prevent attacks on our users.
Initially we tried using SpamAssassin, and later evaluated rspamd – but in the end we learned that all existing solutions (even ones besides these) are overtly complex, missing required features or documentation, incredibly challenging to configure; high-barrier to entry, or have proprietary storage backends (that could store and read your messages without your consent) that limit our scalability.
To us, we value privacy and the security of our data and users – specifically we have a "Zero-Tolerance Policy" on storing logs or metadata of any kind, whatsoever (see our Privacy Policy for more on that). None of these solutions honored this privacy policy (without removing essential spam-detection functionality), so we had to create our own tool – thus "Spam Scanner" was born.
Installation
npm (Recommended)
npm install spamscanner
For CLI usage:
# Install globally
npm install -g spamscanner
# Or use npx without installing
npx spamscanner scan email.eml
Standalone Binary (No Node.js Required)
Download a pre-built binary for your platform. These are self-contained executables that don't require Node.js.
See CLI Installation for download links and platform-specific instructions.
ClamAV Installation (Optional)
macOS
brew install clamav
freshclam
Ubuntu/Debian
sudo apt-get update
sudo apt-get install clamav clamav-daemon
sudo freshclam
sudo systemctl start clamav-daemon
CentOS/RHEL
sudo yum install clamav clamav-update
sudo freshclam
[!TIP] See the ClamAV configuration guide for detailed installation instructions.
CLI (Command Line Interface)
SpamScanner provides a command-line interface for scanning emails directly from the terminal or integrating with mail servers.
CLI Installation
SpamScanner can be installed via npm or as a standalone binary. The standalone binary includes Node.js and all dependencies, so no additional runtime is required.
Install via npm (requires Node.js)
# Install globally
npm install -g spamscanner
# Or use npx without installing
npx spamscanner --help
Install Standalone Binary
macOS
# Download manually for Apple Silicon (M1/M2/M3)
curl -fsSL https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-darwin-arm64 -o /usr/local/bin/spamscanner
chmod +x /usr/local/bin/spamscanner
# Download manually for Intel Mac
curl -fsSL https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-darwin-x64 -o /usr/local/bin/spamscanner
chmod +x /usr/local/bin/spamscanner
Linux
# Download and install to /usr/local/bin
sudo curl -fsSL https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-linux-x64 -o /usr/local/bin/spamscanner
sudo chmod +x /usr/local/bin/spamscanner
# Add to PATH if not already: export PATH="$HOME/.local/bin:$PATH"
# Or install to user directory (no sudo required)
mkdir -p ~/.local/bin
curl -fsSL https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-linux-x64 -o ~/.local/bin/spamscanner
chmod +x ~/.local/bin/spamscanner
# Add to PATH if not already: export PATH="$HOME/.local/bin:$PATH"
Windows
# Using PowerShell (run as Administrator)
Invoke-WebRequest -Uri "https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-win-x64.exe" -OutFile "C:\Program Files\spamscanner\spamscanner.exe"
# Add to PATH via System Properties > Environment Variables
# Or download to current directory
Invoke-WebRequest -Uri "https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-win-x64.exe" -OutFile ".\spamscanner.exe"
# Add to PATH via System Properties > Environment Variables
Verify Installation
# Check version
spamscanner version
# Check for updates
spamscanner update
Automatic Updates
SpamScanner CLI automatically checks for updates once every 24 hours and displays a notification if a new version is available. You can also manually check for updates:
# Check for updates
spamscanner update
# Disable automatic update checks
spamscanner scan email.eml --no-update-check
To update to the latest version, simply re-run the installation command for your platform or use npm:
# Update via npm
npm update -g spamscanner
# Or re-download the binary (macOS/Linux)
curl -fsSL https://github.com/spamscanner/spamscanner/releases/latest/download/spamscanner-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/x64/' | sed 's/aarch64/arm64/') -o /usr/local/bin/spamscanner
chmod +x /usr/local/bin/spamscanner
Commands
| Command
