Sieve supported extensions

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


In addition to the core Sieve functionality specified in RFC 5228 (Sieve), the MTA's Sieve implementation supports a great many standardized extensions, plus many additional private-to-the-MTA extensions. Standardized extensions supported include:

  • Body extension (RFC 5173). The body test provides the means to test material in the message body. Note that there are are number of restrictions on the implementation of body. (7U2)
  • Copy extension (RFC 3894). Copy is a simple extension that allows the "redirect" and "fileinto" actions to be used without canceling the default action of saving the message to the "inbox". (6.1)
  • Date extension (RFC 5260). The date test provides the means to test fields in date-time values. (7U4)
  • Editheader extension (RFC 5293). The "addheader" and "deleteheader" actions provide the ability to alter the message header. Additionally, the "replaceheader" action described in draft-degener-sieve-editheader-00 has been implemented. This provides an especially convenient way to add tags to subject fields.
  • Encoded-character extension (RFC 5228). This extension provides a way to specify Unicode characters by numeric value in Sieve character strings. Additionally, \r, \n, and \t can be used to represent carriage return, line feed, and tab characters respectively in quoted strings. (7.0)
  • Envelope extension (RFC 5228). This extension consists of an "envelope" test that can access MAIL FROM and RCPT TO address information. (Other extensions have made additional items available to the "envelope" test.)
  • Envelope-dsn (RFC 6009). This extension provides access to additional envelope information provided by the delivery status notification SMTP extension. (7U2)
  • Environment extension (RFC 5183). Environment provides scripts access to information outside of the current message. (7.0U1)
  • Ereject extension (RFC 5429). This extension updates the definition of the "reject" action to allow messages to be refused during the SMTP transaction (rather than being accepted and then generating an MDN), and defines the "ereject" action to require messages to be refused during the SMTP transaction. (6.1)
  • Extlists extension (RFC 6134). This extension adds the ":list" match-type to the "address", "currentdate", "date", "deleteheader", "envelope", "environment", "hasflag", "header", "replaceheader", "spamtest", "string", and "virustest" tests. ":list" in turn allows the test to check values against externally stored information. (7U1)
  • Fcc extension (draft-ietf-extra-sieve-fcc-02.txt). This extension adds support for delivering a copy of any generated message to the notify and vacation actions to the mailbox specified by a :fcc nonpositional parameter.
  • Fileinto extension (RFC 5228). This extension adds the "fileinto" action for specifying a folder where the message is to be delivered.
  • Ihave extension (RFC 5463). "ihave" makes it possible to write scripts that use a given extension if it is available but continue to operate if it is not. (7.0)
  • Index extension (RFC 5260). The index extension adds a ":index" nonpositional parameter to the address, date, and header tests, which in turn provides the means to check a specific instance of header fields that occur multiple times. (7U4)
  • Imap4flags extension (RFC 5232). Imap4flags provides the means to set IMAP flags on messages delivered to the message store. (6.3P1)
  • Mime extension (from RFC 5703). The "mime" extension provides facilities for testing headers in inner MIME parts of messages. (7U1) New in MS 8.0 is support for the "extracttext" and "foreverypart" Sieve extensions from RFC 5703. New in MS 8.1 is the ability to control whether or not the foreverypart Sieve control looks inside of nested messages or treats them as leaf parts. The :processnestedmesssages argument tells foreverypart to look inside and is the default. :retainnestedmessages causes nested messages to be treated as leaf parts. (8.0, 8.1)
  • Notify extension (RFC 5435) and the mailto notification method (RFC 5436). Notify with the mailto method provides the means to send an notification email about the current message being processed. Note that an earlier draft of the "notify" action is also still supported. (6.2, 7.0.5)
  • Relational extension (RFC 5231). Relational adds relational comparisons (less than, greater, than, etc.) to the "header", "address", and "envelope" tests (and other extension tests as they have subsequently been defined). It also adds the ability to count (":count") the number of entities that match the test criteria (6.0). As of MS 8.0.1.3, :count may also be used as a modifier to other match types in header and address tests to count and test the number of matches that occurred.
  • Redirect-dsn extension (RFC 6009). This extends Sieve's "redirect" action to provide control over delivery status notification parameters with two new arguments ":notify" (":notify support was actually added for 6.3p1, prior to its standardization) and ":ret". (6.3p1, 7U2)
  • "spamtest", "spamtestplus", and "virustest" extensions (RFC 5235). The tests defined by these extensions provide a means for Sieve scripts to access spam and virus filter "scores". ("spamtest" and "virustest" 6.0; "spamtestplus" 6.3)
  • Subaddress extension (RFC 3598). Subaddress ":user" and ":detail" tagged arguments for the "envelope" and "address" tests to access information embedded in the local part of an address. (iMS uses a plus sign as the separator between user and detail information in the local part.) (6.0)
  • Vacation extension (RFC 5230). The "vacation" action defined by this extension can be used in user-level Sieve scripts to generate "out of office" messages in response to incoming email.
  • Vacation-seconds extension (RFC 6131). This extends the vacation time to allow specification of timeout values in seconds rather than minutes; in particular, it adds a ":seconds" parameter to the "vacation" action.
  • Variables extension (RFC 5229). The core Sieve language does not provide any means of saving state from one statement to the next. This extension adds variables to the language. (6.2)

In addition to the above standardized extensions, the MTA also supports some private extensions:

  • The "address" test supports a private ":aindex" tag. This ":aindex" tag accepts a positive integer as an argument. If ":aindex n" is specified, then only the nth address in each header field will be tested. Note that ":aindex" (selecting which address out of multiple addresses) may be combined with ":index" (selecting which header line out of multiple header lines), to cause the test to operate on a single address in a single header line. (7.0.5)
  • The "address" test supports two new, private, part modifiers, ":display" and ":comment". The ":display" modifier causes the "address" test to operate on the display-name phrase; note that the display-name phrase is the optional text appearing outside of and specifically in front of the actual address, the actual address being the part enclosed in angles. The ":comment" modifier causes the "address" test to operate on any parenthetical comments that appear after an address. (7.0.5)
  • The "addconversiontag", "removeconversiontag", and "setconversiontag" actions allow operating on the MTA's private conversion tag mechanism. ("addconversiontag" and "setconversiontag" 6.0; "removeconversiontag" 7.0u3) Also, in system-level Sieves, the "envelope" test accepts "conversiontag" as a field specifier value, checking the current list of conversion tags, one at a time. (This test only "sees" the set of conversion tags that were present prior to Sieve processing; the effects of "setconversiontag" and "addconversiontag" are not visible.) (6.3)
  • The "addprefix" and "addsuffix" actions are available for adding a string argument as text at the beginning or end, respectively, of the first plain text part of a message. (7.0u3)
  • The addtag action provides a convenient way to add a prefix string, that is, a "tag", to the beginning of the Subject: header line. (6.0)
  • The "adjustcounter" action is available for system Sieve filters to manipulate any of the eight signed, 64 bit counters accessible from Sieve filters. (8.0)
  • The "capture" action (and the deprecated synonym "monitor"). Two optional nonpositional parameters, ":dsn" and ":message", were added for MS 6.3; ":journal" (to generate Microsoft® Exchange "envelope journaling" format) was added for 7.0u2; ":header" (which can be used as a modifier with either :dsn or :journal) was added for 8.0. (6.3, 7.0u2, 8.0)
  • In addition to standard Sieve comparators, the MTA also supports some non-standard Sieve comparators.
  • The "debug" action takes a string argument, and makes that string available for logging to a debug log file if MTA debugging is enabled at mm_debug=2 level or higher.
  • The MTA supports the proposed Sieve duplicate extension specified in RFC 7352. (8.0)
  • The envelope-auth extension adds a "auth" part to the envelope test, providing access to the SMTP AUTH value.
  • The "hold" action causes a message to be sidelined in the MTA queue area as a .HELD file.
  • The "importancetest" test and "importanceadjust" action allow multiple Sieve scripts to cooperate in making a determination of a message's importance, much like the way that the "spamtest" and "spamadjust" extensions allow multiple Sieve scripts to cooperate in determing whether or not a message is spam.
  • The "jettison" action causes a message to be unconditionally discarded; this is a "non-overridable" discard (for use by system-level Sieve scripts).
  • The "loop" construct is supported in system-level Sieve scripts. (7.0.5)
  • The "memcache" operator permits querying and updating a memcache server from Sieve scripts. (8.0)
  • The "metermaid" operator permits querying and updating MeterMaid from Sieve scripts. (8.0)
  • The "override" action is supported in system-level Sieve scripts; the capability string is "override". (8.0)
  • The "nonotify" action is supported in system-level Sieve scripts. It suppresses all uses of the "notify" and "enotify" extensions (all applications of either form of the "notify" action). (8.0)
  • The "novacation" action is supported in system-level Sieve scripts. (6.1)
  • By default, the MTA supports a relaxed use of "require" clauses in Sieve scripts, in that the MTA permits "require" clauses to be sprinkled throughout a Sieve script (rather than, as the Sieve standard specifies, having all "require" clauses at the beginning of the Sieve script). This is especially useful in conjunction with the MTA's support for combining multiple Sieve scriptlets such as those resulting from spam/virus filter package integration, or from user LDAP attribute mailVacation* settings. However, enforcement of per-the-Sieve-standard "require" clause location may be selected by setting the strict_require MTA option.
  • The ":raw" and ":text" modifiers defined for the "body" test may now also be used in "header" and "address" tests. Similarly to when used with "body", the ":raw" modifier specifies that MIME decoding should be performed; in the case of "address" and "header" tests, the MIME processing in question is the decoding of MIME encoded-words (see RFC 2047 for the definition of encoded-words). ":text" is the default for "header" and "address" tests on ":comment" and ":display" address parts. ":raw" is the default for other sorts of "address" tests. (7.0.5)
  • The proposed "regex" extension adds a ":regex" match type. (6.1)
  • The ":resent" and ":noresent" arguments are supported on the Sieve "redirect" action, for controlling whether Sieve "redirect" actions cause addition of Resent-* header lines. (6.3p1)
  • The ":resetmailfrom" and ":keepmailfrom" parameters are supported on the Sieve "redirect" action, to control whether or not the original message's envelope From address is used on the redirected message (vs. using the Sieve owner's address as the envelope From address for the redirected message). (6.3p1)
  • The "setenvelopefrom" action, to override a message's original envelope From address, is available for use in system-level Sieves. (8.0)
  • The "setmtpriority" action is available for system-level Sieves. It accepts a single integer or string argument and sets the current MT-PRIORITY to the argument value. This action is only allowed in system-level Sieves and the argument must be in the -9 to 9 range of valid MT-PRIORITY values. (8.0)
  • The "setnotify" and "setreturn" actions are available in system-level Sieves. (7.0u1)
  • The "setoperation" action is available for system-level Sieves, to set the enqueue operation mode to "submit", "passthrough", "relay", or "default". (8.0)
  • The "setpriority" action is available for system-level Sieves, to set an effective message processing priority. It takes a single string argument which must be one of "non-urgent", "normal", or "urgent". Note that this priority is NOT stored in the message header and only affects processing at this particular stage of message transfer. If multiple "setpriority" actions are specified in different system-level Sieves, the one in the most specific Sieve wins. (7.0u4)
  • The "spamadjust" and "virusset" actions are supported; they tell the MTA how to set the spam or virus score which a standard "spamtest" and "virustest" test, respectively, would then test. (6.0)
  • The "strongrandom" function takes as an argument an integer value n specifying the number of bytes of (cryptographically strong) random material to return. "strong" is permitted only in system-level Sieves; (attempts to use "strongrandom" from user-levels Sieves are prohibited because of performance concerns).
  • The "random" function takes as an argument an integer specifying an upper limit n on the range of values to return; a uniformly distributed random number between 0 and n-1 is then returned. The linear congruential generator described in "Random Number Generators: Good Ones Are Hard To Find", S. Park and K. Miller, CACM 31 No. 10, pp. 1192-1201, October 1988 is used to generate these numbers; a separate sequence seeded from the system time is used for each sieve evaluation. An explicit 32 bit integer seed can be specified by calling the "randomssed" function. (This may be useful for debugging purposes.) A value of 0 will cause the sequence to be reinitialized from the system clock.
  • The "transactionlog" action is available for system-level Sieves. It takes a single string argument. All of the "transactionlog" actions in all of the applicable Sieves are concatenated into a single string, which is then available for inclusion in the MTA message transaction log file; see the log_transactionlog MTA option. (8.0)
  • The translate function is available, to convert a string from one charset to another. (8.0.1)
  • The warn action is available, to cause additional text to be added to the "warn" clause in the log_filter field of the MTA message transaction log file. (8.0)
  • Custom tests may be defined via MTA FILTER_testname mapping tables. (Updates to MS 6.2 and updates to MS 6.3)
  • Subroutines are supported. (8.0)

Finally, one of the most important of the MTA's extensions to Sieve is the MTA's support of a hierarchy of Sieve filters.


See also: