SPAMASSASSIN-RUN(1)

📦
version 4.0.2 · 9 versions
, in alpine 3.23

💌 SPAMASSASSIN-RUN(1) 💌

okay so this is the manual page for spamassassin-run, straight out of User Contributed Perl Documentation, and bestie, it's literally the gateway to the whole SpamAssassin vibe. it's a simple front-end filtering script for SpamAssassin, and by the end of this you're gonna be filtering spam like it's main character energy. let's go ✨

🎀 NAME 🎀

spamassassin — the simple front-end filtering script for SpamAssassin. that's it, that's the name, she's iconic 💅

🦋 SYNOPSIS 🦋

okay so here's the group chat of every way you can call her:

spamassassin [options] [ < mailmessage | path ... ]

spamassassin -d [ < mailmessage | path ... ]

spamassassin -r [ < mailmessage | path ... ]

spamassassin -k [ < mailmessage | path ... ]

spamassassin -W|-R [ < mailmessage | path ... ]

and now the options, because there are so many and every single one matters:

  • -L, --local — local tests only, no online tests. keeping it cozy and offline 🏠
  • -r, --report — report the message as spam. snitch on it, fr fr 📢
  • -k, --revoke — revoke the message as spam. nvm bestie, our bad 🙈
  • -d, --remove-markup — remove spam reports from a message. cleanup era 🧹
  • -C path, --configpath=path, --config-file=path — the path to the standard configuration dir 📁
  • -p prefs, --prefspath=file, --prefs-file=file — set the user preferences file. your personal settings, your rules 💖
  • --siteconfigpath=path — path for site configs (default: /etc/mail/spamassassin) 🗂️
  • --cf='config line' — one more line of configuration, right there on the command line ⚡
  • --pre='config line' — one more line of .pre config, and yup, it gets prepended to the configuration 👑
  • -x, --nocreate-prefs — don't create the user preferences file. no new files today 🚫
  • -e, --exit-code — exit with a non-zero exit code if the tested message was spam. so scripts can tell 👀
  • --mbox — read in messages in mbox format 📬
  • --mbx — read in messages in UW mbx format 📮
  • -t, --test-mode — pipe the message through and add an extra report to the bottom 🧪
  • --lint — lint the rule set: report syntax errors. spa day for your rules ✨
  • -W, --add-to-welcomelist — add addresses in the mail to the persistent address welcomelist 💚
  • --add-to-blocklist — add addresses in the mail to the persistent address blocklist ⛔
  • -R, --remove-from-welcomelist — remove all addresses found in the mail from the persistent address list 🫶
  • --add-addr-to-welcomelist=addr — add addr to the persistent address welcomelist ✅
  • --add-addr-to-blocklist=addr — add addr to the persistent address blocklist ❌
  • --remove-addr-from-welcomelist=addr — remove addr from the persistent address welcomelist 🧚
  • --remove-addr-from-blocklist=addr — remove addr from the persistent address blocklist 💀
  • -u username, --username=username — override the username taken from the runtime environment, used with SQL 🗄️
  • -4, --ipv4only, --ipv4-only, --ipv4 — use IPv4, disable use of IPv6 for DNS etc. old school but reliable 🌈
  • -6 — use IPv6, disable use of IPv4 where possible. future era 🚀
  • --progress — print a progress bar. we love a little visual 🍓
  • -D, --debug [area,...] — print debugging messages. peek behind the curtain 🔍
  • -V, --version — print the version 🏷️
  • -h, --help — print the usage message. when in doubt, ask her 🫶

🌸 DESCRIPTION 🌸

okay so spamassassin is a simple front-end filter for SpamAssassin. simple in the way that a perfectly executed fit is "simple", ykwim? 💅

using the SpamAssassin rule base, it runs a wide range of heuristic tests on mail headers and body text to identify "spam" — also known as unsolicited bulk email, which is literally the worst genre of email ever. once it's identified, the mail gets tagged as spam for later filtering using the user's own mail user-agent application. slay 🎀

the default tagging operations that take place are detailed in "TAGGING" in spamassassin — that's where the receipts live, bestie, go read it.

so by default, message(s) are read in from STDIN (< mailmessage), or from specified files and directories (path ...). STDIN and files are assumed to be in file format, with a single message per file — one message per file, that's the rule 📄. directories are assumed to be in a format where each file in the directory contains only one message. and listen, directories are not recursed, and filenames containing whitespace or beginning with . or , are skipped. so if your file is named my spam.txt or .hidden or ,comma, she's not seeing it, periodt 🙈. the options --mbox and --mbx can override the assumed format, so check the appropriate OPTION info below.

files compressed with gzip/bzip2/xz/lz4/lzip/lzo are uncompressed automatically. so thoughtful of her 🧚. see "Mail::SpamAssassin::ArchiveIterator" for more details.

⚠️ ok important warning bestie: SpamAssassin is not designed to scan huge messages. messages larger than ~10-20MB should not be fed to SpamAssassin, because memory consumption will increase rapidly and that's not a vibe, that's a crash waiting to happen 😭

okay that's the setup, and there's so much more coming — the deep dive continues, so stay with me 🦋

✨ OPTIONS ✨

okay bestie, here's the full menu of flags — every single one, no skips 💅

  • -e, --error-code, --exit-code — bail out with a non-zero error code if the message gets flagged as spam. that's it, that's the whole vibe 🫶
  • -h, --help — prints the help message and dips. iconic behavior honestly ✨
  • -V, --version — prints the version and exits. quick little flex 💖
  • -t, --test-mode — test mode, queen. pipes the message through and adds the extra report. 🎀 heads up tho: the report text assumes the message is spam, since in normal use you'd only ever see it in that case — so don't trust the wording, pay attention to the score instead 👑

and if you run this together with -d, the message will first have SpamAssassin markup removed before being tested. teamwork! 🧚

if the message contains SpamAssassin markup, that markup gets stripped out automatically before submission. the support modules for DCC, Pyzor, and Razor must be installed for spam to be reported to each service. and SpamCop reports will have greater effect if you register and set the spamcop_to_address option, so like… do that 💅

the message will also be submitted to SpamAssassin's learning systems; currently this is the internal Bayesian statistical-filtering system (the BAYES rules). (note: if you only want to perform statistical learning, and do not want to report mail to third-parties, you should use the sa-learn command directly instead. iykyk 🦋)

  • -k, --revoke — revoke this message. this revokes the mail message read from STDIN from various spam-blocker databases. currently, these are Vipul's Razor.

revocation support for the Distributed Checksum Clearinghouse, Pyzor, and SpamCop is not currently available 😭 that's just how it is rn.

if the message contains SpamAssassin markup, the markup will be stripped out automatically before submission. the support modules for Razor must be installed for spam to be revoked from the service.

the message will also be submitted as 'ham' (non-spam) to SpamAssassin's learning systems; currently this is the internal Bayesian statistical-filtering system (the BAYES rules). (note: if you only want to perform statistical learning, and do not want to report mail to third-parties, you should use the sa-learn command directly instead. same note as before, still true 🌸)

  • --lint — syntax check (lint) the rule set and configuration files, reporting typos and rules that do not compile correctly. exits with 0 if there are no errors, or greater than 0 if any errors are found. the vibe check for your config fr fr ✅
  • -W, --add-to-welcomelist — previously --add-to-whitelist, which will work interchangeably until 4.1. 📝

adds all email addresses, in the headers and body of the mail message read from STDIN, to a persistent address welcomelist. note that you must be running spamassassin or spamd with a persistent address list plugin enabled for this to work. no plugin, no party 🙈

  • --add-to-blocklist — previously --add-to-blacklist, which will work interchangeably until 4.1.

adds all email addresses, in the headers and body of the mail message read from STDIN, to the persistent address blocklist. note that you must be running spamassassin or spamd with a persistent address list plugin enabled for this to work. 🚫

  • -R, --remove-from-welcomelist — previously --remove-from-whitelist, which will work interchangeably until 4.1.

removes all email addresses, in the headers and body of the mail message read from STDIN, from a persistent address list. STDIN must contain a full email message, so to remove a single address you should use --remove-addr-from-welcomelist instead. important distinction bestie 💀

note that you must be running spamassassin or spamd with a persistent address list plugin enabled for this to work.

  • --add-addr-to-welcomelist — previously --add-addr-to-whitelist, which will work interchangeably until 4.1.

adds the named email address to a persistent address welcomelist. note that you must be running spamassassin or spamd with a persistent address list plugin enabled for this to work. 💖

  • --add-addr-to-blocklist — previously --add-addr-to-blacklist, which will work interchangeably until 4.1.

adds the named email address to a persistent address blocklist. note that you must be running spamassassin or spamd with a persistent address list plugin enabled for this to work.

  • --remove-addr-from-welcomelist — previously --remove-addr-from-whitelist, which will work interchangeably until 4.1.

removes the named email address from a persistent address welcomelist. note that you must be running spamassassin or spamd with a persistent address list plugin enabled for this to work. 🫶

  • --remove-addr-from-blocklist — removes the named email address from a persistent address blocklist. note that you must be running spamassassin or spamd with a persistent address list plugin enabled for this to work. (no "previously" note on this one, she's new here ✨)
  • -u username, --username=username — if specified, this username will override the username taken from the runtime environment. you can use this option to specify users in a virtual user configuration when using SQL as the Bayes backend. 🗂️
NOTE: this option will not change to the given username, it will only attempt to act on behalf of that user. because of this you will need to have proper permissions to be able to change files owned by username. in the case of SQL this generally is not a problem. main character energy but with the right permissions, yk? 👑
  • --ipv4only, --ipv4-only, --ipv4 — do not use IPv6 for DNS tests. normally, SpamAssassin will try to detect if IPv6 is available, using only IPv4 if it is not. use this if the existing tests for IPv6 availability produce incorrect results or crashes. 💀 three aliases, one job.
  • -L, --local — do only the "local" tests, the ones that do not require an internet connection to operate. normally, SpamAssassin will try to detect whether you are connected to the net before doing these tests anyway, but for faster checks you may wish to use this. 🏠
note: SpamAssassin's network rules are run in parallel. this can cause overhead in terms of the number of file descriptors required if --local is not used; it is recommended that the minimum limit on fds be raised to at least 256 for safety. protect your fds bestie 😭
  • -d, --remove-markup — remove SpamAssassin markup (the "SpamAssassin results" report, X-Spam-Status headers, etc.) from the mail message. the resulting message, which will be more or less identical to the original, pre-SpamAssassin input, will be output to STDOUT. 🧼
(note: the message will not be exactly identical; some headers will be reformatted due to some features of the Mail::Internet package, but the body text will be.) don't come for me about the headers 💅
  • -C path, --configpath=path, --config-file=path — use the specified path for locating the distributed configuration files. ignore the default directories (usually /usr/share/spamassassin or similar). 📁
  • --siteconfigpath=path — use the specified path for locating site-specific configuration files. ignore the default directories (usually /etc/mail/spamassassin or similar). 🗄️
  • --cf='config line' — add additional lines of configuration directly from the command-line, parsed after the configuration files are read. multiple --cf arguments can be used, and each will be considered a separate line of configuration. for example:
spamassassin -t --cf="body NEWRULE /text/" --cf="score NEWRULE 3.0"

obsessed with this one actually 🔥

  • --pre='config line' — add additional lines of .pre configuration directly from the command-line, parsed before the configuration files are read. multiple --pre arguments can be used, and each will be considered a separate line of configuration. for example:
spamassassin -t --pre="loadplugin Mail::SpamAssassin::Plugin::Foobar"

before vs after, know the difference 💖

  • -p prefs, --prefspath=prefs, --prefs-file=prefs — read user score preferences from prefs (usually $HOME/.spamassassin/user_prefs). 🌸
  • --progress — prints a progress bar (to STDERR) showing the current progress. this option will only be useful if you are redirecting STDOUT (and not STDERR). in the case where no valid terminal is found this option will behave very much like the --showdots option in other SpamAssassin programs. little loading bar moment ✨
  • -D [area,...], --debug [area,...] — produce debugging output. if no areas are listed, all debugging information is printed. diagnostic output can also be enabled for each area individually; area is the area of the code to instrument. for example, to produce diagnostic output on bayes, learn, and dns, use:
spamassassin -D bayes,learn,dns

use an empty string (-D '') to indicate no areas when the next item on the command line is a path, to prevent the path from being parsed as an area. sneaky! 😭

higher priority informational messages that are suitable for logging in normal circumstances are available with an area of info.

for more information about which areas (also known as channels) are available, please see the documentation at:

L<https://wiki.apache.org/spamassassin/DebugChannels>

go read the wiki bestie 🦋

  • -x, --nocreate-prefs — disable creation of user preferences file. sometimes you just don't want the file, periodt. 🚫
  • --mbox — specify that the input message(s) are in mbox format. mbox is a standard Unix message folder format. 📬
  • --mbx — specify that the input message(s) are in UW .mbx format. mbx is the mailbox format used within the University of Washington's IMAP implementation; see "https://en.wikipedia.org/wiki/UW_IMAP". 🏫

🌈 SEE ALSO 🌈

sa-learn(1) spamd(1) spamc(1) Mail::SpamAssassin::Conf(3) Mail::SpamAssassin(3)

the whole friend group honestly 🫶

🧚 PREREQUISITES 🧚

Mail::SpamAssassin — that's the one, gotta have it 💜

💀 BUGS 💀

see <https://bz.apache.org/SpamAssassin/> — yes there's a bug tracker, yes you should use it, no don't just suffer in silence 😭

👑 AUTHORS 👑

The SpamAssassin(tm) Project <https://spamassassin.apache.org/>

SpamAssassin is distributed under the Apache License, Version 2.0, as described in the file LICENSE included with the distribution.

k that's the whole page bestie, you're officially informed 💅✨ this was perl v5.42.0, dated 2025-08-31, page SPAMASSASSIN-RUN(1) — go forth and filter some spam, you absolute icon 🦋🌸💖

📦 where this page comes from