====== Overview ======
Filters are normally edited in the user interface, in the window that appears when the File->Filters command is run.
Once defined, they are applied server-side by manitou-mdx to messages that enter the database.

{{:ui-filters-window.png?400}}

A filter is defined to apply to incoming or outgoing mail or both. Applying a filter consists of evaluating its **condition**, and if the result is true, doing the **actions** that are associated to it. If a filter has no action, it can be considered inactive. A condition is basically an **expression** that evaluates to true or false, optionally qualified with a unique name, that can be self-contained or refer to another expressions.

====== Expressions syntax ======
The expressions can be arbitrarily complex, with subparts combined with NOT, OR, AND boolean operators, references to other expressions, calls to built-in functions and evaluation of built-in operators. An expression may be named and refered to by its name from another expression.

<code>
expr := expr op expr
expr := (expr)
expr := NOT expr
op := OR | AND | contain[s] | eq[uals] | regmatches | ne
expr:= function(expr)
</code>

====== Functions ======
As of 0.9.11, built-in functions are:
  * **rawheader(string name)**: returns the non-decoded form of the first occurrence of the header line ''name''
  * **header(string name)**: returns the decoded form of the first occurrence of the header line ''name''
  * **headers()**: returns the entire headers of the message
  * **rawheaders()**: returns the entire non-decoded headers of the message
  * **recipients()**: returns all recipients (To, Cc, Bcc) separated by commas
  * **body()**: returns the text body of the message
  * **mailbox()**: returns the name of the mailbox to which the message belongs


====== Examples ======

These are examples of expressions that can be used in a filter (the filter actions being triggered when the expression evaluates to true).

  - From or to any address of a domain (dom.tld): <code>header("From") contains "@dom.tld" OR header("To") contains "@dom.tld"</code>
  - Spam detected by spamassassin:  <code>header("X-Spam-Flag") eq "YES"</code>
  - From a mailing list: <code>header("List-Post") eq "<mailto:dbd-pg@perl.org>"</code>
  - With a specific subject and sender: <code>header("subject") eq "Your Bugzilla buglist needs attention." AND header("From") eq "bugzilla-daemon@domain.tld"</code>