FILTER(1)

💖 FILTER(1) — the girlies' guide to filtering ur mail 💖

okay bestie, so this is a page from the General Commands Manual, and it's about a lil program called filter. sit down, hydrate, we're doing this 🫶

✨ NAME ✨

filter — filter incoming messages before adding to mailbox

like, it's the bouncer at the door of ur inbox. it checks the vibes of every message before letting it in 💅

---

✨ SYNOPSIS ✨

filter [-q] [-v] [-l] [-o output] [-f rules-file] [-m mailbox]
filter [-n] [-f rules-file]
filter [-r] [-o output] [-f rules-file]
filter [-c] [-s] [-o output] [-f rules-file]
filter [-c] [-S] [-o output] [-f rules-file]

five whole moods, pick ur fighter ✨

---

✨ DESCRIPTION ✨

so the tl;dr — filter is literally designed to sort ur incoming mail based on user preferences for various recognized headers. it logs a summary of messages filtered to a logfile. that's the vibe check. 📬

for the full tea, scroll down to the USAGE section, because there's a LOT there and it's honestly iconic.

---

✨ OPTIONS ✨

these are the flags filter understands, no cap:

• -c — Clear logs. if u use this flag, the log files get removed after being summarized by either -s or -S (peep below). so like, summarize first, THEN yeet 🗑️
• -f rules-file — get ur rules from the specified file instead of the default $HOME/.filter/filter-rules. custom rules, custom vibes 💅
• -l — Log actions only. do NOT log info about mailed messages. we're keeping it minimal bestie
• -n — Not really. output what would happen if given a message from standard input, but don't actually do anything with it. it's giving window shopping 🛍️
• -o file — redirect stdout messages to the specified file or device. logging of filter actions is not affected. (this was added to more gracefully deal with changes in the file system, since sendmail is quite picky about modes of files being redirected into.) picky king 🙄
• -m mailbox — override the compiled in definition of ur primary mailbox. this is disabled if filter is setgid. sorry bestie, security said no
• -q — Quiet. do not log filtering actions. shhhh 🤫
• -r — Rules. list the rules currently being used. receipts, basically 🧾
• -s — Summarize. list a summary of the message filtering log
• -S — same as -s but ALSO includes message-by-message information. extra detail, extra slay ✨
• -v — Verbose. give output on standard out for each message filtered. may be useful to set output to /dev/console or other logging device. (see -o). she's chatty and we love her 🗣️

---

✨ USAGE ✨

okay this is the main character section, lock in 🔥

filter uses a set of selection rules to process incoming mail messages. these rules are normally read in from $HOME/.filter/filter-rules. as soon as a rule matches something about the message, that rule is used, and no further action is taken — first match wins, periodt. the general format for a rule is:

if  (expression)  then  action

where expression is:

expression  ::=  { not }  condition  { and expression }

condition  ::=  field  =  stringvalue
           ::=  field  != stringvalue
           ::=  lines  relop  numvalue
or                 ::=  always

these further break down as:

field  ::=  from  |  subject  |  alphasubject  |  to  |  lines | sender

relop  ::=  =  |  !=  |  <  |  >  |  <=  |  >=

stringvalue  ::=  any  quoted  string

numvalue  ::=  any  integer  value

note: alphasubject is a transformed version of the subject line, where only alpha chars are preserved, and they are forced to lower case. it is then simpler to use a regular expression match across a wide variety of similar subjects. she's a glow-up of the subject line fr fr ✨

from matches any and all of the following headers:

"From " From: Reply-To: Sender:

so from is not just one thing, it's a whole friend group 👑

Action can be any of:

delete              (ignore this message; throw it away)
save  foldername    (put in 'foldername' for later)
savecopy foldername (save a copy AND put in my inbox)
execute  command    (pipe message to 'command')
executec command    (copy to inbox, AND pipe to 'command')
forward  address    (forward this message)
forwardc address    (forward this message, AND copy to inbox)
resend   address    (resend to new addr without change)
leave               (just put it in my inbox)
bounce              (say there's no such user)

an example of a rules file would be:

# I'll read this stuff later when I feel like it
if (from = "list@interest.org") then save "~/Mail/mailinglist"
# This mailing list actually has an x-mailing-list header
if (mailinglist = "smartlist@other.com") then save "~/Mail/otherlist"
# auto-archive this project's email, AND put in my current mailbox
if (subject = "strange project") then savecopy "~/Mail/proj-archive"
# If "make money" appears ANYWHERE in subject, upper/lowercase,
# delete the lousy spam
if ( subject = "make money" ) then delete
# This person no longer shares this virtual mailbox with me.
# Resend visibly as a "forwarded" message.
if (to = "partner") then forward "partner@new.address.com"
# If email for an old address comes to me, resend to new one.
# Note that the "envelope" will show my address, but the
# normal headers will not
if ( to = "old_address" ) then resend new@address.here"
# Special virtual headerline derived from normal subject line
# catches "multiple!!!wor+ds**here"
if ( alphasubject = "multiplewordshere" ) then delete
# If email for a special address comes to me, resend through
# a non-standard "special" mailer
if ( to = "special_address" ) then exec "/usr/lib/mailer special@addr"
#
# The rules file doesn't really need parentheses. Or even the 'if'.
# They are just traditional.
subject = "silly" then bounce

note that all filenames must be double-quoted — yes, all of them, no exceptions bestie 💅

for further information about the rules language, please see The Elm Filter Guide.

---

✨ MAINTAINER ✨

Philip Brown 👑

---

✨ FILES ✨

• $HOME/.filter/filter-rules — default rules file 📝
• $HOME/.filter/filterlog — a log of what has been done
• $HOME/.filter/filtersum — a summary of what has been done
• $MAIL — if you set this var, defines ur default mailbox 📮
• /etc/passwd — used to get users home directory

---

✨ SEE ALSO ✨

• The Elm Filter Guide (distributed with the source code) 📖
• mail(1), mailx(1), sendmail(1,8)

---

✨ COMMENTS ✨

ngl it could be smarter about pattern matching 😭 message body checks might be nice too. we're manifesting it bestie 🕯️

please note that this was historically bundled with the elm mail reader, but now can be found at http://www.bolthole.com/filter/ — glow up era 🌈

---

✨ BUG REPORTS TO ✨

filter@bolthole.com — tell them everything, they wanna know 💌

---

✨ COPYRIGHTS ✨

Copyright 1988-1992 by The USENET Community Trust
Derived from Elm 2.0,  Copyright 1986, 1987 by Dave Taylor

---

and that's the whole page, bestie 🎀 USENET Comm. Trust, 19 April 2004, page FILTER(1) — mwah, go filter ur mail, u got this 💖🦋✨