.\" %Z%%M% %I% %E%; Copyright (c) 1990 - Sun Microsystems
.\"
.TH SORTMAIL 1 "21 Apr 1991"
.SH NAME
sortmail \- classify incoming mail
.SH SYNOPSIS
.B sortmail
[
.B \-v
] [
.B \-home
.I path
] [
.B \-mailbox
.I path
] [
.B \-mailrc
.I initfile
] [
.B \-sortmailrc
.I initfile
]
.I username
.SH DESCRIPTION
Create this \fB.forward\fP file in your home directory:

	"| /\fIpath\fP/sortmail \fIuser\fP"

Where "/\fIpath\fP/sortmail" is the full path where you installed
sortmail, and \fIuser\fP is your own userid.  The userid must be
specified because when mail arrives \fBsortmail\fP could be run as
root, daemon, or any number of other id's.

Once your \fB.forward\fP file is set up,
.B sortmail
will classify incoming mail according to the patterns in $HOME/.sortmailrc.
Your \fB.sortmailrc\fP file is similar to a news KILL file, but somewhat
more powerful.  You can discard mail, have it delivered to your mailbox,
have it filed into a folder, forward it to another address
or even pipe it through a shell command.

When \fBsortmail\fP starts up, it first reads your \fB.mailrc\fP file to
find the value of mail(1) variables that are also used by \fBsortmail\fP.
It then reads your \fB.sortmailrc\fP file for additional variable settings,
if any, and for search patterns.  (See below.)

.SH OPTIONS
.TP 15
.B \-v
Verbose.  A message is printed on /dev/console for every mail message.  A
second
.B \-v
causes a lot more information to be printed.
.TP 15
\fB\-home\fP \fIpath\fP
Set user's home directory, overriding the default taken from the user's
passwd entry.
.TP 15
\fB\-mailbox\fP \fIpath\fP
Set the user's system mailbox, overriding the default of
\fB/usr/spool/mail/\fP\fIuser\fP.
.TP 15
\fB\-mailrc\fP \fIpath\fP
Set the user's .mailrc file, overriding the default of
\fI~user/\fP\fB.mailrc\fP.
.TP 15
\fB\-sortmailrc\fP \fIpath\fP
Set the user's .sortmailrc file, overriding the default of
\fI~user/\fP\fB.sortmailrc\fP.

.SH SORTMAILRC FORMAT

Your .sortmailrc file is a series of lines in the form

	\fBset\fP \fIvariable=value\fP

and search patterns take the form

	/\fIregular-expression\fP/\fImodifier\fP:\fIcommand\fP

where \fIregular-expression\fP is any \fBed(1)\fP-style regular
expression, \fImodifier\fP is one of \fBt, f, s, h, a\fP, and
\fIcommand\fP is one of \fBm, j, v, f\fP\ \fIfile\fP, \fB+\fP\fIfile\fP,
or \fB|\fP\ \fIcommand\fP.

.SH MODIFIERS
.LP
These modifiers affect how the regular expression is applied to the
incoming mail.  The default is 's'.
.TP 6
.B s
Test the "Subject:\ " line of the incoming mail against the regular expression.
.TP 6
.B t
Test the "To:\ ", "Cc:\ " and "Apparently-To:\ " lines of the incoming
mail against the regular expression.
.TP 6
.B f
Test the "From:\ " line of the incoming mail against the regular expression.
.TP 6
.B h
Test the entire header of the incoming mail against the regular expression.
.TP 6
.B a
Test the entire incoming mail message against the regular expression.

.SH COMMANDS
.TP 10
.B m
Send the message to the user's mailbox.
.TP
\fBm\fP \fIaddress\fP
Forward the mail to the specified address.
.TP 10
.B j
Delete the message ("junk" it.)
.TP 10
\fBf\fP \fIfolder\fP
Save the message in the given mail folder.  \fIfolder\fP may be in
the formats ~/\fIpath\fP, /\fIabspath\fP, ~\fIuser/path\fP, or
+\fIname\fP.  The latter form expands to ~/\fIfolder/name\fP where
\fIfolder\fP is the value specified for the \fBfolder\fP variable
(default is "\fBfolders\fP".)
.TP 10
\fB+\fP\fIfolder\fP
Shorthand for "\fBf +\fP\fIfolder\fP".
.TP 10
\fB|\fP \fIcommand\fP
Pipe the mail message through the given \fIshell-command\fP.
sh(1) is used.

.SH VARIABLES
.LP
\fBsortmail\fP uses the following variables, which may be changed in
your \fB.mailrc\fP or \fB.sortmailrc\fP files.  Some variables may also
be set on the command line.
.TP 10
.B user
The user on behalf of whom \fBsortmail\fP is running.  This value must
be specified on the command line, but may be changed later.  It is used
to determine the user's home directory, among other things.
.TP 10
.B home
The user's home directory.  Used to find intialization files and the
user's \fIfolders\fP directory.  Default is ~\fIuser\fP.
.TP 10
.B mailbox
The user's mail box.  Default is \fB/usr/spool/mail/\fP\fIuser\fP.
.TP 10
.B mailrc
Full path of the user's \fB.mailrc\fP file.  There's no real point in
changing this.
.TP 10
.B sortmailrc
Full path of the user's \fB.sortmailrc\fP file.  There's no real point in
changing this.
.TP 10
.B mbox
Full path of the user's \fBmbox\fP file.  Not currently used by \fBsortmail\fP.
.TP 10
.B folder
The user's \fImail folders\fP directory.  Mail folders are identified by the
leading '+' in their name, and are stored in ~\fIuser/folder\fP/.
Default is "\fBfolders\fP".
.TP 10
.B default
Name of the file into which unclassifiable mail is sent.  The default
is \fImailbox\fP.  Another reasonable value might be "\fB+other\fP".
.TP 10
.B vacation
If set, mail to \fIuser\fP will also be piped through /usr/ucb/vacation.
.TP 10
.B logfilename
Messages printed with -v are sent to the specified log file.  Default is
/dev/console, or (if /dev/console cannot be opened) stderr.

.SH EXAMPLES
.LP
Here is a sample \fB.sortmailrc\fP file:
.LP
.RS
.nf
.ft B
set default=+other
/MAILER-DAEMON/f:+bounces
/falk/t:m
/bldg8/t:m
/joe/f:m
/scuba@sun/t:+scuba
/scuba/s:+scuba
/mwicks/f:j
/homework/t:m falk@kestrel
/jim@apple/f:| /home/falk/bin/fixjim
/^Precedence: junk/h:+other
.ft
.fi
.RE
.LP
In this example, the folder directory and other variables have whatever
values were specified in \fB.mailrc\fP.  Unclassifiable mail is sent to
the folder "+other".  Mail from "MAILER-DAEMON" is sent to the folder
"+bounces".  Mail to "falk" or "bldg8" or from my friend joe is sent
directly to my mailbox.  Mail to the scuba club or with "scuba" in the
subject line is sent to the "+scuba" folder.  Mail from mwicks is
thrown away without my ever seeing it.  Mail to the "homework" alias
is forwarded to my account on another machine.
Mail from my friend jim, who
formats his mail in a funny way is passed through a shell script which
cleans up his messages and appends them to my mailbox.  Mail messages
with "^Precedence:\ junk" anywhere in the header is filed in +other.

Note that the patterns are applied in the order given; it is important,
for example, that the "MAILER-DAEMON" pattern precede the "falk" pattern
so that mail from MAILER-DAEMON is filed in +bounces even if directed
to me personally.  On the other hand, mail from mwicks will be placed
in my mailbox if addressed to me personally, otherwise it will
be junked.

.SH NOTES
Remember that sortmail can be executed under any userid, depending on
who sent the mail, and whether or not it came from the local machine.
Because of this, you cannot depend on any user environment to be available,
especially environment variables and path.  All filenames and program
names should be specified as full paths, except that "~", "~user" and
"+folder" forms are understood.  The permissions of sortmail and every
directory along its path should be such that any user can run it.

If you pipe incoming mail through a program, that program should not
generate any output to stdout or stderr whatsoever.  If it does, that
output will be sent back to the originator of the mail as if the mail
had bounced.

.SH SEE ALSO
ed(1), mail(1)
.SH COPYRIGHT
 Copyright (c) 1990 by Sun Microsystems, Inc.
 Edward A. Falk (falk@sun.com)

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation.

regex.[ch] is covered by the GNU copyleft.