You must read this section to understand how the Spam package works. Do not skip, speed-read, or glance through this section.
Make sure you read the section on the spam.el sequence of
events. See Extending the Spam package.
To use the Spam package, you must first run the function
spam-initialize:
(spam-initialize)
This autoloads spam.el and installs the various hooks necessary
to let the Spam package do its job. In order to make use of the Spam
package, you have to set up certain group parameters and variables,
which we will describe below. All of the variables controlling the
Spam package can be found in the ‘spam’ customization group.
There are two “contact points” between the Spam package and the rest of Gnus: checking new mail for spam, and leaving a group.
Checking new mail for spam is done in one of two ways: while splitting incoming mail, or when you enter a group.
The first way, checking for spam while splitting incoming mail, is
suited to mail back ends such as nnml or nnimap, where
new mail appears in a single spool file. The Spam package processes
incoming mail, and sends mail considered to be spam to a designated
“spam” group. See Filtering Incoming Mail.
The second way is suited to back ends such as nntp, which have
no incoming mail spool, or back ends where the server is in charge of
splitting incoming mail. In this case, when you enter a Gnus group,
the unseen or unread messages in that group are checked for spam.
Detected spam messages are marked as spam. See Detecting Spam in Groups.
In either case, you have to tell the Spam package what method to use to detect spam messages. There are several methods, or spam back ends (not to be confused with Gnus back ends!) to choose from: spam “blacklists” and “whitelists”, dictionary-based filters, and so forth. See Spam Back Ends.
In the Gnus summary buffer, messages that have been identified as spam always appear with a ‘$’ symbol.
The Spam package divides Gnus groups into three categories: ham
groups, spam groups, and unclassified groups. You should mark each of
the groups you subscribe to as either a ham group or a spam group,
using the spam-contents group parameter (see Group Parameters). Spam groups have a special property: when you enter a
spam group, all unseen articles are marked as spam. Thus, mail split
into a spam group is automatically marked as spam.
Identifying spam messages is only half of the Spam package’s job. The second half comes into play whenever you exit a group buffer. At this point, the Spam package does several things:
First, it calls spam and ham processors to process the articles
according to whether they are spam or ham. There is a pair of spam
and ham processors associated with each spam back end, and what the
processors do depends on the back end. At present, the main role of
spam and ham processors is for dictionary-based spam filters: they add
the contents of the messages in the group to the filter’s dictionary,
to improve its ability to detect future spam. The spam-process
group parameter specifies what spam processors to use. See Spam and Ham Processors.
If the spam filter failed to mark a spam message, you can mark it yourself, so that the message is processed as spam when you exit the group:
Mark current article as spam, showing it with the ‘$’ mark
(gnus-summary-mark-as-spam).
Similarly, you can unmark an article if it has been erroneously marked as spam. See Setting Marks.
Normally, a ham message found in a non-ham group is not processed as
ham—the rationale is that it should be moved into a ham group for
further processing (see below). However, you can force these articles
to be processed as ham by setting
spam-process-ham-in-spam-groups and
spam-process-ham-in-nonham-groups.
The second thing that the Spam package does when you exit a group is
to move ham articles out of spam groups, and spam articles out of ham
groups. Ham in a spam group is moved to the group specified by the
variable gnus-ham-process-destinations, or the group parameter
ham-process-destination. Spam in a ham group is moved to the
group specified by the variable gnus-spam-process-destinations,
or the group parameter spam-process-destination. If these
variables are not set, the articles are left in their current group.
If an article cannot be moved (e.g., with a read-only backend such
as NNTP), it is copied.
If an article is moved to another group, it is processed again when
you visit the new group. Normally, this is not a problem, but if you
want each article to be processed only once, load the
gnus-registry.el package and set the variable
spam-log-to-registry to t. See Spam Package Configuration Examples.
Normally, spam groups ignore gnus-spam-process-destinations.
However, if you set spam-move-spam-nonspam-groups-only to
nil, spam will also be moved out of spam groups, depending on
the spam-process-destination parameter.
The final thing the Spam package does is to mark spam articles as expired, which is usually the right thing to do.
If all this seems confusing, don’t worry. Soon it will be as natural as typing Lisp one-liners on a neural interface… err, sorry, that’s 50 years in the future yet. Just trust us, it’s not so bad.