General-Purpose Mail Filter
‘Sieve’ is a powerful mail filtering language, defined in
Mailfromd supports an extended form
of this language. For a description of the language and available
extensions, see Sieve Language in GNU Mailutils Manual.
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.mf:
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.
MF_SIEVE_LOG|MF_SIEVE_DEBUG_TRACE enables logging
‘Sieve’ actions and tests.
sieve function returns
true if the message was
accepted by the script program, and
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 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
sieve appears. For example, the above program produces the
following in the log:
prog.mf: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
This document was generated on January 3, 2019 using makeinfo.Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.