You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by da...@apache.org on 2007/05/03 15:03:13 UTC
svn commit: r534838 [4/5] - in /james/mailet/trunk: ./ lib/ src/ src/main/
src/main/java/ src/site/ src/site/resources/ src/site/resources/images/
src/site/xdoc/ src/site/xdoc/images/ src/site/xdoc/stylesheets/ src/test/
src/test/java/ src/test/resources/
Added: james/mailet/trunk/src/site/resources/rfc3028.txt
URL: http://svn.apache.org/viewvc/james/mailet/trunk/src/site/resources/rfc3028.txt?view=auto&rev=534838
==============================================================================
--- james/mailet/trunk/src/site/resources/rfc3028.txt (added)
+++ james/mailet/trunk/src/site/resources/rfc3028.txt Thu May 3 06:03:12 2007
@@ -0,0 +1,2018 @@
+
+
+
+
+
+Network Working Group T. Showalter
+Request for Comments: 3028 Mirapoint, Inc.
+Category: Standards Track January 2001
+
+
+ Sieve: A Mail Filtering Language
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2001). All Rights Reserved.
+
+Abstract
+
+ This document describes a language for filtering e-mail messages at
+ time of final delivery. It is designed to be implementable on either
+ a mail client or mail server. It is meant to be extensible, simple,
+ and independent of access protocol, mail architecture, and operating
+ system. It is suitable for running on a mail server where users may
+ not be allowed to execute arbitrary programs, such as on black box
+ Internet Message Access Protocol (IMAP) servers, as it has no
+ variables, loops, or ability to shell out to external programs.
+
+Table of Contents
+
+ 1. Introduction ........................................... 3
+ 1.1. Conventions Used in This Document ..................... 4
+ 1.2. Example mail messages ................................. 4
+ 2. Design ................................................. 5
+ 2.1. Form of the Language .................................. 5
+ 2.2. Whitespace ............................................ 5
+ 2.3. Comments .............................................. 6
+ 2.4. Literal Data .......................................... 6
+ 2.4.1. Numbers ............................................... 6
+ 2.4.2. Strings ............................................... 7
+ 2.4.2.1. String Lists .......................................... 7
+ 2.4.2.2. Headers ............................................... 8
+ 2.4.2.3. Addresses ............................................. 8
+ 2.4.2.4. MIME Parts ............................................ 9
+ 2.5. Tests ................................................. 9
+ 2.5.1. Test Lists ............................................ 9
+
+
+
+Showalter Standards Track [Page 1]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ 2.6. Arguments ............................................. 9
+ 2.6.1. Positional Arguments .................................. 9
+ 2.6.2. Tagged Arguments ...................................... 10
+ 2.6.3. Optional Arguments .................................... 10
+ 2.6.4. Types of Arguments .................................... 10
+ 2.7. String Comparison ..................................... 11
+ 2.7.1. Match Type ............................................ 11
+ 2.7.2. Comparisons Across Character Sets ..................... 12
+ 2.7.3. Comparators ........................................... 12
+ 2.7.4. Comparisons Against Addresses ......................... 13
+ 2.8. Blocks ................................................ 14
+ 2.9. Commands .............................................. 14
+ 2.10. Evaluation ............................................ 15
+ 2.10.1. Action Interaction .................................... 15
+ 2.10.2. Implicit Keep ......................................... 15
+ 2.10.3. Message Uniqueness in a Mailbox ....................... 15
+ 2.10.4. Limits on Numbers of Actions .......................... 16
+ 2.10.5. Extensions and Optional Features ...................... 16
+ 2.10.6. Errors ................................................ 17
+ 2.10.7. Limits on Execution ................................... 17
+ 3. Control Commands ....................................... 17
+ 3.1. Control Structure If .................................. 18
+ 3.2. Control Structure Require ............................. 19
+ 3.3. Control Structure Stop ................................ 19
+ 4. Action Commands ........................................ 19
+ 4.1. Action reject ......................................... 20
+ 4.2. Action fileinto ....................................... 20
+ 4.3. Action redirect ....................................... 21
+ 4.4. Action keep ........................................... 21
+ 4.5. Action discard ........................................ 22
+ 5. Test Commands .......................................... 22
+ 5.1. Test address .......................................... 23
+ 5.2. Test allof ............................................ 23
+ 5.3. Test anyof ............................................ 24
+ 5.4. Test envelope ......................................... 24
+ 5.5. Test exists ........................................... 25
+ 5.6. Test false ............................................ 25
+ 5.7. Test header ........................................... 25
+ 5.8. Test not .............................................. 26
+ 5.9. Test size ............................................. 26
+ 5.10. Test true ............................................. 26
+ 6. Extensibility .......................................... 26
+ 6.1. Capability String ..................................... 27
+ 6.2. IANA Considerations ................................... 28
+ 6.2.1. Template for Capability Registrations ................. 28
+ 6.2.2. Initial Capability Registrations ...................... 28
+ 6.3. Capability Transport .................................. 29
+ 7. Transmission ........................................... 29
+
+
+
+Showalter Standards Track [Page 2]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ 8. Parsing ................................................ 30
+ 8.1. Lexical Tokens ........................................ 30
+ 8.2. Grammar ............................................... 31
+ 9. Extended Example ....................................... 32
+ 10. Security Considerations ................................ 34
+ 11. Acknowledgments ........................................ 34
+ 12. Author's Address ....................................... 34
+ 13. References ............................................. 34
+ 14. Full Copyright Statement ............................... 36
+
+1. Introduction
+
+ This memo documents a language that can be used to create filters for
+ electronic mail. It is not tied to any particular operating system or
+ mail architecture. It requires the use of [IMAIL]-compliant
+ messages, but should otherwise generalize to many systems.
+
+ The language is powerful enough to be useful but limited in order to
+ allow for a safe server-side filtering system. The intention is to
+ make it impossible for users to do anything more complex (and
+ dangerous) than write simple mail filters, along with facilitating
+ the use of GUIs for filter creation and manipulation. The language is
+ not Turing-complete: it provides no way to write a loop or a function
+ and variables are not provided.
+
+ Scripts written in Sieve are executed during final delivery, when the
+ message is moved to the user-accessible mailbox. In systems where
+ the MTA does final delivery, such as traditional Unix mail, it is
+ reasonable to sort when the MTA deposits mail into the user's
+ mailbox.
+
+ There are a number of reasons to use a filtering system. Mail
+ traffic for most users has been increasing due to increased usage of
+ e-mail, the emergence of unsolicited email as a form of advertising,
+ and increased usage of mailing lists.
+
+ Experience at Carnegie Mellon has shown that if a filtering system is
+ made available to users, many will make use of it in order to file
+ messages from specific users or mailing lists. However, many others
+ did not make use of the Andrew system's FLAMES filtering language
+ [FLAMES] due to difficulty in setting it up.
+
+ Because of the expectation that users will make use of filtering if
+ it is offered and easy to use, this language has been made simple
+ enough to allow many users to make use of it, but rich enough that it
+ can be used productively. However, it is expected that GUI-based
+ editors will be the preferred way of editing filters for a large
+ number of users.
+
+
+
+Showalter Standards Track [Page 3]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+1.1. Conventions Used in This Document
+
+ In the sections of this document that discuss the requirements of
+ various keywords and operators, the following conventions have been
+ adopted.
+
+ The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and
+ "MAY" in this document are to be interpreted as defined in
+ [KEYWORDS].
+
+ Each section on a command (test, action, or control structure) has a
+ line labeled "Syntax:". This line describes the syntax of the
+ command, including its name and its arguments. Required arguments
+ are listed inside angle brackets ("<" and ">"). Optional arguments
+ are listed inside square brackets ("[" and "]"). Each argument is
+ followed by its type, so "<key: string>" represents an argument
+ called "key" that is a string. Literal strings are represented with
+ double-quoted strings. Alternatives are separated with slashes, and
+ parenthesis are used for grouping, similar to [ABNF].
+
+ In the "Syntax" line, there are three special pieces of syntax that
+ are frequently repeated, MATCH-TYPE, COMPARATOR, and ADDRESS-PART.
+ These are discussed in sections 2.7.1, 2.7.3, and 2.7.4,
+ respectively.
+
+ The formal grammar for these commands in section 10 and is the
+ authoritative reference on how to construct commands, but the formal
+ grammar does not specify the order, semantics, number or types of
+ arguments to commands, nor the legal command names. The intent is to
+ allow for extension without changing the grammar.
+
+1.2. Example mail messages
+
+ The following mail messages will be used throughout this document in
+ examples.
+
+ Message A
+ -----------------------------------------------------------
+ Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
+ From: coyote@desert.example.org
+ To: roadrunner@acme.example.com
+ Subject: I have a present for you
+
+ Look, I'm sorry about the whole anvil thing, and I really
+ didn't mean to try and drop it on you from the top of the
+ cliff. I want to try to make it up to you. I've got some
+ great birdseed over here at my place--top of the line
+
+
+
+
+Showalter Standards Track [Page 4]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ stuff--and if you come by, I'll have it all wrapped up
+ for you. I'm really sorry for all the problems I've caused
+ for you over the years, but I know we can work this out.
+ --
+ Wile E. Coyote "Super Genius" coyote@desert.example.org
+ -----------------------------------------------------------
+
+ Message B
+ -----------------------------------------------------------
+ From: youcouldberich!@reply-by-postal-mail.invalid
+ Sender: b1ff@de.res.example.com
+ To: rube@landru.example.edu
+ Date: Mon, 31 Mar 1997 18:26:10 -0800
+ Subject: $$$ YOU, TOO, CAN BE A MILLIONAIRE! $$$
+
+ YOU MAY HAVE ALREADY WON TEN MILLION DOLLARS, BUT I DOUBT
+ IT! SO JUST POST THIS TO SIX HUNDRED NEWSGROUPS! IT WILL
+ GUARANTEE THAT YOU GET AT LEAST FIVE RESPONSES WITH MONEY!
+ MONEY! MONEY! COLD HARD CASH! YOU WILL RECEIVE OVER
+ $20,000 IN LESS THAN TWO MONTHS! AND IT'S LEGAL!!!!!!!!!
+ !!!!!!!!!!!!!!!!!!111111111!!!!!!!11111111111!!1 JUST
+ SEND $5 IN SMALL, UNMARKED BILLS TO THE ADDRESSES BELOW!
+ -----------------------------------------------------------
+
+2. Design
+
+2.1. Form of the Language
+
+ The language consists of a set of commands. Each command consists of
+ a set of tokens delimited by whitespace. The command identifier is
+ the first token and it is followed by zero or more argument tokens.
+ Arguments may be literal data, tags, blocks of commands, or test
+ commands.
+
+ The language is represented in UTF-8, as specified in [UTF-8].
+
+ Tokens in the ASCII range are considered case-insensitive.
+
+2.2. Whitespace
+
+ Whitespace is used to separate tokens. Whitespace is made up of
+ tabs, newlines (CRLF, never just CR or LF), and the space character.
+ The amount of whitespace used is not significant.
+
+
+
+
+
+
+
+
+Showalter Standards Track [Page 5]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+2.3. Comments
+
+ Two types of comments are offered. Comments are semantically
+ equivalent to whitespace and can be used anyplace that whitespace is
+ (with one exception in multi-line strings, as described in the
+ grammar).
+
+ Hash comments begin with a "#" character that is not contained within
+ a string and continue until the next CRLF.
+
+ Example: if size :over 100K { # this is a comment
+ discard;
+ }
+
+ Bracketed comments begin with the token "/*" and end with "*/" outside
+ of a string. Bracketed comments may span multiple lines. Bracketed
+ comments do not nest.
+
+ Example: if size :over 100K { /* this is a comment
+ this is still a comment */ discard /* this is a comment
+ */ ;
+ }
+
+2.4. Literal Data
+
+ Literal data means data that is not executed, merely evaluated "as
+ is", to be used as arguments to commands. Literal data is limited to
+ numbers and strings.
+
+2.4.1. Numbers
+
+ Numbers are given as ordinary decimal numbers. However, those
+ numbers that have a tendency to be fairly large, such as message
+ sizes, MAY have a "K", "M", or "G" appended to indicate a multiple of
+ a power of two. To be comparable with the power-of-two-based
+ versions of SI units that computers frequently use, K specifies
+ kibi-, or 1,024 (2^10) times the value of the number; M specifies
+ mebi-, or 1,048,576 (2^20) times the value of the number; and G
+ specifies tebi-, or 1,073,741,824 (2^30) times the value of the
+ number [BINARY-SI].
+
+ Implementations MUST provide 31 bits of magnitude in numbers, but MAY
+ provide more.
+
+ Only positive integers are permitted by this specification.
+
+
+
+
+
+
+Showalter Standards Track [Page 6]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+2.4.2. Strings
+
+ Scripts involve large numbers of strings as they are used for pattern
+ matching, addresses, textual bodies, etc. Typically, short quoted
+ strings suffice for most uses, but a more convenient form is provided
+ for longer strings such as bodies of messages.
+
+ A quoted string starts and ends with a single double quote (the <">
+ character, ASCII 34). A backslash ("\", ASCII 92) inside of a quoted
+ string is followed by either another backslash or a double quote.
+ This two-character sequence represents a single backslash or double-
+ quote within the string, respectively.
+
+ No other characters should be escaped with a single backslash.
+
+ An undefined escape sequence (such as "\a" in a context where "a" has
+ no special meaning) is interpreted as if there were no backslash (in
+ this case, "\a" is just "a").
+
+ Non-printing characters such as tabs, CR and LF, and control
+ characters are permitted in quoted strings. Quoted strings MAY span
+ multiple lines. NUL (ASCII 0) is not allowed in strings.
+
+ For entering larger amounts of text, such as an email message, a
+ multi-line form is allowed. It starts with the keyword "text:",
+ followed by a CRLF, and ends with the sequence of a CRLF, a single
+ period, and another CRLF. In order to allow the message to contain
+ lines with a single-dot, lines are dot-stuffed. That is, when
+ composing a message body, an extra `.' is added before each line
+ which begins with a `.'. When the server interprets the script,
+ these extra dots are removed. Note that a line that begins with a
+ dot followed by a non-dot character is not interpreted dot-stuffed;
+ that is, ".foo" is interpreted as ".foo". However, because this is
+ potentially ambiguous, scripts SHOULD be properly dot-stuffed so such
+ lines do not appear.
+
+ Note that a hashed comment or whitespace may occur in between the
+ "text:" and the CRLF, but not within the string itself. Bracketed
+ comments are not allowed here.
+
+2.4.2.1. String Lists
+
+ When matching patterns, it is frequently convenient to match against
+ groups of strings instead of single strings. For this reason, a list
+ of strings is allowed in many tests, implying that if the test is
+ true using any one of the strings, then the test is true.
+ Implementations are encouraged to use short-circuit evaluation in
+ these cases.
+
+
+
+Showalter Standards Track [Page 7]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ For instance, the test `header :contains ["To", "Cc"]
+ ["me@example.com", "me00@landru.example.edu"]' is true if either the
+ To header or Cc header of the input message contains either of the
+ e-mail addresses "me@example.com" or "me00@landru.example.edu".
+
+ Conversely, in any case where a list of strings is appropriate, a
+ single string is allowed without being a member of a list: it is
+ equivalent to a list with a single member. This means that the test
+ `exists "To"' is equivalent to the test `exists ["To"]'.
+
+2.4.2.2. Headers
+
+ Headers are a subset of strings. In the Internet Message
+ Specification [IMAIL] [RFC1123], each header line is allowed to have
+ whitespace nearly anywhere in the line, including after the field
+ name and before the subsequent colon. Extra spaces between the
+ header name and the ":" in a header field are ignored.
+
+ A header name never contains a colon. The "From" header refers to a
+ line beginning "From:" (or "From :", etc.). No header will match
+ the string "From:" due to the trailing colon.
+
+ Folding of long header lines (as described in [IMAIL] 3.4.8) is
+ removed prior to interpretation of the data. The folding syntax (the
+ CRLF that ends a line plus any leading whitespace at the beginning of
+ the next line that indicates folding) are interpreted as if they were
+ a single space.
+
+2.4.2.3. Addresses
+
+ A number of commands call for email addresses, which are also a
+ subset of strings. When these addresses are used in outbound
+ contexts, addresses must be compliant with [IMAIL], but are further
+ constrained. Using the symbols defined in [IMAIL], section 6.1, the
+ syntax of an address is:
+
+ sieve-address = addr-spec ; simple address
+ / phrase "<" addr-spec ">" ; name & addr-spec
+
+ That is, routes and group syntax are not permitted. If multiple
+ addresses are required, use a string list. Named groups are not used
+ here.
+
+ Implementations MUST ensure that the addresses are syntactically
+ valid, but need not ensure that they actually identify an email
+ recipient.
+
+
+
+
+
+Showalter Standards Track [Page 8]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+2.4.2.4. MIME Parts
+
+ In a few places, [MIME] body parts are represented as strings. These
+ parts include MIME headers and the body. This provides a way of
+ embedding typed data within a Sieve script so that, among other
+ things, character sets other than UTF-8 can be used for output
+ messages.
+
+2.5. Tests
+
+ Tests are given as arguments to commands in order to control their
+ actions. In this document, tests are given to if/elsif/else to
+ decide which block of code is run.
+
+ Tests MUST NOT have side effects. That is, a test cannot affect the
+ state of the filter or message. No tests in this specification have
+ side effects, and side effects are forbidden in extension tests as
+ well.
+
+ The rationale for this is that tests with side effects impair
+ readability and maintainability and are difficult to represent in a
+ graphic interface for generating scripts. Side effects are confined
+ to actions where they are clearer.
+
+2.5.1. Test Lists
+
+ Some tests ("allof" and "anyof", which implement logical "and" and
+ logical "or", respectively) may require more than a single test as an
+ argument. The test-list syntax element provides a way of grouping
+ tests.
+
+ Example: if anyof (not exists ["From", "Date"],
+ header :contains "from" "fool@example.edu") {
+ discard;
+ }
+
+2.6. Arguments
+
+ In order to specify what to do, most commands take arguments. There
+ are three types of arguments: positional, tagged, and optional.
+
+2.6.1. Positional Arguments
+
+ Positional arguments are given to a command which discerns their
+ meaning based on their order. When a command takes positional
+ arguments, all positional arguments must be supplied and must be in
+ the order prescribed.
+
+
+
+
+Showalter Standards Track [Page 9]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+2.6.2. Tagged Arguments
+
+ This document provides for tagged arguments in the style of
+ CommonLISP. These are also similar to flags given to commands in
+ most command-line systems.
+
+ A tagged argument is an argument for a command that begins with ":"
+ followed by a tag naming the argument, such as ":contains". This
+ argument means that zero or more of the next tokens have some
+ particular meaning depending on the argument. These next tokens may
+ be numbers or strings but they are never blocks.
+
+ Tagged arguments are similar to positional arguments, except that
+ instead of the meaning being derived from the command, it is derived
+ from the tag.
+
+ Tagged arguments must appear before positional arguments, but they
+ may appear in any order with other tagged arguments. For simplicity
+ of the specification, this is not expressed in the syntax definitions
+ with commands, but they still may be reordered arbitrarily provided
+ they appear before positional arguments. Tagged arguments may be
+ mixed with optional arguments.
+
+ To simplify this specification, tagged arguments SHOULD NOT take
+ tagged arguments as arguments.
+
+2.6.3. Optional Arguments
+
+ Optional arguments are exactly like tagged arguments except that they
+ may be left out, in which case a default value is implied. Because
+ optional arguments tend to result in shorter scripts, they have been
+ used far more than tagged arguments.
+
+ One particularly noteworthy case is the ":comparator" argument, which
+ allows the user to specify which [ACAP] comparator will be used to
+ compare two strings, since different languages may impose different
+ orderings on UTF-8 [UTF-8] characters.
+
+2.6.4. Types of Arguments
+
+ Abstractly, arguments may be literal data, tests, or blocks of
+ commands. In this way, an "if" control structure is merely a command
+ that happens to take a test and a block as arguments and may execute
+ the block of code.
+
+ However, this abstraction is ambiguous from a parsing standpoint.
+ The grammar in section 9.2 presents a parsable version of this:
+ Arguments are string-lists, numbers, and tags, which may be followed
+
+
+
+Showalter Standards Track [Page 10]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ by a test or a test-list, which may be followed by a block of
+ commands. No more than one test or test list, nor more than one
+ block of commands, may be used, and commands that end with blocks of
+ commands do not end with semicolons.
+
+2.7. String Comparison
+
+ When matching one string against another, there are a number of ways
+ of performing the match operation. These are accomplished with three
+ types of matches: an exact match, a substring match, and a wildcard
+ glob-style match. These are described below.
+
+ In order to provide for matches between character sets and case
+ insensitivity, Sieve borrows ACAP's comparator registry.
+
+ However, when a string represents the name of a header, the
+ comparator is never user-specified. Header comparisons are always
+ done with the "i;ascii-casemap" operator, i.e., case-insensitive
+ comparisons, because this is the way things are defined in the
+ message specification [IMAIL].
+
+2.7.1. Match Type
+
+ There are three match types describing the matching used in this
+ specification: ":is", ":contains", and ":matches". Match type
+ arguments are supplied to those commands which allow them to specify
+ what kind of match is to be performed.
+
+ These are used as tagged arguments to tests that perform string
+ comparison.
+
+ The ":contains" match type describes a substring match. If the value
+ argument contains the key argument as a substring, the match is true.
+ For instance, the string "frobnitzm" contains "frob" and "nit", but
+ not "fbm". The null key ("") is contained in all values.
+
+ The ":is" match type describes an absolute match; if the contents of
+ the first string are absolutely the same as the contents of the
+ second string, they match. Only the string "frobnitzm" is the string
+ "frobnitzm". The null key ":is" and only ":is" the null value.
+
+ The ":matches" version specifies a wildcard match using the
+ characters "*" and "?". "*" matches zero or more characters, and "?"
+ matches a single character. "?" and "*" may be escaped as "\\?" and
+ "\\*" in strings to match against themselves. The first backslash
+ escapes the second backslash; together, they escape the "*". This is
+ awkward, but it is commonplace in several programming languages that
+ use globs and regular expressions.
+
+
+
+Showalter Standards Track [Page 11]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ In order to specify what type of match is supposed to happen,
+ commands that support matching take optional tagged arguments
+ ":matches", ":is", and ":contains". Commands default to using ":is"
+ matching if no match type argument is supplied. Note that these
+ modifiers may interact with comparators; in particular, some
+ comparators are not suitable for matching with ":contains" or
+ ":matches". It is an error to use a comparator with ":contains" or
+ ":matches" that is not compatible with it.
+
+ It is an error to give more than one of these arguments to a given
+ command.
+
+ For convenience, the "MATCH-TYPE" syntax element is defined here as
+ follows:
+
+ Syntax: ":is" / ":contains" / ":matches"
+
+2.7.2. Comparisons Across Character Sets
+
+ All Sieve scripts are represented in UTF-8, but messages may involve
+ a number of character sets. In order for comparisons to work across
+ character sets, implementations SHOULD implement the following
+ behavior:
+
+ Implementations decode header charsets to UTF-8. Two strings are
+ considered equal if their UTF-8 representations are identical.
+ Implementations should decode charsets represented in the forms
+ specified by [MIME] for both message headers and bodies.
+ Implementations must be capable of decoding US-ASCII, ISO-8859-1,
+ the ASCII subset of ISO-8859-* character sets, and UTF-8.
+
+ If implementations fail to support the above behavior, they MUST
+ conform to the following:
+
+ No two strings can be considered equal if one contains octets
+ greater than 127.
+
+2.7.3. Comparators
+
+ In order to allow for language-independent, case-independent matches,
+ the match type may be coupled with a comparator name. Comparators
+ are described for [ACAP]; a registry is defined for ACAP, and this
+ specification uses that registry.
+
+ ACAP defines multiple comparator types. Only equality types are used
+ in this specification.
+
+
+
+
+
+Showalter Standards Track [Page 12]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ All implementations MUST support the "i;octet" comparator (simply
+ compares octets) and the "i;ascii-casemap" comparator (which treats
+ uppercase and lowercase characters in the ASCII subset of UTF-8 as
+ the same). If left unspecified, the default is "i;ascii-casemap".
+
+ Some comparators may not be usable with substring matches; that is,
+ they may only work with ":is". It is an error to try and use a
+ comparator with ":matches" or ":contains" that is not compatible with
+ it.
+
+ A comparator is specified by the ":comparator" option with commands
+ that support matching. This option is followed by a string providing
+ the name of the comparator to be used. For convenience, the syntax
+ of a comparator is abbreviated to "COMPARATOR", and (repeated in
+ several tests) is as follows:
+
+ Syntax: ":comparator" <comparator-name: string>
+
+ So in this example,
+
+ Example: if header :contains :comparator "i;octet" "Subject"
+ "MAKE MONEY FAST" {
+ discard;
+ }
+
+ would discard any message with subjects like "You can MAKE MONEY
+ FAST", but not "You can Make Money Fast", since the comparator used
+ is case-sensitive.
+
+ Comparators other than i;octet and i;ascii-casemap must be declared
+ with require, as they are extensions. If a comparator declared with
+ require is not known, it is an error, and execution fails. If the
+ comparator is not declared with require, it is also an error, even if
+ the comparator is supported. (See 2.10.5.)
+
+ Both ":matches" and ":contains" match types are compatible with the
+ "i;octet" and "i;ascii-casemap" comparators and may be used with
+ them.
+
+ It is an error to give more than one of these arguments to a given
+ command.
+
+2.7.4. Comparisons Against Addresses
+
+ Addresses are one of the most frequent things represented as strings.
+ These are structured, and being able to compare against the local-
+ part or the domain of an address is useful, so some tests that act
+
+
+
+
+Showalter Standards Track [Page 13]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ exclusively on addresses take an additional optional argument that
+ specifies what the test acts on.
+
+ These optional arguments are ":localpart", ":domain", and ":all",
+ which act on the local-part (left-side), the domain part (right-
+ side), and the whole address.
+
+ The kind of comparison done, such as whether or not the test done is
+ case-insensitive, is specified as a comparator argument to the test.
+
+ If an optional address-part is omitted, the default is ":all".
+
+ It is an error to give more than one of these arguments to a given
+ command.
+
+ For convenience, the "ADDRESS-PART" syntax element is defined here as
+ follows:
+
+ Syntax: ":localpart" / ":domain" / ":all"
+
+2.8. Blocks
+
+ Blocks are sets of commands enclosed within curly braces. Blocks are
+ supplied to commands so that the commands can implement control
+ commands.
+
+ A control structure is a command that happens to take a test and a
+ block as one of its arguments; depending on the result of the test
+ supplied as another argument, it runs the code in the block some
+ number of times.
+
+ With the commands supplied in this memo, there are no loops. The
+ control structures supplied--if, elsif, and else--run a block either
+ once or not at all. So there are two arguments, the test and the
+ block.
+
+2.9. Commands
+
+ Sieve scripts are sequences of commands. Commands can take any of
+ the tokens above as arguments, and arguments may be either tagged or
+ positional arguments. Not all commands take all arguments.
+
+ There are three kinds of commands: test commands, action commands,
+ and control commands.
+
+ The simplest is an action command. An action command is an
+ identifier followed by zero or more arguments, terminated by a
+ semicolon. Action commands do not take tests or blocks as arguments.
+
+
+
+Showalter Standards Track [Page 14]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ A control command is similar, but it takes a test as an argument, and
+ ends with a block instead of a semicolon.
+
+ A test command is used as part of a control command. It is used to
+ specify whether or not the block of code given to the control command
+ is executed.
+
+2.10. Evaluation
+
+2.10.1. Action Interaction
+
+ Some actions cannot be used with other actions because the result
+ would be absurd. These restrictions are noted throughout this memo.
+
+ Extension actions MUST state how they interact with actions defined
+ in this specification.
+
+2.10.2. Implicit Keep
+
+ Previous experience with filtering systems suggests that cases tend
+ to be missed in scripts. To prevent errors, Sieve has an "implicit
+ keep".
+
+ An implicit keep is a keep action (see 4.4) performed in absence of
+ any action that cancels the implicit keep.
+
+ An implicit keep is performed if a message is not written to a
+ mailbox, redirected to a new address, or explicitly thrown out. That
+ is, if a fileinto, a keep, a redirect, or a discard is performed, an
+ implicit keep is not.
+
+ Some actions may be defined to not cancel the implicit keep. These
+ actions may not directly affect the delivery of a message, and are
+ used for their side effects. None of the actions specified in this
+ document meet that criteria, but extension actions will.
+
+ For instance, with any of the short messages offered above, the
+ following script produces no actions.
+
+ Example: if size :over 500K { discard; }
+
+ As a result, the implicit keep is taken.
+
+2.10.3. Message Uniqueness in a Mailbox
+
+ Implementations SHOULD NOT deliver a message to the same folder more
+ than once, even if a script explicitly asks for a message to be
+ written to a mailbox twice.
+
+
+
+Showalter Standards Track [Page 15]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ The test for equality of two messages is implementation-defined.
+
+ If a script asks for a message to be written to a mailbox twice, it
+ MUST NOT be treated as an error.
+
+2.10.4. Limits on Numbers of Actions
+
+ Site policy MAY limit numbers of actions taken and MAY impose
+ restrictions on which actions can be used together. In the event
+ that a script hits a policy limit on the number of actions taken for
+ a particular message, an error occurs.
+
+ Implementations MUST prohibit more than one reject.
+
+ Implementations MUST allow at least one keep or one fileinto. If
+ fileinto is not implemented, implementations MUST allow at least one
+ keep.
+
+ Implementations SHOULD prohibit reject when used with other actions.
+
+2.10.5. Extensions and Optional Features
+
+ Because of the differing capabilities of many mail systems, several
+ features of this specification are optional. Before any of these
+ extensions can be executed, they must be declared with the "require"
+ action.
+
+ If an extension is not enabled with "require", implementations MUST
+ treat it as if they did not support it at all.
+
+ If a script does not understand an extension declared with require,
+ the script must not be used at all. Implementations MUST NOT execute
+ scripts which require unknown capability names.
+
+ Note: The reason for this restriction is that prior experiences with
+ languages such as LISP and Tcl suggest that this is a workable
+ way of noting that a given script uses an extension.
+
+ Experience with PostScript suggests that mechanisms that allow
+ a script to work around missing extensions are not used in
+ practice.
+
+ Extensions which define actions MUST state how they interact with
+ actions discussed in the base specification.
+
+
+
+
+
+
+
+Showalter Standards Track [Page 16]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+2.10.6. Errors
+
+ In any programming language, there are compile-time and run-time
+ errors.
+
+ Compile-time errors are ones in syntax that are detectable if a
+ syntax check is done.
+
+ Run-time errors are not detectable until the script is run. This
+ includes transient failures like disk full conditions, but also
+ includes issues like invalid combinations of actions.
+
+ When an error occurs in a Sieve script, all processing stops.
+
+ Implementations MAY choose to do a full parse, then evaluate the
+ script, then do all actions. Implementations might even go so far as
+ to ensure that execution is atomic (either all actions are executed
+ or none are executed).
+
+ Other implementations may choose to parse and run at the same time.
+ Such implementations are simpler, but have issues with partial
+ failure (some actions happen, others don't).
+
+ Implementations might even go so far as to ensure that scripts can
+ never execute an invalid set of actions (e.g., reject + fileinto)
+ before execution, although this could involve solving the Halting
+ Problem.
+
+ This specification allows any of these approaches. Solving the
+ Halting Problem is considered extra credit.
+
+ When an error happens, implementations MUST notify the user that an
+ error occurred, which actions (if any) were taken, and do an implicit
+ keep.
+
+2.10.7. Limits on Execution
+
+ Implementations may limit certain constructs. However, this
+ specification places a lower bound on some of these limits.
+
+ Implementations MUST support fifteen levels of nested blocks.
+
+ Implementations MUST support fifteen levels of nested test lists.
+
+3. Control Commands
+
+ Control structures are needed to allow for multiple and conditional
+ actions.
+
+
+
+Showalter Standards Track [Page 17]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+3.1. Control Structure If
+
+ There are three pieces to if: "if", "elsif", and "else". Each is
+ actually a separate command in terms of the grammar. However, an
+ elsif MUST only follow an if, and an else MUST follow only either an
+ if or an elsif. An error occurs if these conditions are not met.
+
+ Syntax: if <test1: test> <block1: block>
+
+ Syntax: elsif <test2: test> <block2: block>
+
+ Syntax: else <block>
+
+ The semantics are similar to those of any of the many other
+ programming languages these control commands appear in. When the
+ interpreter sees an "if", it evaluates the test associated with it.
+ If the test is true, it executes the block associated with it.
+
+ If the test of the "if" is false, it evaluates the test of the first
+ "elsif" (if any). If the test of "elsif" is true, it runs the
+ elsif's block. An elsif may be followed by an elsif, in which case,
+ the interpreter repeats this process until it runs out of elsifs.
+
+ When the interpreter runs out of elsifs, there may be an "else" case.
+ If there is, and none of the if or elsif tests were true, the
+ interpreter runs the else case.
+
+ This provides a way of performing exactly one of the blocks in the
+ chain.
+
+ In the following example, both Message A and B are dropped.
+
+ Example: require "fileinto";
+ if header :contains "from" "coyote" {
+ discard;
+ } elsif header :contains ["subject"] ["$$$"] {
+ discard;
+ } else {
+ fileinto "INBOX";
+ }
+
+
+ When the script below is run over message A, it redirects the message
+ to acm@example.edu; message B, to postmaster@example.edu; any other
+ message is redirected to field@example.edu.
+
+
+
+
+
+
+Showalter Standards Track [Page 18]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ Example: if header :contains ["From"] ["coyote"] {
+ redirect "acm@example.edu";
+ } elsif header :contains "Subject" "$$$" {
+ redirect "postmaster@example.edu";
+ } else {
+ redirect "field@example.edu";
+ }
+
+ Note that this definition prohibits the "... else if ..." sequence
+ used by C. This is intentional, because this construct produces a
+ shift-reduce conflict.
+
+3.2. Control Structure Require
+
+ Syntax: require <capabilities: string-list>
+
+ The require action notes that a script makes use of a certain
+ extension. Such a declaration is required to use the extension, as
+ discussed in section 2.10.5. Multiple capabilities can be declared
+ with a single require.
+
+ The require command, if present, MUST be used before anything other
+ than a require can be used. An error occurs if a require appears
+ after a command other than require.
+
+ Example: require ["fileinto", "reject"];
+
+ Example: require "fileinto";
+ require "vacation";
+
+3.3. Control Structure Stop
+
+ Syntax: stop
+
+ The "stop" action ends all processing. If no actions have been
+ executed, then the keep action is taken.
+
+4. Action Commands
+
+ This document supplies five actions that may be taken on a message:
+ keep, fileinto, redirect, reject, and discard.
+
+ Implementations MUST support the "keep", "discard", and "redirect"
+ actions.
+
+ Implementations SHOULD support "reject" and "fileinto".
+
+
+
+
+
+Showalter Standards Track [Page 19]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ Implementations MAY limit the number of certain actions taken (see
+ section 2.10.4).
+
+4.1. Action reject
+
+ Syntax: reject <reason: string>
+
+ The optional "reject" action refuses delivery of a message by sending
+ back an [MDN] to the sender. It resends the message to the sender,
+ wrapping it in a "reject" form, noting that it was rejected by the
+ recipient. In the following script, message A is rejected and
+ returned to the sender.
+
+ Example: if header :contains "from" "coyote@desert.example.org" {
+ reject "I am not taking mail from you, and I don't want
+ your birdseed, either!";
+ }
+
+ A reject message MUST take the form of a failure MDN as specified by
+ [MDN]. The human-readable portion of the message, the first
+ component of the MDN, contains the human readable message describing
+ the error, and it SHOULD contain additional text alerting the
+ original sender that mail was refused by a filter. This part of the
+ MDN might appear as follows:
+
+ ------------------------------------------------------------
+ Message was refused by recipient's mail filtering program. Reason
+ given was as follows:
+
+ I am not taking mail from you, and I don't want your birdseed,
+ either!
+ ------------------------------------------------------------
+
+ The MDN action-value field as defined in the MDN specification MUST
+ be "deleted" and MUST have the MDN-sent-automatically and automatic-
+ action modes set.
+
+ Because some implementations can not or will not implement the reject
+ command, it is optional. The capability string to be used with the
+ require command is "reject".
+
+4.2. Action fileinto
+
+ Syntax: fileinto <folder: string>
+
+ The "fileinto" action delivers the message into the specified folder.
+ Implementations SHOULD support fileinto, but in some environments
+ this may be impossible.
+
+
+
+Showalter Standards Track [Page 20]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ The capability string for use with the require command is "fileinto".
+
+ In the following script, message A is filed into folder
+ "INBOX.harassment".
+
+ Example: require "fileinto";
+ if header :contains ["from"] "coyote" {
+ fileinto "INBOX.harassment";
+ }
+
+4.3. Action redirect
+
+ Syntax: redirect <address: string>
+
+ The "redirect" action is used to send the message to another user at
+ a supplied address, as a mail forwarding feature does. The
+ "redirect" action makes no changes to the message body or existing
+ headers, but it may add new headers. The "redirect" modifies the
+ envelope recipient.
+
+ The redirect command performs an MTA-style "forward"--that is, what
+ you get from a .forward file using sendmail under UNIX. The address
+ on the SMTP envelope is replaced with the one on the redirect command
+ and the message is sent back out. (This is not an MUA-style forward,
+ which creates a new message with a different sender and message ID,
+ wrapping the old message in a new one.)
+
+ A simple script can be used for redirecting all mail:
+
+ Example: redirect "bart@example.edu";
+
+ Implementations SHOULD take measures to implement loop control,
+ possibly including adding headers to the message or counting received
+ headers. If an implementation detects a loop, it causes an error.
+
+4.4. Action keep
+
+ Syntax: keep
+
+ The "keep" action is whatever action is taken in lieu of all other
+ actions, if no filtering happens at all; generally, this simply means
+ to file the message into the user's main mailbox. This command
+ provides a way to execute this action without needing to know the
+ name of the user's main mailbox, providing a way to call it without
+ needing to understand the user's setup, or the underlying mail
+ system.
+
+
+
+
+
+Showalter Standards Track [Page 21]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ For instance, in an implementation where the IMAP server is running
+ scripts on behalf of the user at time of delivery, a keep command is
+ equivalent to a fileinto "INBOX".
+
+ Example: if size :under 1M { keep; } else { discard; }
+
+ Note that the above script is identical to the one below.
+
+ Example: if not size :under 1M { discard; }
+
+4.5. Action discard
+
+ Syntax: discard
+
+ Discard is used to silently throw away the message. It does so by
+ simply canceling the implicit keep. If discard is used with other
+ actions, the other actions still happen. Discard is compatible with
+ all other actions. (For instance fileinto+discard is equivalent to
+ fileinto.)
+
+ Discard MUST be silent; that is, it MUST NOT return a non-delivery
+ notification of any kind ([DSN], [MDN], or otherwise).
+
+ In the following script, any mail from "idiot@example.edu" is thrown
+ out.
+
+ Example: if header :contains ["from"] ["idiot@example.edu"] {
+ discard;
+ }
+
+ While an important part of this language, "discard" has the potential
+ to create serious problems for users: Students who leave themselves
+ logged in to an unattended machine in a public computer lab may find
+ their script changed to just "discard". In order to protect users in
+ this situation (along with similar situations), implementations MAY
+ keep messages destroyed by a script for an indefinite period, and MAY
+ disallow scripts that throw out all mail.
+
+5. Test Commands
+
+ Tests are used in conditionals to decide which part(s) of the
+ conditional to execute.
+
+ Implementations MUST support these tests: "address", "allof",
+ "anyof", "exists", "false", "header", "not", "size", and "true".
+
+ Implementations SHOULD support the "envelope" test.
+
+
+
+
+Showalter Standards Track [Page 22]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+5.1. Test address
+
+ Syntax: address [ADDRESS-PART] [COMPARATOR] [MATCH-TYPE]
+ <header-list: string-list> <key-list: string-list>
+
+ The address test matches Internet addresses in structured headers
+ that contain addresses. It returns true if any header contains any
+ key in the specified part of the address, as modified by the
+ comparator and the match keyword.
+
+ Like envelope and header, this test returns true if any combination
+ of the header-list and key-list arguments match.
+
+ Internet email addresses [IMAIL] have the somewhat awkward
+ characteristic that the local-part to the left of the at-sign is
+ considered case sensitive, and the domain-part to the right of the
+ at-sign is case insensitive. The "address" command does not deal
+ with this itself, but provides the ADDRESS-PART argument for allowing
+ users to deal with it.
+
+ The address primitive never acts on the phrase part of an email
+ address, nor on comments within that address. It also never acts on
+ group names, although it does act on the addresses within the group
+ construct.
+
+ Implementations MUST restrict the address test to headers that
+ contain addresses, but MUST include at least From, To, Cc, Bcc,
+ Sender, Resent-From, Resent-To, and SHOULD include any other header
+ that utilizes an "address-list" structured header body.
+
+ Example: if address :is :all "from" "tim@example.com" {
+ discard;
+
+5.2. Test allof
+
+ Syntax: allof <tests: test-list>
+
+ The allof test performs a logical AND on the tests supplied to it.
+
+ Example: allof (false, false) => false
+ allof (false, true) => false
+ allof (true, true) => true
+
+ The allof test takes as its argument a test-list.
+
+
+
+
+
+
+
+Showalter Standards Track [Page 23]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+5.3. Test anyof
+
+ Syntax: anyof <tests: test-list>
+
+ The anyof test performs a logical OR on the tests supplied to it.
+
+ Example: anyof (false, false) => false
+ anyof (false, true) => true
+ anyof (true, true) => true
+
+5.4. Test envelope
+
+ Syntax: envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
+ <envelope-part: string-list> <key-list: string-list>
+
+ The "envelope" test is true if the specified part of the SMTP (or
+ equivalent) envelope matches the specified key.
+
+ If one of the envelope-part strings is (case insensitive) "from",
+ then matching occurs against the FROM address used in the SMTP MAIL
+ command.
+
+ If one of the envelope-part strings is (case insensitive) "to", then
+ matching occurs against the TO address used in the SMTP RCPT command
+ that resulted in this message getting delivered to this user. Note
+ that only the most recent TO is available, and only the one relevant
+ to this user.
+
+ The envelope-part is a string list and may contain more than one
+ parameter, in which case all of the strings specified in the key-list
+ are matched against all parts given in the envelope-part list.
+
+ Like address and header, this test returns true if any combination of
+ the envelope-part and key-list arguments is true.
+
+ All tests against envelopes MUST drop source routes.
+
+ If the SMTP transaction involved several RCPT commands, only the data
+ from the RCPT command that caused delivery to this user is available
+ in the "to" part of the envelope.
+
+ If a protocol other than SMTP is used for message transport,
+ implementations are expected to adapt this command appropriately.
+
+ The envelope command is optional. Implementations SHOULD support it,
+ but the necessary information may not be available in all cases.
+
+
+
+
+
+Showalter Standards Track [Page 24]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ Example: require "envelope";
+ if envelope :all :is "from" "tim@example.com" {
+ discard;
+ }
+
+5.5. Test exists
+
+ Syntax: exists <header-names: string-list>
+
+ The "exists" test is true if the headers listed in the header-names
+ argument exist within the message. All of the headers must exist or
+ the test is false.
+
+ The following example throws out mail that doesn't have a From header
+ and a Date header.
+
+ Example: if not exists ["From","Date"] {
+ discard;
+ }
+
+5.6. Test false
+
+ Syntax: false
+
+ The "false" test always evaluates to false.
+
+5.7. Test header
+
+ Syntax: header [COMPARATOR] [MATCH-TYPE]
+ <header-names: string-list> <key-list: string-list>
+
+ The "header" test evaluates to true if any header name matches any
+ key. The type of match is specified by the optional match argument,
+ which defaults to ":is" if not specified, as specified in section
+ 2.6.
+
+ Like address and envelope, this test returns true if any combination
+ of the string-list and key-list arguments match.
+
+ If a header listed in the header-names argument exists, it contains
+ the null key (""). However, if the named header is not present, it
+ does not contain the null key. So if a message contained the header
+
+ X-Caffeine: C8H10N4O2
+
+
+
+
+
+
+
+Showalter Standards Track [Page 25]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ these tests on that header evaluate as follows:
+
+ header :is ["X-Caffeine"] [""] => false
+ header :contains ["X-Caffeine"] [""] => true
+
+5.8. Test not
+
+ Syntax: not <test>
+
+ The "not" test takes some other test as an argument, and yields the
+ opposite result. "not false" evaluates to "true" and "not true"
+ evaluates to "false".
+
+5.9. Test size
+
+ Syntax: size <":over" / ":under"> <limit: number>
+
+ The "size" test deals with the size of a message. It takes either a
+ tagged argument of ":over" or ":under", followed by a number
+ representing the size of the message.
+
+ If the argument is ":over", and the size of the message is greater
+ than the number provided, the test is true; otherwise, it is false.
+
+ If the argument is ":under", and the size of the message is less than
+ the number provided, the test is true; otherwise, it is false.
+
+ Exactly one of ":over" or ":under" must be specified, and anything
+ else is an error.
+
+ The size of a message is defined to be the number of octets from the
+ initial header until the last character in the message body.
+
+ Note that for a message that is exactly 4,000 octets, the message is
+ neither ":over" 4000 octets or ":under" 4000 octets.
+
+5.10. Test true
+
+ Syntax: true
+
+ The "true" test always evaluates to true.
+
+6. Extensibility
+
+ New control structures, actions, and tests can be added to the
+ language. Sites must make these features known to their users; this
+ document does not define a way to discover the list of extensions
+ supported by the server.
+
+
+
+Showalter Standards Track [Page 26]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ Any extensions to this language MUST define a capability string that
+ uniquely identifies that extension. If a new version of an extension
+ changes the functionality of a previously defined extension, it MUST
+ use a different name.
+
+ In a situation where there is a submission protocol and an extension
+ advertisement mechanism aware of the details of this language,
+ scripts submitted can be checked against the mail server to prevent
+ use of an extension that the server does not support.
+
+ Extensions MUST state how they interact with constraints defined in
+ section 2.10, e.g., whether they cancel the implicit keep, and which
+ actions they are compatible and incompatible with.
+
+6.1. Capability String
+
+ Capability strings are typically short strings describing what
+ capabilities are supported by the server.
+
+ Capability strings beginning with "vnd." represent vendor-defined
+ extensions. Such extensions are not defined by Internet standards or
+ RFCs, but are still registered with IANA in order to prevent
+ conflicts. Extensions starting with "vnd." SHOULD be followed by the
+ name of the vendor and product, such as "vnd.acme.rocket-sled".
+
+ The following capability strings are defined by this document:
+
+ envelope The string "envelope" indicates that the implementation
+ supports the "envelope" command.
+
+ fileinto The string "fileinto" indicates that the implementation
+ supports the "fileinto" command.
+
+ reject The string "reject" indicates that the implementation
+ supports the "reject" command.
+
+ comparator- The string "comparator-elbonia" is provided if the
+ implementation supports the "elbonia" comparator.
+ Therefore, all implementations have at least the
+ "comparator-i;octet" and "comparator-i;ascii-casemap"
+ capabilities. However, these comparators may be used
+ without being declared with require.
+
+
+
+
+
+
+
+
+
+Showalter Standards Track [Page 27]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+6.2. IANA Considerations
+
+ In order to provide a standard set of extensions, a registry is
+ provided by IANA. Capability names may be registered on a first-
+ come, first-served basis. Extensions designed for interoperable use
+ SHOULD be defined as standards track or IESG approved experimental
+ RFCs.
+
+6.2.1. Template for Capability Registrations
+
+ The following template is to be used for registering new Sieve
+ extensions with IANA.
+
+ To: iana@iana.org
+ Subject: Registration of new Sieve extension
+
+ Capability name:
+ Capability keyword:
+ Capability arguments:
+ Standards Track/IESG-approved experimental RFC number:
+ Person and email address to contact for further information:
+
+6.2.2. Initial Capability Registrations
+
+ The following are to be added to the IANA registry for Sieve
+ extensions as the initial contents of the capability registry.
+
+ Capability name: fileinto
+ Capability keyword: fileinto
+ Capability arguments: fileinto <folder: string>
+ Standards Track/IESG-approved experimental RFC number:
+ RFC 3028 (Sieve base spec)
+ Person and email address to contact for further information:
+ Tim Showalter
+ tjs@mirapoint.com
+
+ Capability name: reject
+ Capability keyword: reject
+ Capability arguments: reject <reason: string>
+ Standards Track/IESG-approved experimental RFC number:
+ RFC 3028 (Sieve base spec)
+ Person and email address to contact for further information:
+ Tim Showalter
+ tjs@mirapoint.com
+
+
+
+
+
+
+
+Showalter Standards Track [Page 28]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ Capability name: envelope
+ Capability keyword: envelope
+ Capability arguments:
+ envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
+ <envelope-part: string-list> <key-list: string-list>
+ Standards Track/IESG-approved experimental RFC number:
+ RFC 3028 (Sieve base spec)
+ Person and email address to contact for further information:
+ Tim Showalter
+ tjs@mirapoint.com
+
+ Capability name: comparator-*
+ Capability keyword:
+ comparator-* (anything starting with "comparator-")
+ Capability arguments: (none)
+ Standards Track/IESG-approved experimental RFC number:
+ RFC 3028, Sieve, by reference of
+ RFC 2244, Application Configuration Access Protocol
+ Person and email address to contact for further information:
+ Tim Showalter
+ tjs@mirapoint.com
+
+6.3. Capability Transport
+
+ As the range of mail systems that this document is intended to apply
+ to is quite varied, a method of advertising which capabilities an
+ implementation supports is difficult due to the wide range of
+ possible implementations. Such a mechanism, however, should have
+ property that the implementation can advertise the complete set of
+ extensions that it supports.
+
+7. Transmission
+
+ The MIME type for a Sieve script is "application/sieve".
+
+ The registration of this type for RFC 2048 requirements is as
+ follows:
+
+ Subject: Registration of MIME media type application/sieve
+
+ MIME media type name: application
+ MIME subtype name: sieve
+ Required parameters: none
+ Optional parameters: none
+ Encoding considerations: Most sieve scripts will be textual,
+ written in UTF-8. When non-7bit characters are used,
+ quoted-printable is appropriate for transport systems
+ that require 7bit encoding.
+
+
+
+Showalter Standards Track [Page 29]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ Security considerations: Discussed in section 10 of RFC 3028.
+ Interoperability considerations: Discussed in section 2.10.5
+ of RFC 3028.
+ Published specification: RFC 3028.
+ Applications which use this media type: sieve-enabled mail servers
+ Additional information:
+ Magic number(s):
+ File extension(s): .siv
+ Macintosh File Type Code(s):
+ Person & email address to contact for further information:
+ See the discussion list at ietf-mta-filters@imc.org.
+ Intended usage:
+ COMMON
+ Author/Change controller:
+ See Author information in RFC 3028.
+
+8. Parsing
+
+ The Sieve grammar is separated into tokens and a separate grammar as
+ most programming languages are.
+
+8.1. Lexical Tokens
+
+ Sieve scripts are encoded in UTF-8. The following assumes a valid
+ UTF-8 encoding; special characters in Sieve scripts are all ASCII.
+
+ The following are tokens in Sieve:
+
+ - identifiers
+ - tags
+ - numbers
+ - quoted strings
+ - multi-line strings
+ - other separators
+
+ Blanks, horizontal tabs, CRLFs, and comments ("white space") are
+ ignored except as they separate tokens. Some white space is required
+ to separate otherwise adjacent tokens and in specific places in the
+ multi-line strings.
+
+ The other separators are single individual characters, and are
+ mentioned explicitly in the grammar.
+
+ The lexical structure of sieve is defined in the following BNF (as
+ described in [ABNF]):
+
+
+
+
+
+
+Showalter Standards Track [Page 30]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ bracket-comment = "/*" *(CHAR-NOT-STAR / ("*" CHAR-NOT-SLASH)) "*/"
+ ;; No */ allowed inside a comment.
+ ;; (No * is allowed unless it is the last character,
+ ;; or unless it is followed by a character that isn't a
+ ;; slash.)
+
+ CHAR-NOT-DOT = (%x01-09 / %x0b-0c / %x0e-2d / %x2f-ff)
+ ;; no dots, no CRLFs
+
+ CHAR-NOT-CRLF = (%x01-09 / %x0b-0c / %x0e-ff)
+
+ CHAR-NOT-SLASH = (%x00-57 / %x58-ff)
+
+ CHAR-NOT-STAR = (%x00-51 / %x53-ff)
+
+ comment = bracket-comment / hash-comment
+
+ hash-comment = ( "#" *CHAR-NOT-CRLF CRLF )
+
+ identifier = (ALPHA / "_") *(ALPHA DIGIT "_")
+
+ tag = ":" identifier
+
+ number = 1*DIGIT [QUANTIFIER]
+
+ QUANTIFIER = "K" / "M" / "G"
+
+ quoted-string = DQUOTE *CHAR DQUOTE
+ ;; in general, \ CHAR inside a string maps to CHAR
+ ;; so \" maps to " and \\ maps to \
+ ;; note that newlines and other characters are all allowed
+ ;; strings
+
+ multi-line = "text:" *(SP / HTAB) (hash-comment / CRLF)
+ *(multi-line-literal / multi-line-dotstuff)
+ "." CRLF
+ multi-line-literal = [CHAR-NOT-DOT *CHAR-NOT-CRLF] CRLF
+ multi-line-dotstuff = "." 1*CHAR-NOT-CRLF CRLF
+ ;; A line containing only "." ends the multi-line.
+ ;; Remove a leading '.' if followed by another '.'.
+
+ white-space = 1*(SP / CRLF / HTAB) / comment
+
+8.2. Grammar
+
+ The following is the grammar of Sieve after it has been lexically
+ interpreted. No white space or comments appear below. The start
+ symbol is "start".
+
+
+
+Showalter Standards Track [Page 31]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ argument = string-list / number / tag
+
+ arguments = *argument [test / test-list]
+
+ block = "{" commands "}"
+
+ command = identifier arguments ( ";" / block )
+
+ commands = *command
+
+ start = commands
+
+ string = quoted-string / multi-line
+
+ string-list = "[" string *("," string) "]" / string ;; if
+ there is only a single string, the brackets are optional
+
+ test = identifier arguments
+
+ test-list = "(" test *("," test) ")"
+
+9. Extended Example
+
+ The following is an extended example of a Sieve script. Note that it
+ does not make use of the implicit keep.
+
+ #
+ # Example Sieve Filter
+ # Declare any optional features or extension used by the script
+ #
+ require ["fileinto", "reject"];
+
+ #
+ # Reject any large messages (note that the four leading dots get
+ # "stuffed" to three)
+ #
+ if size :over 1M
+ {
+ reject text:
+ Please do not send me large attachments.
+ Put your file on a server and send me the URL.
+ Thank you.
+ .... Fred
+ .
+ ;
+ stop;
+ }
+ #
+
+
+
+Showalter Standards Track [Page 32]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ # Handle messages from known mailing lists
+ # Move messages from IETF filter discussion list to filter folder
+ #
+ if header :is "Sender" "owner-ietf-mta-filters@imc.org"
+ {
+ fileinto "filter"; # move to "filter" folder
+ }
+ #
+ # Keep all messages to or from people in my company
+ #
+ elsif address :domain :is ["From", "To"] "example.com"
+ {
+ keep; # keep in "In" folder
+ }
+
+ #
+ # Try and catch unsolicited email. If a message is not to me,
+ # or it contains a subject known to be spam, file it away.
+ #
+ elsif anyof (not address :all :contains
+ ["To", "Cc", "Bcc"] "me@example.com",
+ header :matches "subject"
+ ["*make*money*fast*", "*university*dipl*mas*"])
+ {
+ # If message header does not contain my address,
+ # it's from a list.
+ fileinto "spam"; # move to "spam" folder
+ }
+ else
+ {
+ # Move all other (non-company) mail to "personal"
+ # folder.
+ fileinto "personal";
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Showalter Standards Track [Page 33]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+10. Security Considerations
+
+ Users must get their mail. It is imperative that whatever method
+ implementations use to store the user-defined filtering scripts be
+ secure.
+
+ It is equally important that implementations sanity-check the user's
+ scripts, and not allow users to create on-demand mailbombs. For
+ instance, an implementation that allows a user to reject or redirect
+ multiple times to a single message might also allow a user to create
+ a mailbomb triggered by mail from a specific user. Site- or
+ implementation-defined limits on actions are useful for this.
+
+ Several commands, such as "discard", "redirect", and "fileinto" allow
+ for actions to be taken that are potentially very dangerous.
+
+ Implementations SHOULD take measures to prevent languages from
+ looping.
+
+11. Acknowledgments
+
+ I am very thankful to Chris Newman for his support and his ABNF
+ syntax checker, to John Myers and Steve Hole for outlining the
+ requirements for the original drafts, to Larry Greenfield for nagging
+ me about the grammar and finally fixing it, to Greg Sereda for
+ repeatedly fixing and providing examples, to Ned Freed for fixing
+ everything else, to Rob Earhart for an early implementation and a
+ great deal of help, and to Randall Gellens for endless amounts of
+ proofreading. I am grateful to Carnegie Mellon University where most
+ of the work on this document was done. I am also indebted to all of
+ the readers of the ietf-mta-filters@imc.org mailing list.
+
+12. Author's Address
+
+ Tim Showalter
+ Mirapoint, Inc.
+ 909 Hermosa Court
+ Sunnyvale, CA 94085
+
+ EMail: tjs@mirapoint.com
+
+13. References
+
+ [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", RFC 2234, November 1997.
+
+
+
+
+
+
+Showalter Standards Track [Page 34]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+ [ACAP] Newman, C. and J. G. Myers, "ACAP -- Application
+ Configuration Access Protocol", RFC 2244, November 1997.
+
+ [BINARY-SI] "Standard IEC 60027-2: Letter symbols to be used in
+ electrical technology - Part 2: Telecommunications and
+ electronics", January 1999.
+
+ [DSN] Moore, K. and G. Vaudreuil, "An Extensible Message Format
+ for Delivery Status Notifications", RFC 1894, January
+ 1996.
+
+ [FLAMES] Borenstein, N, and C. Thyberg, "Power, Ease of Use, and
+ Cooperative Work in a Practical Multimedia Message
+ System", Int. J. of Man-Machine Studies, April, 1991.
+ Reprinted in Computer-Supported Cooperative Work and
+ Groupware, Saul Greenberg, editor, Harcourt Brace
+ Jovanovich, 1991. Reprinted in Readings in Groupware and
+ Computer-Supported Cooperative Work, Ronald Baecker,
+ editor, Morgan Kaufmann, 1993.
+
+ [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [IMAP] Crispin, M., "Internet Message Access Protocol - version
+ 4rev1", RFC 2060, December 1996.
+
+ [IMAIL] Crocker, D., "Standard for the Format of ARPA Internet
+ Text Messages", STD 11, RFC 822, August 1982.
+
+ [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part One: Format of Internet Message
+ Bodies", RFC 2045, November 1996.
+
+ [MDN] Fajman, R., "An Extensible Message Format for Message
+ Disposition Notifications", RFC 2298, March 1998.
+
+ [RFC1123] Braden, R., "Requirements for Internet Hosts --
+ Application and Support", STD 3, RFC 1123, November 1989.
+
+ [SMTP] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC
+ 821, August 1982.
+
+ [UTF-8] Yergeau, F., "UTF-8, a transformation format of Unicode
+ and ISO 10646", RFC 2044, October 1996.
+
+
+
+
+
+
+
+Showalter Standards Track [Page 35]
+
+RFC 3028 Sieve: A Mail Filtering Language January 2001
+
+
+14. Full Copyright Statement
+
+ Copyright (C) The Internet Society (2001). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Showalter Standards Track [Page 36]
+
Added: james/mailet/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/james/mailet/trunk/src/site/site.xml?view=auto&rev=534838
==============================================================================
--- james/mailet/trunk/src/site/site.xml (added)
+++ james/mailet/trunk/src/site/site.xml Thu May 3 06:03:12 2007
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<project name="jSieve">
+ <bannerLeft>
+ <name>JAMES jSieve</name>
+ <src>images/james-jsieve-logo.gif</src>
+ <href>http://james.apache.org/</href>
+ </bannerLeft>
+
+ <bannerRight>
+ <name>The Apache Software Foundation</name>
+ <src>images/asf-logo-reduced.gif</src>
+ <href>http://www.apache.org/index.html</href>
+ </bannerRight>
+
+ <body>
+
+ <menu name="jSieve">
+ <item name="Overview" href="index.html"/>
+ <item name="RFC 2234 (ABNF)" href="rfc2234.txt"/>
+ <item name="RFC 2244 (ACAP)" href="rfc2244.txt"/>
+ <item name="RFC 2298 (MDN)" href="rfc2298.txt"/>
+ <item name="RFC 3028 (Sieve)" href="rfc3028.txt"/>
+ </menu>
+
+ ${reports}
+
+ </body>
+</project>
Added: james/mailet/trunk/src/site/xdoc/images/james-logo.jpg
URL: http://svn.apache.org/viewvc/james/mailet/trunk/src/site/xdoc/images/james-logo.jpg?view=auto&rev=534838
==============================================================================
Binary file - no diff available.
Propchange: james/mailet/trunk/src/site/xdoc/images/james-logo.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: james/mailet/trunk/src/site/xdoc/images/void.gif
URL: http://svn.apache.org/viewvc/james/mailet/trunk/src/site/xdoc/images/void.gif?view=auto&rev=534838
==============================================================================
Binary file - no diff available.
Propchange: james/mailet/trunk/src/site/xdoc/images/void.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: james/mailet/trunk/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/james/mailet/trunk/src/site/xdoc/index.xml?view=auto&rev=534838
==============================================================================
--- james/mailet/trunk/src/site/xdoc/index.xml (added)
+++ james/mailet/trunk/src/site/xdoc/index.xml Thu May 3 06:03:12 2007
@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+
+<document>
+
+ <properties>
+ <title>Overview</title>
+ <author email="mailet-api@james.apache.org">Mailet API Project</author>
+ </properties>
+
+<body>
+<section name="What is the Apache Mailet API?">
+<p>
+The Apache Mailet API is a Java API which allows the rapid development and flexible deployment of email processing functionality.
+</p>
+<p>
+The Mailet API is a subproject of <a href='http://james.apache.org'>Apache JAMES</a>.
+All who are interested in developing the Mailet API and JAMES will be warmly
+welcomed on the <a href='mail-lists.html'>mailing lists</a>.
+</p>
+</section>
+<section name="Getting Started">
+<p>Until these pages are fleshed out, the best way to understand the API is to read the
+<a href='apidocs/index.html'>Javadocs</a>
+and look at the <a href='xref/index.html'>source code</a>.
+</p>
+<subsection name='Building the Mailet API'>
+<p>
+The build uses <a href='http://ant.apache.org'>Ant</a>. <code>ant -projecthelp</code>
+describes appropriate targets. <code>ant</code> runs the default target.
+</p>
+</subsection>
+</section>
+
+<section name="Comments, Questions and Issues">
+<p>Please direct your feedback to the <a href='mail-lists.html'>mailet-api mailing list</a>.
+</p>
+</section>
+</body>
+</document>
Added: james/mailet/trunk/src/site/xdoc/stylesheets/project.xml
URL: http://svn.apache.org/viewvc/james/mailet/trunk/src/site/xdoc/stylesheets/project.xml?view=auto&rev=534838
==============================================================================
--- james/mailet/trunk/src/site/xdoc/stylesheets/project.xml (added)
+++ james/mailet/trunk/src/site/xdoc/stylesheets/project.xml Thu May 3 06:03:12 2007
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="Mailet API"
+ href="http://james.apache.org">
+
+ <title>jSieve - An RFC 3028 Compliant Mail Filtering Processor</title>
+ <logo href="/images/james-logo.jpg">jSieve - Mail Filtering Processor</logo>
+
+ <body>
+ <menu name="Mailet">
+ <item name="Overview" href="/index.html"/>
+ </menu>
+
+ <menu name="Downloads">
+ <item name="Binaries" href="http://jakarta.apache.org/site/binindex.cgi"/>
+ <item name="Source Code" href="http://jakarta.apache.org/site/sourceindex.cgi"/>
+ </menu>
+
+ <menu name="Documentation">
+ <item name="Javadocs" href="/javadocs/index.html"/>
+ </menu>
+ </body>
+</project>
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org