Spam Scanner documentation
Spam Scanner is a spam filter for Node.js and the command line, with its source code on GitHub. It reads a raw email message and decides whether it is spam, phishing, a scam or carries malware, in any language. It runs as a library, a command-line tool, a Postfix or Sendmail milterMail filter: a protocol from Sendmail, also used by Postfix, that lets a separate program inspect each message during the SMTP session., a Postfix content filter, a SpamAssassin-compatible spamdSpamAssassin's daemon. Its protocol is spoken by spamc, Exim, Haraka and other SpamAssassin clients. server, an HTTP API or a TCP server.
It is built by Forward Email for its own mail servers.
How a message is judged#
Each check adds or removes points. The total decides the outcome:
| Score | Action | What a mail server does |
|---|---|---|
| Below 5 | accept | Delivers the message |
| 5 to 14.9 | tag | Delivers it marked as spam |
| 15 and above | reject | Refuses it during the SMTP session |
Both thresholds can be changed. Every result lists the tests that fired, with their points and a reason, so a decision can always be explained.
The checks:
- A trained classifier reads the words of the message in any script, the shape of its links, its sender and its attachments. It ships trained on public datasets and learns from your own mail. How the classifier works
- Phishing checks catch lookalike domains (
paypa1.com,pаypal.comwith a Cyrillic а), links whose text shows one address and whose target is another, and display names that claim a brand. Phishing - Attachment checks find executables, executables renamed as documents, double extensions, right-to-left filename tricks, executables inside ZIP files, Office macros and active PDF content. ClamAVAn open-source antivirus engine. Its daemon, clamd, scans files sent over a socket. can scan attachments for viruses. Attachments
- Authentication: SPFSender Policy Framework: a DNS record listing the servers allowed to send mail for a domain., DKIMDomainKeys Identified Mail: a signature over a message, checked with a public key published in the sender's DNS., DMARCA DNS policy telling receivers what to do when mail claiming a domain fails SPF and DKIM alignment. and ARCAuthenticated Received Chain: signatures that carry authentication results across forwarding servers., when the client's IP address is known. Authentication
- DNS blocklists for the client's IP address and the domains in links, and Cloudflare's filtering resolvers for known malware and adult sites. Blocklists
- Rules for patterns no classifier needs to learn: the GTUBEGeneric Test for Unsolicited Bulk Email: a fixed string every spam filter treats as spam, for testing. test string, sextortion subjects, PayPal invoice scams, self-spoofing and instructions hidden for AI filters. Rules
- A language model, optional, gives a second opinion on close calls: a local model through OllamaA program that downloads and runs open language models on your own machine, with an HTTP API. or any OpenAI-compatible server, a decision model such as Cloudflare's Clef, or Claude, ChatGPT, Gemini and others. By default it returns a probability for each verdict in one step instead of writing an answer. Language models
Where to start#
- Getting started: install it and scan a first message.
- Command line: every command and option.
- Postfix and Sendmail: filter a mail server with the milter or a content filter.
- Other mail servers: Exim, Haraka, Dovecot, procmail and anything that can call an HTTP API.
- Training: teach it your own mail and measure the result.
- Language models: decisions and generation, measured accuracy and speed, decision models, providers, recommended open models, privacy and prompt injection.
- Languages: how it reads Chinese, Arabic, Thai and every other script.
- Forward Email: how Forward Email uses it, and upgrading from version 5 or 6.
- API reference and tests and scores.
- Security and privacy: what leaves the machine, and how to stop it.