Next: , Previous: , Up: Library   [Contents][Index]

5.30 Sieve Interface

Sieve’ is a powerful mail filtering language, defined in RFC 3028. Mailfromd supports an extended form of this language. For a description of the language and available extensions, see Sieve Language in GNU Mailutils Manual.

Built-in Function: boolean sieve (number msg, string script [, number flags, string file, number line])

Compile the Sieve program script and execute it over the message identified by the descriptor nmsg.

Optional flags modify the behavior of the function. It is a bit-mask field, consisting of a bitwise or of one or more of the following flags, defined in sieve.mfl:


The script argument specifies the name of a Sieve program file. This is the default.


The script argument is a string containing entire Sieve program. Optional arguments file and line can be used to fix source locations in Sieve diagnostic messages (see below).


Log every executed ‘Sieve’ action.


Trace execution of ‘Sieve’ tests.


Log every instruction, executed in the compiled ‘Sieve’ code. This produces huge amounts of output and is rarely useful, unless you suspect some bug in ‘Sieve’ implementation and wish to trace it.

For example, MF_SIEVE_LOG|MF_SIEVE_DEBUG_TRACE enables logging ‘Sieve’ actions and tests.

The sieve function returns true if the message was accepted by the script program, and false otherwise. Here, the word accepted means that some form of ‘KEEP’ action (see Actions in GNU Mailutils Manual) was executed over the message.

While executing the Sieve script, Sieve environment (RFC 5183) is initialized as follows:


The domain name of the server Sieve is running on.


Host name of the server Sieve is running on.


The string ‘MTA’.


The string ‘GNU Mailutils’.


The string ‘pre’.


Defined to the value of ‘client_ptr’ macro, if it was required.


Defined to the value of ‘client_addr’ macro, if it was required.


The version of GNU Mailutils.

The following example discards each message not accepted by the ‘Sieve’ program /etc/mail/filter.siv:

require 'sieve'

group eom
  if not sieve(current_message(), "/etc/mail/filter.siv", MF_SIEVE_LOG)

The Sieve program can be embedded in the MFL filter, as shown in the example below:

require 'sieve'

prog eom
  if not sieve(current_message(),
               "require \"fileinto\";\n"
               "fileinto \"/tmp/sieved.mbox\";",
               MF_SIEVE_TEXT | MF_SIEVE_LOG)

In such cases, any Sieve diagnostics (error messages, traces, etc.) will be marked with the locations relative to the line where the call to sieve appears. For example, the above program produces the following in the log:

prog.mfl:7: FILEINTO; delivering into /tmp/sieved.mbox

Notice, that the line number correctly refers to the line where the fileinto action appears in the source. However, there are cases where the reported line number is incorrect. This happens, for instance, if script is a string variable defined elsewhere. To handle such cases, sieve accepts two optional parameters which are used to compute the location in the Sieve program. The file parameter specifies the file name where the definition of the program appears, and the line parameter gives the number of line in that file where the program begins. For example:

require 'sieve'

const sieve_prog_line __line__ + 2
string sieve_prog <<EOT
require "fileinto";
fileinto "/tmp/sieved.mbox";

prog eom
  if not sieve(current_message(),
               sieve_prog, MF_SIEVE_TEXT | MF_SIEVE_LOG,
               __file__, sieve_prog_line)

The actual Sieve program begins two lines below the sieve_prog_line constant definition, which is reflected in its initialization.

Next: , Previous: , Up: Library   [Contents][Index]