SPAMPROBE(1)

okay bestie, so this is the SPAMPROBE(1) manual page — user commands section — and it's literally all about spamprobe. 🎀

💖 NAME 💖

spamprobe — A Bayesian spam filter. periodt. ✨

🌸 SYNOPSIS 🌸

spamprobe [options]  command  [files ...]

🦋 DESCRIPTION 🦋

So SpamProbe is a spam filter that relies on a Bayesian analysis of how often words show up in spam vs. non-spam emails that one individual person gets. The process is completely automatic, and it tailors itself to the kinds of emails each person receives. 💅

SpamProbe recognizes and decodes MIME attachments in quoted-printable and base64 encoding. Image attachments are considered as words that can signal a spam. By default, it ignores HTML tags for scoring purpose. no cap.

SpamProbe supports MBOX, MBX and Maildir mailbox formats. These formats are automatically detected for mailboxes used as parameters of SpamProbe commands. iconic.

spamprobe is designed to be used in mail delivery agents (MDAs) like procmail(1) or maildrop(1) to help in identifying spam. bestie behavior, honestly. 🫶

✨ OPTIONS ✨

The recognized options are — and yes, we're listing every single one:

• -a char — By default SpamProbe converts non-ascii characters (characters with the most significant bit set to 1) into the letter 'z'. This is useful for lumping all Asian characters into a single word for easy recognition. The -a option allows you to change the character to something else if you don't like the letter 'z' for some reason. 💅
• -c — Tells SpamProbe to create the database directory if it does not already exist. Normally SpamProbe exits with a usage error if the database directory does not already exist. 🙈
• -C number — Tells SpamProbe to assign a default, somewhat neutral, probability to any term that does not have a weighted (good count doubled) count of at least number in the database. This prevents terms which have been seen only a few times from having an unreasonable influence on the score of an email containing them.

The default value is 5. For example if number is 5 then in order for a term to use its calculated probability it must have been seen 3 times in good mails, or 2 times in good mails and once in spam, or 5 times in spam, or some other combination adding up to at least 5.

• -d [type:]directory — By default SpamProbe stores its database in a directory named .spamprobe under your home directory. The -d option allows you to specify a different directory to use. This is necessary if your home directory is NFS mounted for example.

The directory name can be prefixed with a special code to force SpamProbe to use a particular type of data file format. Defined types include:

• -d bdb:path — Forces the use of Berkeley DB data file.
• -d hash:path — Forces the use of an mmapped hash file.
• -d split:path — Forces the use of a hash file and ISAM file (may provide better precision than plain hash in some cases).

The hash: option can also specify a desired file size in megabytes before the path. For example -d hash:19:path would cause SpamProbe to use a 19 MB hash file. The size must be in the range of 1-100. The default hash file size is 16 MB. Because hash files have a fixed size and capacity they should be cleaned relatively often using the cleanup command (see below) to prevent them from becoming full or being slowed by too many hash key collisions.

Hash files provide better performance than Berkeley DB. However hash files do not store the original terms. Only a 32 bit hash key is stored with each term. This prevents a user from exploring the terms in the database using the dump command to see what words are particularly spammy or hammy. The default data file format is Berkeley BD (bdb). 💀

• -D directory — Tells SpamProbe to use the database in the specified directory (must be different than the one specified with the -d option) as a shared database from which to draw terms that are not defined in the user's own database. This can be used to provide a baseline database shared by all users on a system (in the -D directory) and a private database unique to each user of the system ($HOME/.spamprobe or -d directory).
• -g fieldname — Tells SpamProbe what header to look for previous score and message digest in. Default is X-SpamProbe. Field name is not case sensitive. Used by all commands except receive.
• -h — By default SpamProbe removes HTML markup from the text in emails to help avoid false positives. The -h option allows you to override this behavior and force SpamProbe to include words from within HTML tags in its word counts. Note that SpamProbe always counts any URLs in hrefs within tags whether -h is used or not. Use of this option is discouraged. It can increase the rate of spam detection slightly but unless the user receives a significant amount of HTML emails it also tends to increase the number of false positives. 🚩
• -H option — By default SpamProbe only scans a meaningful subset of headers from the email message when searching for words to score. The -H option allows the user to specify additional headers to scan. Legal values are all, nox, none, or normal. all scans all headers, nox scans all headers except those starting with X-, none does not scan headers, and normal scans the normal set of headers.

In addition to those values you can also explicitly add a header to the list of headers to process by adding the header name in lower case preceded by a plus sign. Multiple headers can be specified by using multiple -H options. For example, to include only the From and Received headers in your train command you could run SpamProbe as follows:

spamprobe -Hnone -H+from -H+received train

To process the normal set of headers but also add the SpamAssassin header X-SpamStatus you could run SpamProbe as follows:

spamprobe -H+x-spam-status train

• -l number — Changes the spam probability threshold for emails from the default (0.7) to number. The number must be a value between 0 and 1. Generally the value should be above 0.5 to avoid a high false positive rate. Lower numbers tend to produce more false positives while higher numbers tend to reduce accuracy.
• -m — Forces SpamProbe to use mbox format for reading emails in receive mode. Normally SpamProbe assumes that the input to receive mode contains a single message so it doesn't look for message breaks.
• -M — Forces SpamProbe to treat the entire input as a single message. This ignores From lines and Content-Length headers in the input.
• -o option — Enables special options by name. Currently the only special options are:
  • -o graham — Causes SpamProbe to emulate the filtering algorithm originally outlined in [A Plan For Spam].
  • -o honor-status-header — Causes SpamProbe to ignore messages if they have a Status: header containing a capital D. Some mail servers use this status to indicate a message that has been flagged for deletion but has not yet been purged from the file.

DO NOT use this option with the receive or train command in your procmailrc file! Doing so could allow spammers to bypass the filter. This option is meant to be used with the train-spam and train-good commands in scripts that periodically update the database.

• -o orig-score — Causes SpamProbe to use its original scoring algorithm that produces excellent results but tends to generate scores of either 0 or 1 for all messages.
• -o suspicious-tags — Causes SpamProbe to scan the contents of “suspicious” tags for tokens rather than simply throwing them out. Currently only font tags are scanned but other tags may be added to this list in later versions.
• -o tokenized — Causes SpamProbe to read tokens one per line rather than processing the input as mail format. This allows users to completely replace the standard SpamProbe tokenizer if they wish and instead use some external program as a tokenizer.

In this mode SpamProbe considers a blank line to indicate the end of one message's tokens and the start of a new message's tokens. SpamProbe computes a message digest based on the lines of text containing the tokens.

The -o option can be used multiple times and all requested options will be applied. Note that some options might conflict with each other in which case the last option would take precedence.

• -p number — Changes the maximum number of words per phrase. Default value is two. Increasing the limit improves accuracy somewhat but increases database size. Experiments indicate that increasing beyond two is not worth the extra cost in space.
• -P number — Causes SpamProbe to perform a purge of all terms with junk count less than or equal 2 after every number messages are processed. Using this option when classifying a large collection of spam can prevent the database from growing overly large at the cost of more processing time and possible loss of precision.
• -r number — Changes the number of times that a single word/phrase can occur in the top words array used to calculate the score for each message. Allowing repeats reduces the number of words overall (since a single word occupies more than one slot) but allows words which occur frequently in the message to have a higher weight. Generally this is changed only for optimization purposes.
• -R — Causes SpamProbe to treat the input as a single message and to base its exit code on whether or not that message was spam. The exit code will be 0 if the message was spam or 1 if the message was good.
• -s number — SpamProbe maintains an in memory cache of the words it has seen in previous messages to reduce disk I/O and improve performance. By default the cache will contain the most recently accessed 2,500 terms. This number can be changed using the -s option. Using a larger the cache size will cause SpamProbe to use more memory and, potentially, to perform less database I/O. A value of zero causes SpamProbe to use 100,000 as the limit which effectively means that the cache will only be flushed at program exit (unless you have really enormous mailbox files). The cache doesn't affect receive, dump, or export but has a significant impact on the others.
• -T — bestie this one is a whole vibe ✨ it makes SpamProbe spit out the top terms that go with every single message, on top of whatever it was already printing. Plays nice with find-good, find-spam, and score. 👑
• -v — the talkative queen 👑 drop it once on the command line and SpamProbe writes verbose info while it's processing. Drop it twice and it writes debugging info to stderr instead. Fr fr this is the move when you're debugging, or when you just gotta see which terms SpamProbe used to score each email. 🕵️‍♀️
• -V — prints the version and copyright info and then dips. that's it, that's the whole thing 💅
• -w number — changes how many of the most significant words/phrases SpamProbe uses to calculate the score for each message. Ngl this is generally only touched for optimization purposes. 🔧
• -x — okay so normally SpamProbe only uses a fixed number of top terms (whatever you set with the -w command line option) when it's scoring emails. The -x option lets that array get extended past the max size if there are more terms available with probabilities <= 0.1 or >= 0.9. periodt. 📈
• -X — an interesting little variation on the scoring settings 👀 It's equivalent to using -w5 -r5 -x, so generally only words with probabilites <= 0.1 or >= 0.9 get used, and word frequencies in the email count heavily towards the score. Tests have shown this setting tends to be safer (fewer false positives) and has higher recall (proper classification of spams previously scored as spam), although its predictive power isn't quite as good as the default settings.

⚠️ WARNING: This setting might work best with a fairly large corpus, it has not been tested with a small corpus so it might be very inaccurate with fewer than 1000 total messages. not me warning you twice, it's in the fine print bestie 😭

• -Y — assumes the traditional Berkeley mailbox format, ignoring any Content-Length: fields. 🗄️
• -7 — tells SpamProbe to ignore any characters with the most significant bit set to 1, instead of mapping them to the letter z. 🙈
• -8 — tells SpamProbe to store all characters even if their most significant bit is set to 1. no cap, all of them 💖

💖 COMMANDS 💖

ok so SpamProbe speaks a bunch of commands, bestie, and here they ALL are, no gatekeeping ✨

• spamprobe help [ command ] — call it with no args and it lists every valid command for you. Add one or more commands after the word help and it'll give you the full verbose tea on each one 🫖
• spamprobe create-db — if there's no database kicking around yet, SpamProbe tries to make one and then dips. perfect for bootstrapping a brand new install 🎀. tbh this command isn't strictly necessary because train-spam, train-good and auto-train will ALSO create a database if none exists — but some people just like making the db as its own separate installation step, and honestly? valid.
• spamprobe create-config — writes a fresh config file called spamprobe.hdl into the database directory (normally $HOME/.spamprobe). ⚠️ any config file already sitting there gets overwritten, so make a copy before you run this, fr fr. back it up or cry about it, your call 😭
• spamprobe receive [ filename... ] — tells SpamProbe to read its standard input (or a file named after receive) and score it using the current databases. once it's scored, the message gets classified as spam or non-spam and its word counts get written into the matching database. the score goes to stdout along with a single word, like this:

SPAM 0.9999999 595f0150587edd7b395691964069d7af
GOOD 0.0200000 595f0150587edd7b395691964069d7af

that string of hex digits after the score? that's the message's “MD5-digest”, a 128 bit number that uniquely IDs the message 👑 SpamProbe uses the digest to recognize messages it's already processed, so it can keep its word counts consistent if you reclassify something.

using the -T option also lists the terms used to produce the score, plus their counts (how many times each one showed up in the message).

• spamprobe train [ filename... ] — functionally identical to receive, except the database only gets modified if the message was “difficult” to classify. in practice this can cut database updates down to as little as 10% of the messages received 💅 iconic efficiency.
• spamprobe score [ filename... ] — like receive but the database does not get modified in any way. read only, respectful of boundaries ✨
• spamprobe summarize [ filename... ] — like score except it prints a short summary and score for each message. super handy when you're testing 🧚 using the -T option additionally lists the terms used to produce the score along with their counts (number of times they were found in the message).
• spamprobe find-spam [ filename... ] — like score except it prints a short summary and score for each message that's determined to be spam. great for testing 🔥 using -T additionally lists the terms used to produce the score along with their counts (number of times they were found in the message).
• spamprobe find-good [ filename... ] — like score except it prints a short summary and score for each message that's determined to be good. also great for testing 🌸 using -T additionally lists the terms used to produce the score along with their counts (number of times they were found in the message).
• spamprobe auto-train { SPAM|GOOD filename ... } ... — tries to build a database efficiently from all the named files. you can name one or more file of each type, and before each set of filenames you have to drop the word SPAM or GOOD to say what kind of mail is in the files that follow on the command line.

the case of the SPAM and GOOD keywords matters, ok? any number of filenames can go between the keywords. the command line format is super flexible — you can even use a find command in backticks to chew through whole directory trees of files. like:

spamprobe auto-train SPAM spams/* GOOD `find  hams -type f`

SpamProbe pre-scans the files to figure out how many emails of each type exist, then trains on hams and spams in a random sequence that balances the inflow of each type so the train command can do its best work. for example, if you had 400 hams and 400 spams, auto-train will generally process one spam, then one ham, etc. if you had 4000 spams and 400 hams then auto-train will generally process 10 spams, then one ham, etc. ⚖️

since this command will likely take a LONG time to run, it's often desirable to pair it with the -v option to see progress info as the messages get processed:

spamprobe -v auto-train SPAM spams/* GOOD hams/*

• spamprobe good [ filename... ] — scans each file (or stdin if you don't name a file) and reclassifies every email in it as non-spam. the databases get updated appropriately. messages previously classified as good (recognized via their MD5 digest) are ignored. messages previously classified as spam get reclassified as good 🦋
• spamprobe train-good [ filename... ] — functionally identical to the good command, except it only updates the database for messages that are either incorrectly classified (i.e. classified as spam) or are “difficult” to classify. in practice this can reduce database updates to as little as 10% of messages 👑
• spamprobe spam [ filename... ] — scans each file (or stdin if no file is specified) and reclassifies every email in it as spam. the databases get updated appropriately. messages previously classified as spam (recognized using their MD5 digest of message ids) are ignored. messages previously classified as good get reclassified as spam 🔥
• spamprobe train-spam [ filename... ] — functionally identical to the spam command, except it only updates the database for messages that are either incorrectly classified (i.e. classified as good) or are “difficult” to classify. in practice this can reduce database updates to as little as 10% of messages 💅
• spamprobe remove [ filename... ] — scans each file (or stdin if no file is specified) and removes its term counts from the database. messages that aren't in the database (recognized using their MD5 digest of message ids) are ignored ✨
• spamprobe cleanup [ junk_count [ max_age ] ] — scans the database and removes all terms with junk_count or less (default 2) which haven't had their counts modified in at least max_age days (default 7). you can specify multiple count/age pairs on a single command line, but you must specify both a count and an age for all but the last count. run this periodically so your database doesn't grow endlessly 🌱
• spamprobe purge [ junk_count ] — like cleanup but it forces the immediate deletion of ALL terms with total count less than junk_count (default is 2) no matter how long it's been since they were modified — i.e. even if they were just added today 😭 super handy right after classifying a big mailbox of historical spam or good email, to make room for the next batch.
• spamprobe purge-terms regex — like purge except it removes from the database all terms matching the specified regular expression. ⚠️ be careful with this one, bestie — it could remove way more terms than you expect. run dump with the same regex before running this command to see exactly what's about to get deleted. protect your peace 🙈
• spamprobe edit-term term good_count spam_count — lets you specifically set the good and spam counts of a term. whether this is truly useful is doubtful, but it's provided for completeness sake 🤷♀️
• spamprobe dump [ regex ] — prints the contents of the word counts database, one word per line, in human readable format: spam probability, good count, spam count, flags, and word, in columns separated by whitespace. when given, the regex argument limits output to matching tokens 🔍
• spamprobe tokenize [ filename ] — prints the tokens found in the file, one word per line, in human readable format: spam probability, good count, spam count, message count, and word, in columns separated by whitespace. terms are listed in the order they were encountered in the message. the standard unix sort command can be used to sort the terms however you like 🌈
• spamprobe export — like the dump command but prints the counts and words in a comma separated format, with the words surrounded by double quotes. this can be more useful for importing into some databases 💾
• spamprobe import — reads the specified files, which must contain export data written by the export command. the terms and counts from this file get added to the database. you can use this to convert a database from a prior version 👑

---

✨ EXAMPLES ✨

🧚 External Tokenizers

assuming you have a tokenizer called tokenize.pl, in your procmailrc file you could use:

SCORE=| tokenize.pl | /usr/bin/spamprobe -o tokenized train

🌸 Querying Mailboxes

to list all words from “most good” to “least good”, use this command:

spamprobe tokenize filename | sort -k 1n -k 2nr

to list all words from “most spammy” to “least spammy”, use this command:

spamprobe tokenize filename | sort -k 1nr -k 3nr

💅 Querying The Database

use spamprobe dump to get a human readable list of tokens in SpamProbe's database. Berkeley DB sorts terms alphabetically; piping the output into the standard unix sort(1) command can be used to sort the terms however you want 🦋

to list all words in SpamProbe's database from “most good” to “least good”, use this command:

spamprobe dump | sort -k 1n -k 2nr

to list all words from “most spammy” to “least spammy”, use this command:

spamprobe dump | sort -k 1nr -k 3nr

optionally you can specify a regular expression. if specified, SpamProbe will only dump terms matching that regex. for example:

spamprobe dump 'finance'
spamprobe dump '\\bfinance\\b'
spamprobe dump 'HSubject_.*finance'

🧹 DATABASE MAINTAINANCE 🧼

okay bestie this is the part nobody tells you about and then your disk fills up 💀 if you don't do anything, SpamProbe's databases will literally just keep growing and growing while it's classifying messages. so to yeet the old unused entries, you should run cleanup on the reg — easiest way is from cron(1). ✨

# daily at 00:03
#    remove entries with count <= 2 that haven't
#    been touched during the last 2 weeks from
#    spamprobe's database
3 0 * * * /usr/bin/spamprobe cleanup 2 14

orrrr you might wanna use a way higher count (like 1000 in this example) for terms that haven't been seen in roughly six months 🌙:

3 0 * * * /home/brian/bin/spamprobe cleanup 1000 180 2 14

so here's the thing about Berkeley DB — the database file will not actually shrink (it's giving "I'm not shrinking I'm thriving" 🙈) but the newly added terms can use the space that the removed terms left behind, so the file's growth should be significantly slower if you use this command. slay. 💅

if you actually DO wanna shrink the database, you can build a whole new one using the Berkeley DB utility programs db_dump(1) and db_load(1), or the SpamProbe import and export commands. like so:

cd ~
mkdir new.spamprobe
spamprobe export | spamprobe -d ~/new.spamprobe import
mv .spamprobe old.spamprobe
mv new.spamprobe .spamprobe

the -P option can also be used to limit the rate of growth of the database when you're importing a huge number of emails 📥. so for example, if you wanna classify 1000 emails and you want SpamProbe to purge rare terms every 100 messages, you'd use a command like:

spamprobe -P 100 good goodmailboxname

using -P slows down the classification but can save you from needing the export/import trick. just know that -P only makes sense when you're classifying a large number of messages. 🔥

and you may want to force a particular word to be very spammy or extremely good:

spamprobe edit-term xanax 0 1000000
spamprobe edit-term debian 10000000 0

lowkey at least pinning good terms tends to help spammers. 😭

---

🐛 BUGS

ngl this manual page is still work in progress. specifically it's missing a description of which headers are processed with -H normal, and how terms are generated from headers, plus a reference to the regex syntax that applies to the dump and purge-term commands. so yeah, it's a WIP bestie 🙈

---

📁 FILES

• ~/.spamprobe — when you don't specify otherwise with the -d directory option, SpamProbe stores its database files in this directory. it does not automatically create database directories, except when you explicitly ask it to with the -c command line flag or the create-db command. and listen — if your home directory is NFS mounted, use a different directory on a local disk, because Berkeley DB performance suffers badly over NFS. seriously. 💀
• ~/.spamprobe/spamprobe.hdl — configuration file for spamprobe. this file is optional. you can initialize it with all the default values by using the create-config command. 🎀

---

👀 SEE ALSO

procmail(1) , maildrop(1)

---

👑 AUTHOR

SpamProbe has been written by Brian Burton <bburton@users.sourceforge.net> and is published under the QPL (Qt Public License).

This manual page was compiled by Siggy Brentrup <bsb@debian.org> from the distributed one for the Debian GNU/Linux system but may be used by others. Permission is granted to copy, distribute and/or modify this document under the terms of the GPL version 2. 🫶

---

and that's a wrap on the whole page, bestie!! 🎉 this version is dated 01/29/2026, it's from the User commands section of the manual, and it lives under the name SPAMPROBE(1). go forth and filter, you icon, you absolute main character of mail filtering 🌈💖✨