Sieve variables extension

From Messaging Server Technical Reference Wiki
Jump to: navigation, search

As of MS 6.2, the MTA added initial support for the Sieve variables extension, modified in MS 6.3 as the initial variables draft changed, eventually to become RFC 5229 (Sieve Email Filtering: Variables Extension). Note that as part of allowing use of string variables, the variables extension also adds to the Sieve language a "set" action and a "string" test. Also, when variables are enabled, the MTA's Sieve implementation allows the use of assignment statements of the forms:

var-name := string-expression;
var-name = string-expression;

That is, either "=" or ":=" is supported as the assignment operator. (Note that the semi-colon terminating the statement may be omitted if the statement is at the end of a block.)

The capability string is "variables":

require "variables";

Several items of note regarding variables:

  • Variable substitutions are not allowed in body test arguments. If they are used, an error is likely to occur. For example, this Sieve script will fail:

    require ["variables", "body"];
    set "a" "testing"
    if body :contains "${a}" { discard; }

    This restriction exists so that a list of all arguments to body in all scripts can be computed in advance and searched for in a single pass. If this restriction were to be lifted, it would be easy to construct scripts that would require an arbitrary number of passes over the message, which is unacceptable in a server environment. As such, this should be considered to be a permanent restriction.

  • The MTA has a private extension to the Sieve external lists extension, which is that the MTA also supports properties associated with list entries. When Sieve variables are enabled, properties may be returned in additional variables.
  • The "set" action's ":quotewildcard" modifier was first implemented in MS 6.3. However, for MS 7.0.4 the name of the modifier was changed (in the mistaken expectation of a name change in the RFC) to ":quotewild". As of the 8.0 release, either modifier name, ":quotewild" or ":quotewildcard", will be accepted.
  • When the Sieve notify extension of RFC 5435 (capability "enotify") is enabled also, it adds an ":encodeurl" modifier to the variables "set" action.
  • When the Sieve regex extension is enabled also, it adds a ":quoteregex" modifier to the variables "set" action.
  • Sieve :regex match type tests now set variables in the same way that :matches match type test do. Note that unlike glob-style matches (as when :matches is used), where the default is to store whatever matched any wildcard that appears in the pattern, in :regex match type tests only those regular expressions enclosed in parentheses are stored. If parentheses are needed but storage is not desired, then the (?: ) form may be used.
  • The maximum number of variables that the MTA will permit in a Sieve script is controlled by the max_variables MTA option, by default 128.
  • The maximum length that the MTA will permit for a variable name is 128 characters; this is not configurable.
  • The MTA does not currently support the use of variable namespaces, so variable names may not contain any periods.
  • As of the MS 8.0 release, the MTA supports user-defined routines (subroutines) in system-level Sieve filters. Inside such Sieve subroutines, local variables are supported; local variables are declared in a routine by specifying the "my" control command immediately preceeding the first use of the variable; e.g.:

          sub fib(n) {my s = [1, 1];
                      my a = 1;
                      my b = 1;
                      loop {exitif --n < 2;
                            my c = a + b;
                            s .= c;
                            a = b;
                            b = c;}
                      return s;}
  • As of the 8.0 release, the MTA supports integer and list variable values in all levels of Sieves; previously, integer and list values were only supported in system-level Sieves. Integer and list values can only be assigned to variables with regular assignment statements, e.g.,

      a = 1;
      b = ["a", "b", "c"];
      a = a + 1;
      b .= ["d"];

    Such assignment statements are an extension to Sieve syntax. The "set" action provided by the variables extension always produces a variable with a string value.

Examples of using variables can be found in discussions of the Sieve editheader extension, Sieve body extension, Sieve external lists, Sieve mime extension, and Sieve custom tests via mappings.

See also: