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:

MF_SIEVE_FILE

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

MF_SIEVE_TEXT

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).

MF_SIEVE_LOG

Log every executed ‘Sieve’ action.

MF_SIEVE_DEBUG_TRACE

Trace execution of ‘Sieve’ tests.

MF_SIEVE_DEBUG_INSTR

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:

domain

The domain name of the server Sieve is running on.

host

Host name of the server Sieve is running on.

location

The string ‘MTA’.

name

The string ‘GNU Mailutils’.

phase

The string ‘pre’.

remote-host

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

remote-ip

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

version

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
do
  if not sieve(current_message(), "/etc/mail/filter.siv", MF_SIEVE_LOG)
     discard
  fi
done

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

require 'sieve'

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

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";
EOT

prog eom
do
  if not sieve(current_message(),
               sieve_prog, MF_SIEVE_TEXT | MF_SIEVE_LOG,
               __file__, sieve_prog_line)
     discard
  fi
done

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