|
Related Topics
This document describes basic syntax, variables, and functions for the rules.MailRules file. For an explanation of the default rules.MailRules document, see Default rules.MailRules file in our online help. For an indepth discussion of SMTP mail rules, see Using rules.Mailrules.
Syntax of the rules.MailRules file
This is the basic syntax of the rules.MailRules file:
<header> ":" 1*<sp> <condition> 1*<sp> <action>
The rule.MailRules script syntax for <header>
• <header> ":" 1*<sp> <condition> 1*<sp> <action>
• ::= <RFC822 header name> (for example, From)
• ::= <RFC2045 and RFC2183 attachment header name> (for example, Content-disposition)
• ::= '*' means any/all header
• ::= '^' means before any headers
• ::= '' (empty) means end of headers
• ::= '<' means links in HTML message body (<A> and <IMG>)
• ::= '>' means the text in the message body
• ::= '@' means at the end of each set of attachment headers
• ::= '.' means at the end of the message
The rule.MailRules script syntax for 1*
• <header> ":" 1*<sp> <condition> 1*<sp> <action>
indicates one or more
The rule.MailRules script syntax for <sp>
• <header> ":" 1*<sp> <condition> 1*<sp> <action>
indicates a space
• ::= ASCII SPACE or TAB
The rule.MailRules script syntax for <condition>
• <header> ":" 1*<sp> <condition> 1*<sp> <action>
• ::= ["NOT" 1*<sp>] <">simple expression<"> # supports * and ?, case insensitive
• ::= ["NOT" 1*<sp>] "regexp:" <">regular expression<"> # full regular expression, including tagged groups for replacement
• ::= ["NOT" 1*<sp>] "eregexp:" <">extended regular expression<"> # extended regular expression, including tagged groups for replacement
• ::= ["NOT" 1*<sp>] "eregexpi:" <">extended regular expression<"> # extended, case-insensitive regular expression, including tagged groups for replacement
• ::= "IF" *<sp> "(" <expression> ")"
The rule.MailRules script syntax for <expression>
• <expression> ::= ["("] <term> [<relational> <expression>] [")"]
• <term> ::= [<not>] <lhs> [<conditional> <lhs>]
• <not> ::= "NOT" | "!"
• <lhs> ::= <constant> [<mathop> <lhs>] | [<incr> | <decr>] <variable> [<mathop> <lhs>] | <function> | <expression>
• <constant> ::= <number> | <string>
• <number> ::= ["+" | "-"] <octal> | <decimal> | <hexadecimal>
• <octal> ::= "0" 1*<octal digit>
• <octal digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"
• <decimal> ::= 1*<decimal digit>
• <decimal digit> ::= <octal digit> | "8" | "9"
• <hexadecimal> ::= "0" ["X" | "x"] 1*<hex digit>
• <hex digit> ::= <decimal digit> | ["A" | "a"] | ["B" | "b"] | ["C" | "c"] | ["D" | "d"] | ["E" | "e"] | ["F" | "f"]
• <function> ::= "@' 1*<alpha> "(" [<arglist>] ")"
• <arglist> ::= <argument> ["," <arglist>]
• <argument> ::= <constant> | <variable>
• <mathop> ::= "+" | "-" | "*" | "/" | "&" | "^" | "%"
• <incr> ::= "++"
• <decr> ::= "--"
• <conditional> ::= "==" | "!=" | "|" | "&" | "~=" | "![=]~" | "=[=]~" | <lt> | <gt> | <le> | <ge>
• <lt> ::= "LT" | "<"
• <gt> ::= "GT" | ">"
• <le> ::= "LE" | "<="
• <ge> ::= "GE" | ">="
• <relational> ::= <and> | <or>
• <and> ::= "AND" | "&&"
• <or> ::= "OR" | "||"
The rules.MailRules script syntax for <action>:
• <header> ":" 1*<sp> <condition> 1*<sp> <action>
• ::= <set> *[1*<sp> AND 1*<sp> <set>] (see The set action)
• ::= "BCC" <local address>
• ::= "BLACKLIST" [<time in seconds>]
• ::= "DISCARDHEADER"
• ::= "DISCARDMESSAGE"
• ::= "DONE" # stop processing rules for this message
• ::= "INJECT" <"><header>":" <value><"> # (can include replacement groups, such as \1 and \2)
Example
: IF ($LowSpamMin <= $spamlevel && $spamlevel <= $LowSpamMax) INJECT "X-SPAM-Warning: Low"
This means that if the spam score at the end of a header test is between 'Low' and 'Medium', inject the header "X-SPAM-Warning: LOW" into the Internet header for this message.
• ::= "NDN" <errcode> [1*<sp> <string>] # implies DONE
Example
: IF ($spamlevel > $HighSpamMax && $XtremeCausesNDN == 1) NDN 550 "Sorry, your message has triggered a spam block, please contact the postmaster."
This means that if the spam score at the end of a header test is greater than 'High' and if you have chosen NDN, then NDN the message with an SMTP code of 550 and your choice of text, for example, "Sorry, your message has triggered a spam block, please contact the postmaster."
• ::= "REPLACE" <"><header>":" <value><"> # (can include replacement groups such as \1 and \2)
• ::= "SPAM" # shorthand for SET $priority=junk AND $machinegenerated=1
• ::= "STRIKE"
Example
: IF ($MedSpamMax < $spamlevel) SPAM
This means that if the spam score at the end of a header test is greater than 'medium' setting, mark the message as spam.
Variables in mail rules
The rules.MailRules file uses variables to enable features. Variables are placeholders, which can store some data for the duration of the processing of a single message. Variables can be tested using conditional expressions and assigned using the SET action. There are two kinds of variables in mail rules: Built-in and User-defined.
Built-in variables
Built-in variables are defined by the rules system and contain data about the message being processed. Built-in variables give mail rules access to information about the message being processed. Make sure you are familiar with built-in variables and you use them correctly or misleading or incorrect results will occur. For example, using $#To before the To: header has been received will return the value zero.
Some built-in variables can be SET to alter the attribute of a message:
• $MachineGenerated
Value
"1", "0"
Readonly/Readwrite
Readwrite
• $Priority
Value
"Normal", "Urgent", "Bulk", "Junk"
Readonly/Readwrite
Readwrite
• $IsNewsArticle
Value
"1", "0"
Readonly/Readwrite
Readonly
• $IsSpammer
Value
"1", "0"
Readonly/Readwrite
Readwrite
• $MessageID
Value
<contents of Message-ID header>
Readonly/Readwrite
Readonly
• $Subject
Value
<contents of subject header>
Readonly/Readwrite
Readwrite
• $From
Value
<contents of From: header>
Readonly/Readwrite
Readonly
• $Sender
Value
<contents of MAIL FROM:>
Readonly/Readwrite
Readonly
• $#To
Value
<number of To: recipients>
Readonly/Readwrite
Readonly
• $#Cc
Value
<number of Cc: recipients>
Readonly/Readwrite
Readonly
• $#Bcc
Value
<number of Bcc: recipients>
Readonly/Readwrite
Readonly
• $HaveReplyTo
Value
"1", "0"
Readonly/Readwrite
Readonly
• $HaveResentReplyTo
Value
"1", "0"
Readonly/Readwrite
Readonly
• $SenderIP
Value
<IP address of sending SMTP host>
Readonly/Readwrite
Readonly
• $MyIP
Value
<IP address of this host>
Readonly/Readwrite
Readonly
• $Authenticated
Value
"1", "0"
Readonly/Readwrite
Readonly
• $AuthCanRelay
Value
"1", "0"
Readonly/Readwrite
Readonly
• $InAttachment
Value
"1", "0" 1 if this rule is running while IS is processing attachment headers
Readonly/Readwrite
Readonly
• $#RCPTTO
Value
<number of RCPT TO addresses>
Readonly/Readwrite
Readonly
• $#BADRCPTTO
Value
<number of invalid RCPT TO addresses>
Readonly/Readwrite
Readonly
• $#URL
Value
<number of <A> links in the message>
Readonly/Readwrite
Readonly
• $#IMG
Value
<number of <IMG> links in the message>
Readonly/Readwrite
Readonly
• $#BODY
Value
<number of characters of text in the message body>
Readonly/Readwrite
Readonly
• $Form.GlobalPrefs.<FieldID>.<Format>
Value
Depends on the <FieldID>.<Format> combination
Readonly/Readwrite
Readonly
<FieldID> is a number representing a field in the Global Preferences form
<Format> is one of "Number", "String" or "Checkbox"
• $Form.Config.<FieldID>.<Format>
Value
Depends on the <FieldID>.<Format> combination
Readonly/Readwrite
Readonly
<FieldID> is a number representing a field on one of the Internet Services forms (for example, the Basic Internet Setup form)
<Format> is one of "Number", "String" or "Checkbox"
User-defined variables
User-defined variables are defined by putting $anytext into your rules. You should set a value before you use them. For example, using this rule
:IF ($myvar > 50) NDN 550 "Go Away"
without having created this next rule
^: IF (1) SET $myvar = 51
would cause your rule to never execute, since $myvar has no value.
Functions in mail rules
Functions give you access to built-in functionality of Internet Services, such as testing to see if an address is in your filter list. Functions are used in conditional expressions, and they return various values depending on the function. You cannot define your own functions. Here is a list of available functions and their syntax:
• @inblocklist(<string> or <variable> [, case]) #
case is "yes", "no", "true", "false". The default is "no".
returns TRUE (1) or FALSE (0)
• @inwordlist(<listname>, <string> or <variable> [, case])
# case is "yes", "no", "true", "false". The default is "no".
returns TRUE or FALSE
like @inblocklist, but you can use a separate list <listname> which must be named starting with "lists.". Optionally case-sensitive if the case argument is TRUE, YES, or a non-zero number.
• @wordcount(<listname>, <string> or <variable> [, case]) # case is "yes", "no", "true", "false". The default is "no".
returns the number of occurances of the words or phrases contained in the file/document <listname> that occur in <string>. Optionally case-sensitive if the case argument is TRUE, YES, or a non-zero number.
• @seenheader(<string> or <variable>)
returns TRUE or FALSE
• @istrustedip(<string> or <variable> [, listname])
returns TRUE or FALSE
The optional list <listname> must be named starting with "lists." and contain IP address values or masks (one per line).
• @istrustedaddress(<string> or <variable> [, listname])
returns TRUE or FALSE
The optional list <listname> must be named starting with "lists." and contain domain names (one per line). Wildcards in the domain names are not yet supported.
• @isspamip(<string> or <variable> [, listname])
returns TRUE or FALSE
The optional list <listname> must be named starting with "lists." and contain IP address values or masks (one per line).
• @isspamaddress(<string> or <variable> [, listname])
returns TRUE or FALSE
The optional list <listname> must be named starting with "lists." and contain domain names (one per line). Wildcards in the domain names are not yet supported.
• @islocaladdress(<string> or <variable>)
returns TRUE or FALSE
• @isrecipient(<string> or <variable>)
returns TRUE or FALSE
• @allcaps(<string> or <variable>)
returns TRUE or FALSE
• @punctcount(<string> or <variable>)
returns the number of punctuation characters in <string> or <variable>
punctuation characters are defined as any printable character that is not a space character or an alphanumeric character.
• @rcptto(<number> or <variable>)
returns a string that contains the Nth valid RCPT TO value, as requested by the argument (starting at zero).
These functions behave the same as Internet Services statements:
• @split(...)
• @substr(...)
• @length(...)
• @indexof(...)
• @upper(...)
• @lower(...)
• @rand()
The set action
The <set> action facilitates a number of boolean operators to accommodate the test portion of a rule:
• <set>
::= "SET" 1*<sp> <variable> *<sp> "=" *<sp> <value> *[ 1*<sp> "AND" 1*<sp> <variable> *<sp> "=" *<sp> <value> ]
Here are some examples:
• <not>
• ::= "NOT" | "!"
• <and>
• ::= "AND" | "&&"
• <or>
• ::= "OR" | "||"
• <gt>
• ::= "GT" | ">"
• <lt>
• ::= "LT" | "<"
• <ge>
• ::= "GE" | ">="
• <le>
• ::= "LE" | "<="
Syntax for the variable component of SET
The <variable> component of the <set> action allows for both predefined and custom described variables:
::= "SET" 1*<sp> <variable> *<sp> "=" *<sp> <value> *[ 1*<sp> "AND" 1*<sp> <variable> *<sp> "=" *<sp> <value> ]
Predefined variables are called <builtin> and custom described variables are called <alpha> for text only variables or <alphanum> for combined text numerical variables:
::= "$" ["{"] <builtin> or 1<alpha>*<alphanum_> ["}"]
Syntax for the value component of SET
The <value> component of the <set> action (subsection of the <action> script) defines system functions that return a value.
::= "SET" 1*<sp> <variable> *<sp> <assignop> *<sp> <value> *[ 1*<sp> "AND" 1*<sp> <variable> *<sp> <assignop> *<sp> <value> ]
<assignop> ::= "=" | "/=" | "*=" | "-=" | "+=" | "%=" # if value is a <string>, on;y = and += are valid
|
