Description of the message filter in CrashMail II
       =================================================


Introduction
------------
The message filter makes it possible filter out messages that match a set of
criteria and perform a number of commands on them. All messages that are handled
by CrashMail are checked against the filter statements in the configuration.

Filter statements have this general syntax in the configuration:

FILTER <expression>
<command 1>
<command 2>
...

This file will start by describing how expressions work and what variables
you can use in them and then continue by describing the available commands.
This file relies heavily on examples to describe how the filter works.

Expressions
-----------
Expressions have this general syntax:

 <variable><operator><pattern>

CrashMail understands the operator "=" for all variable types expect text
variables and also "|"(substring search) for string and text variables.
Boolean variables can be used without an operator in which case "variable"
equals "variable=TRUE". You cannot have space characters around the operator,
CrashMail will not understand for example "FILEATTACH = TRUE".

A few examples:

 TONAME="Johan Billing"
 SUBJECT=CrashMail
 TEXT|"CrashMail"
 TOLOCALAKA

If the variable matches the pattern, the expression is TRUE and the commands
for the filter will be performed. You can also use NOT to negate a statement
and perform the commands if the expression is not true:

 NOT FROMNAME="AreaFix"

Expressions can be linked using AND and OR. Parentheses can be used to set
the evaluation order. (Default is evaluation from left to right.) Examples:

 TYPE=NETMAIL and TOLOCALAKA and TONAME=Raid
 TYPE=ECHOMAIL and (TONAME="Johan Billing" or TONAME="Billing Johan")
 TYPE=NETMAIL and NOT (FROMNAME=AreaFix or FROMNAME=Raid)

Variables
---------
String variables

 FROMNAME
 TONAME
 SUBJECT
 AREA
 TYPE
 SOURCE

 FROMNAME, TONAME and SUBJECT should be self-explanatory. AREA is the tagname
 of the area for echomail messages and for netmail messages it will be empty.
 TYPE can be either NETMAIL or ECHOMAIL. SOURCE describes where the message
 came from and can have these values:

  TOSSED      message was read from a *.pkt file
  EXPORTED    message was exported from a messagebase
  CRASHMAIL   message was generated by CrashMail (bounce messages, AreaFix
              responses etc)

 The "=" operator matches a variable against a pattern (see description of
 CrashMail's patterns in ReadMe.txt). "|" makes a substring search.

 Examples:

  FROMNAME=Johan*
  SOURCE=CRASHMAIL
  SUBJECT|AreaFix

Node variables

 FROMADDR
 TOADDR

 For netmail messages, these are the addresses found in the message header.
 For echomail messages, FROMADDR is taken from the Origin line and TOADDR
 will be empty.

 Node variables are matched against a node pattern using the "=" operator.

 Examples:

  FROMADDR="1:*/*.*"
  TOADDR="2:200/207.6"

Text variables

 TEXT
 KLUDGES

 TEXT is the message text without kludges and KLUDGES contains all the kludges
 (lines beginning with 0x01). You can only do substring searches on text
 variables using the "|" operator.

 Examples:

 TEXT|CrashMail
 KLUDGES|"TID: CrashMail"

Boolean variables

 FILEATTACH
 TOLOCALAKA
 FROMLOCALAKA
 TOLOCALPOINT
 FROMLOCALPOINT
 EXISTSCFG_FROMADDR
 EXISTSCFG_FROMBOSS
 EXISTSCFG_TOADDR
 EXISTSCFG_TOBOSS
 EXISTSNL_FROMADDR
 EXISTSNL_FROMBOSS
 EXISTSNL_TOADDR
 EXISTSNL_TOBOSS

 Boolean variables are always TRUE or FALSE. Boolean variables can be used
 either alone (variable and variable=TRUE is the same thing) or as
 variable=TRUE/FALSE.

 FILEATTACH will be TRUE if the message has an attached file.

 FROMLOCALAKA/TOLOCALAKA will be TRUE if the message is from/to one of the
 AKAs configured in the configuration file. FROMLOCALPOINT/TOLOCALPOINT will
 be TRUE if the message is from/to a point under one of the AKAs configured
 in the configuration file.

 EXISTSCFG_FROMADDR will be TRUE if the message is from an address configured
 as a NODE in the configuration file. EXISTSCFG_FROMBOSS is similar, but if
 the node is a point (x:y/z.p), CrashMail will look for the boss (x:y/z.0) in
 the node configuration instead. EXISTSCFG_TOADDR/EXISTSCFG_TOBOSS are similar,
 but for the destination address.

 EXISTSNL_* are similar to EXISTSCFG_*, but instead of looking for the nodes
 in the node configuration, the variable will only the TRUE if the node is
 found in the external nodelist.

 Examples:

 TOLOCALAKA or TOLOCALAKA=TRUE (equivalent)
 FROMLOCALPOINT=FALSE or NOT FROMLOCALPOINT (equivalent)

Commands
--------
TWIT

 Don't import the message. The message will be sent to downlinks as usual.

 Example:

  FILTER TYPE=ECHOMAIL and FROMNAME="Hubba Hopp"
  TWIT

KILL

 Completely discard the message.

 Example:

  FILTER SOURCE=CRASHMAIL
  KILL

COPY <area>

 Write a copy of the message to a local area. The local area needs to be
 configured in the configuration using LOCALAREA.

 Example:

  FILTER SOURCE=TOSSED and TYPE=ECHOMAIL and TONAME="Johan Billing"
  COPY PERSONAL_MESSAGES

EXECUTE <command>

 Executes an external command. The following codes can be used in the command:

  %r  RFC-style with Fidonet addresses. Name of a file that contains a
      message in a text format similar to that used for e-mail messages on
      the internet, but addresses are still in x:x/x.x@domain format.
  %R  RFC-style with RFC-style addresses. Name of a file that contains a
      message in a text format similar to that used for e-mail messages on
      the internet, but addresses are in name@pX.fX.nX.zX.domain format.
  %m  Name of a file that contains the message as a *.msg file
  %a  Area name (echomail only, will be empty for netmail areas)
  %f  From name
  %o  Originating node
  %t  To name
  %d  Destination node
  %s  Subject
  %x  Date and time of the message

 CrashMail will react differently depending on the exit code of the executed
 command:

  0     The message is not imported
  10    The message is imported
  20    CrashMail aborts

 Example:

  FILTER TYPE=NETMAIL and TOLOCALAKA and TONAME="Raid"
  EXECUTE "raid %r"

WRITELOG <message>

 Writes a message to the logfile (loglevel 1). The same %-codes as for the
 EXECUTE command can be used here as well except for %r, %R and %m.

 Example:

  FILTER TYPE=ECHOMAIL and SOURCE=TOSSED
  WRITELOG "From: %f Subj: %s Area: %a"

WRITEBAD <reason>

 Writes the message to the BAD area with <reason> specified as the reason. The
 message is not deleted unless you also use the KILL command.

  FILTER TYPE=NETMAIL and NOT EXISTSNL_TOBOSS
  WRITEBAD "Warning: Destination not in nodelist, message might not arrive"

BOUNCEMSG <message>
BOUNCEHEADER <message>

 These commands writes an error message to the sender of the filtered message.
 BOUNCEMSG includes a full copy of the original message and BOUNCEHEADER only
 includes the message header. In the message to the sender, you can use the
 same %-codes as for the EXECUTE command except for %r, %R and %m. The message
 will not be deleted unless you also use the KILL command.

 Example:

  FILTER TYPE=NETMAIL and not TOLOCALAKA and not EXISTSCFG_TOADDR
  BOUNCEMSG "Destination node %d does not exist, message can not be delivered"
  KILL

REMAPMSG <new name> <destination pattern>

 This command can change the destination name and node of a netmail message. If
 the new name is "*", the old name will be kept.

 Examples:

  FILTER TYPE=NETMAIL and TOLOCALAKA and TONAME="Johannes"
  REMAPMSG "Johannes Nilsson" 2:200/2075

  FILTER TYPE=NETMAIL and TOADDR=2:999/*.*
  REMAPMSG "*" 2:200/*.*

Additional examples
-------------------
Copy all talk about me to a special area:

 FILTER TYPE=ECHOMAIL and SOURCE=TOSSED and TEXT|billing
 COPY BILLING_DISCUSSIONS

Keep a copy of all sent netmails:

 FILTER TYPE=NETMAIL and SOURCE=EXPORTED
 COPY SENT_NETMAILS

Log all routed messages:

 FILTER TYPE=NETMAIL and SOURCE=TOSSED
 WRITELOG "Routed message from %f (%o) to %t (%d)"

Search all messages for a string:

 FILTER TEXT|CrashMail
 COPY CRASHMAIL_DISCUSSIONS

Make customized bounce messages:

 FILTER TYPE=NETMAIL AND NOT EXISTSNL_TOBOSS
 BOUNCEMSG "Destination node %d does not exist in nodelist, your message cannot be delivered"
 KILL

Make it possible to inspect all messages generated by CrashMail:

 FILTER SOURCE=CRASHMAIL
 COPY CRASHMAIL_MESSAGES