For the most up-to-date information you are referred to the Dovecot wiki:

 http://wiki.dovecot.org/LDA/Sieve/Dovecot

 Compiling

 ---------

 Compilation is identical among the CMUSieve and the new Sieve plugin. Use 

 --with-dovecot=<path> to point to dovecot-config file's directory. There are two

 possibilities where this could exist:

   1. If you configured Dovecot with --enable-header-install, you'll have 

      dovecot-config installed in $prefix/lib/dovecot/ directory. For example:

      ./configure --with-dovecot=/usr/local/lib/dovecot

      make

      sudo make install

   2. Compiled Dovecot sources' root directory. For example:

      ./configure --with-dovecot=../dovecot-1.2.0/

      make

      make install

 If you downloaded the sources using Mercurial, you will need to execute 

 `./autogen.sh' first to build the automake structure in your source tree. This 

 process requires autotools and libtool to be installed.

 Dovecot Sieve includes several command line tools to perform tasks such as

 compile, verify and debug Sieve scripts (refer to the README file for more

 information). These are built only if you use method 2, because they need to

 link Dovecot's .a libraries, which can only be found from Dovecot's source tree

 (make install doesn't install them).

 Basic Configuration

 -------------------

 To use Sieve, you will first need to make sure you are using Dovecot's deliver

 for delivering incoming mail to users' mailboxes. Then, you need to enable the

 Sieve plugin in your dovecot.conf:

 protocol lda {

 ..

   # Support for dynamically loadable plugins. mail_plugins is a space separated

   # list of plugins to load.

   mail_plugins = sieve # ... other plugins like quota

 }

 The sieve plugin recognizes the following configuration options in the plugin

 section of the config file (default values are shown if applicable):

 sieve = ~/.dovecot.sieve

   The path to the user's main active script. 

 sieve_global_path

   A path to a global sieve script file, which gets executed ONLY if user's 

   private Sieve script doesn't exist, e.g. /var/lib/dovecot/default.sieve. Be 

   sure to pre-compile this script manually using the sievec command line tool,

   as explained in the README file. 

 sieve_global_dir =

   Directory for :global include scripts for the include extension. 

 sieve_dir = ~/

   Directory for :personal include scripts for the include extension. 

 sieve_extensions =

   Which Sieve language extensions are available to users. By default, all 

   supported extensions are available, except for deprecated extensions or those 

   that are still under development. Some system administrators may want to 

   disable certain Sieve extensions or enable those that are not available by 

   default. Supported extensions are listed on this page. This setting can use 

   '+' and '-' to specify differences relative to the default. For example 

   `sieve_extensions = +imapflags' will enable the deprecated imapflags extension

   in addition to all extensions enabled by default. 

 sieve_subaddress_sep = +

   The separator that is expected between the :user and :detail address parts 

   introduced by the subaddress extension. This may also be a sequence of

   characters (e.g. '--'). The current implementation looks for the separator

   from the left of the localpart and uses the first one encountered. The :user

   part is left of the separator and the :detail part is right.

 For example:

 plugin {

 ...

    # The location of the user's active script:

    sieve = ~/.dovecot.sieve

    # If the user has no personal active script (i.e. if the file 

    # indicated in sieve= does not exist), use this one:

    sieve_global_path = /var/lib/dovecot/sieve/default.sieve

    # The include extension fetches the :personal scripts from this 

    # directory. When ManageSieve is used, this is also where scripts 

    # are uploaded.

    sieve_dir = ~/sieve

    # The include extension fetches the :global scripts from this 

    # directory.

    sieve_global_dir = /var/lib/dovecot/sieve/global/

 }

 Configurable Limits

 -------------------

 sieve_max_script_size = 1M

   The maximum size of a Sieve script. The compiler will refuse to compile any

   script larger than this limit. 

 sieve_max_actions = 32

   The maximum number of actions that can be performed during a single script

   execution.

 sieve_max_redirects = 4

   The maximum number of redirect actions that can be performed during a single

   script execution.

 A value of 0 for these settings means that the limit is not enforced. 

 Per-user Sieve script location

 ------------------------------

 By default, the Dovecot Sieve plugin looks for the user's Sieve script file in

 the user's home directory (~/.dovecot.sieve). This requires that the home 

 directory is set for the user.

 If you want to store the script elsewhere, you can override the default using 

 the sieve setting, which specifies the path to the user's script file. This can 

 be done in two ways:

  1. Define the sieve setting in the plugin section of dovecot.conf.

  2. Return sieve extra field from userdb extra fields. 

 For example, to use a Sieve script file named <username>.sieve in 

 /var/sieve-scripts, use:

 plugin {

 ...

  sieve = /var/sieve-scripts/%u.sieve

 }

 You may use templates like %u, as shown in the example. See all variables.

 A relative path (or just a filename) will be interpreted to point under the 

 user's home directory.

 Executing Multiple Scripts Sequentially

 ---------------------------------------

 The Dovecot Sieve plugin allows executing multiple Sieve scripts sequentially.

 The extra scripts can be executed before and after the user's private script. 

 For example, this allows executing global Sieve policies before the user's 

 script. This is not possible using the sieve_global_path setting, because that

 is only used when the user's private script does not exist. The following 

 settings in the plugin section of the Dovecot config file control the execution

 sequence:

 sieve_before =

   Path to a script file or a directory containing script files that need to be

   executed before the user's script. If the path points to a directory, all the

   Sieve scripts contained therein (with the proper .sieve extension) are

   executed. The order of execution is determined by the file names, using a

   normal 8bit per-character comparison. 

 sieve_after =

   Identical to sieve_before, only the specified scripts are executed after the

   user's script (only when keep is still in effect!). 

 The script execution ends when the currently executing script in the sequence

 does not yield a "keep" result: when the script terminates, the next script is 

 only executed if an implicit or explicit "keep" is in effect. Thus, to end all

 script execution, a script must not execute keep and it must cancel the 

 implicit keep, e.g. by executing "discard; stop;". This means that the command 

 "keep;" has different semantics when used in a sequence of scripts. For normal

 Sieve execution, "keep;" is equivalent to "fileinto "INBOX";", because both 

 cause the message to be stored in INBOX. However, in sequential script 

 execution, it only controls whether the next script is executed. Storing the 

 message into INBOX (the default folder) is not done until the last script in 

 the sequence executes (implicit) keep. To force storing the message into INBOX

 earlier in the sequence, the fileinto command can be used (with ":copy" or 

 together with "keep;").

 Apart from the keep action, all actions triggered in a script in the sequence

 are executed before continuing to the next script. This means that when a script

 in the sequence encounters an error, actions from earlier executed scripts are

 not affected. The sequence is broken however, meaning that the script execution

 of the offending script is aborted and no further scripts are executed. An

 implicit keep is executed in stead.

 Just as for executing a single script the normal way, the Dovecot Sieve plugin

 takes care never to duplicate deliveries, forwards or responses. When vacation

 actions are executed multiple times in different scripts, the usual error is not

 triggered: the subsequent duplicate vacation actions are simply discarded.

 For example:

 plugin {

 ...

    # Scripts executed before the user's script.

    #   E.g. handling messages marked as dangerous

    sieve_before = /var/lib/dovecot/sieve/discard-virusses.sieve

    # Scripts executed after the user's script (if keep is still in effect)

    #   E.g. default mail filing rules.

    sieve_after = /var/lib/dovecot/sieve/after.d/

 }

 IMPORTANT: Be sure to manually pre-compile the scripts specified by sieve_before 

 and sieve_after using the sievec tool, as explained in the README file.

 Spamtest and Virustest Extensions

 ---------------------------------

 Using the spamtest and virustest extensions (RFC 5235), the Sieve language 

 provides a uniform and standardized command interface for evaluating spam and

 virus tests performed on the message. Users no longer need to know what headers 

 need to be checked and how the scanner's verdict is represented in the header 

 field value. They only need to know how to use the spamtest (spamtestplus) and 

 virustest extensions. This also gives GUI-based Sieve editors the means to 

 provide a portable and easy to install interface for spam and virus filter 

 configuration.

 The spamtest, spamtestplus and virustest extensions require explicit

 configuration and are not enabled for use by default. Refer to 

 doc/spamtest-virustest.txt for configuration information.  

 Migration from CMUSieve

 -----------------------

 For the most part, migration from CMUSieve to the new Sieve plugin is just a

 matter of changing the used plugin name from cmusieve to sieve in the

 mail_plugins option in the protocol lda section of the config file (as explained

 above). However, there are a few important differences:

  * The imapflags extension is now called imap4flags. The CMUSieve implementation

    is based on an old draft specification that is not completely compatible.

    Particularly, the mark and unmark commands were removed from the new

    specification. For backwards compatibility, support for the old imapflags

    extension can be enabled using the sieve_extensions setting (as explained

    above). This is disabled by default.

  * The notify extension is now called enotify. Sieve scripts need to be adjusted

    to incorporate this change: unlike imapflags, no backwards compatibility is

    provided currently.

  * The include extension now requires your script file names to end with 

    ".sieve" : include :personal "myscript"; won't work unless you rename

    "myscript" to "myscript.sieve" 

 Test Suite

 ----------

 This package includes a test suite to verify the basic processing of the Sieve

 interpreter on your particular platform. Note that the test suite is not

 available when this package is compiled against the Dovecot headers only. The

 test suite executes a list of test cases and halts when one of them fails. If it

 executes all test cases successfully, the test suite finishes. You can execute

 the test suite using `make test`.

 A failing test case is always a bug and a report is greatly appreciated.