SpamAssassin is configured using traditional UNIX-style configuration files, loaded from

# starts a comment.
If # is part of a rule or configuration option, it must be escaped with a backslash. i.e.: \#

Whitespace in the files is not significant.
Do not begin a line with whitespace as future versions will use this to indicate a multi-line rule definitions.

File and directory paths can use ~ to refer to the user's home directory.
No other shell-style path extensions such as globing or ~user/ are supported.

The following are permitted for site-wide (local.cf) and user-specific (user_prefs) files

It is important to consider the result of the SpamAssasin evaluation of a message.
If SA evaluates a message as spam it will modify the email, this may affect wether the email is delivered, held, rejected or discarded by a follow-on process.

If spam is only modified by SA and delivered, false positives (i.e. defining a nice message (ham) as spam ) has minor impact.
If a follow-on process moves spam to a holding directory, a false positive is more of a problem.
If a follow-on process rejects or discards spam without notifying the receipient, a false positive is a bad thing!
This type of processing is not recommended (previously known as required_hits )

A false negative (i.e. failure to declare a message as spam) can have detrimental effects if the message is an attack.

Scoring Options

Whitelist and Blacklist options

Basic Message Tagging Options

These are considered 'privileged'.
Only users running spamassassin from their procmailrc's or forward files, or sysadmins editing a file in /etc/mail/spamassassin, can use them.

If you add or modify a test, please be sure to run a sanity check afterwards by running spamassassin --lint. This will avoid confusing error messages, or other tests being skipped as a side-effect. spamd users cannot use them in their user_prefs files, for security and efficiency reasons, unless allow_user_rules is enabled.

ADMINISTRATOR SETTINGS

These settings considered 'more privileged' than the ones in the PRIVILEGED SETTINGS section. These can not be set from user_prefs when spamc/spamd is used.
However, all settings can be used by local programs run directly by the user.

version_tag string

Appended to the SA version in the X-Spam-Status header.
You should include it when modify your ruleset, especially if you plan to distribute it. string is your last name or your initials followed by a number which increases with each change.

The version_tag will be lowercased, and any non-alphanumeric or period character will be replaced by an underscore.
example:

  version_tag myrules1    # version=2.41-myrules1

test test (ok|fail) Some string to test against

Define a regression testing string. Multiple strings per symbolic test name are permitted.

These tests are only run as part of the test suite.

bayes_path /path/filename Default:~/.spamassassin/bayes

directory and filename for Bayes databases. Several databases will be created, with this as the base directory and filename, with _toks, _seen, etc. appended to the base. The default setting results in files called ~/.spamassassin/bayes_seen, ~/.spamassassin/bayes_toks, etc.

By default, each user has their own in their ~/.spamassassin directory with mode 700/600.
For system-wide SpamAssassin use, and to reduce disk space usage share this across all users.
Bayes is more effective with individual user databases.

bayes_file_mode Default:700

Permissions for files and directories, include eXecute mode bits. Files will not have any execute bits set

bayes_store_module Name::Of::BayesStore::Module

Alternate storage mechanism. It must be a published storage specification (see Mail::SpamAssassin::BayesStore). For example, Mail::SpamAssassin::BayesStore::SQL to use the generic SQL storage module.

bayes_sql_dsn DBI::databasetype:databasename:hostname:port

Connect string used for SQL based storage.

bayes_sql_username

bayes_sql_password

bayes_sql_username_authorized (0|1) Default:0

to call the services_authorized_for_username plugin hook in BayesSQL. If the hook does not determine that the user is allowed to use bayes or is invalid then then database will not be initialized.

By default the user is considered invalid until a plugin returns a true value.
If enabled without a proper plugin loaded, all users denied

The username passed into the plugin can be affected by bayes_sql_override_username.

user_scores_dsn DBI:databasetype:databasename:hostname:port

To load user scores from a SQL database, this will set the DSN used to connect. Example: DBI:mysql:spamassassin:localhost

To load user scores from an LDAP directory, this will set the DSN used to connect.
Write the DSN as an LDAP URL, the components being the host and port to connect to, the base DN for the seasrch, the scope of the search (base, one or sub), the single attribute being the multivalued attribute used to hold the configuration data (space separated pairs of key and value, just as in a file) and finally the filter being the expression used to filter out the wanted username.
The filter expression is being used in a sprintf statement with the username as the only parameter, thus is can hold a single __USERNAME__ expression. This will be replaced with the username.

Example: ldap://localhost:389/dc=koehntopp,dc=de?spamassassinconfig?uid=__USERNAME__

user_scores_sql_username username

user_scores_sql_password password

user_scores_sql_custom_query query

Create a custom SQL query to retrieve user scores and preferences.
Query should return two values, the preference name and value, in that order.
variables can be used as part of the query, which will be substituted for the values before the query is run:

_TABLE_: table where user scores and preferences are stored. Default: userpref
_USERNAME_: The current user's username.
_MAILBOX_: The portion before the @ from the current username.
_DOMAIN_: The portion after the @ from the current username, may be null.

The query must be contained on one line.
Default query:
SELECT preference, value FROM _TABLE_ WHERE username = _USERNAME_ OR username = '@GLOBAL' ORDER BY username ASC

Use global and then domain level defaults:
SELECT preference, value FROM _TABLE_ WHERE username = _USERNAME_ OR username = '@GLOBAL' OR username = '@~'||_DOMAIN_ ORDER BY username ASC

If global prefs should override user prefs:
SELECT preference, value FROM _TABLE_ WHERE username = _USERNAME_ OR username = '@GLOBAL' ORDER BY username DESC

user_scores_ldap_username

This is the Bind DN used to connect to the LDAP server.

Example: cn=master,dc=koehntopp,dc=de

user_scores_ldap_password

loadplugin PluginModuleName [/path/module.pm]

Load a perl module with the name used to create the plugin object itself.

/path/to/module.pm is the file to load, containing the module's perl code; if specified as a relative path, it is relative to the current configuration file.
If omitted, the module will be loaded using perl's search path (the @INC array).

See Mail::SpamAssassin::Plugin.

PREPROCESSING OPTIONS

TEMPLATE TAGS

The following tags can be used in certain options. They will be replaced by the corresponding value when they are used.

Some tags can take an argument (in parentheses). The argument is optional, and the default is shown below.

HAMMYTOKENS and SPAMMYTOKENS optional second argument specifies a format. See HAMMYTOKENS/SPAMMYTOKENS TAG FORMAT section.

HAMMYTOKENS/SPAMMYTOKENS TAG FORMAT

The HAMMYTOKENS and SPAMMYTOKENS tags have an optional second argument which specifies a format: _SPAMMYTOKENS(N,FMT)_, _HAMMYTOKENS(N,FMT)_ The following formats are available:

`ALL`	refers to the text of all the message's headers.
`ToCc`	refers to the contents of both the 'To' and 'Cc' headers.
`EnvelopeFrom`	is the address used in the 'MAIL FROM:' phase of the SMTP transaction that delivered this message.
`MESSAGEID`	is a symbol meaning all Message-Id's found in the message; some mailing list software moves the real 'Message-Id' to 'Resent-Message-Id' or 'X-Message-Id', then uses its own one in the 'Message-Id' header. The value returned for this symbol is the text from all 3 headers, separated by newlines.

User Preferences