7Network Working Group P. Guenther, Ed.
8Request for Comments: 5228 Sendmail, Inc.
9Obsoletes: 3028 T. Showalter, Ed.
10Category: Standards Track January 2008
13 Sieve: An Email Filtering Language
17 This document specifies an Internet standards track protocol for the
18 Internet community, and requests discussion and suggestions for
19 improvements. Please refer to the current edition of the "Internet
20 Official Protocol Standards" (STD 1) for the standardization state
21 and status of this protocol. Distribution of this memo is unlimited.
25 This document describes a language for filtering email messages at
26 time of final delivery. It is designed to be implementable on either
27 a mail client or mail server. It is meant to be extensible, simple,
28 and independent of access protocol, mail architecture, and operating
29 system. It is suitable for running on a mail server where users may
30 not be allowed to execute arbitrary programs, such as on black box
31 Internet Message Access Protocol (IMAP) servers, as the base language
32 has no variables, loops, or ability to shell out to external
58Guenther & Showalter Standards Track [Page 1]
60RFC 5228 Sieve: An Email Filtering Language January 2008
65 1. Introduction ....................................................4
66 1.1. Conventions Used in This Document ..........................4
67 1.2. Example Mail Messages ......................................5
68 2. Design ..........................................................6
69 2.1. Form of the Language .......................................6
70 2.2. Whitespace .................................................7
71 2.3. Comments ...................................................7
72 2.4. Literal Data ...............................................7
73 2.4.1. Numbers .............................................7
74 2.4.2. Strings .............................................8
75 2.4.2.1. String Lists ...............................9
76 2.4.2.2. Headers ....................................9
77 2.4.2.3. Addresses .................................10
78 2.4.2.4. Encoding Characters Using
79 "encoded-character" .......................10
80 2.5. Tests .....................................................11
81 2.5.1. Test Lists .........................................12
82 2.6. Arguments .................................................12
83 2.6.1. Positional Arguments ...............................12
84 2.6.2. Tagged Arguments ...................................12
85 2.6.3. Optional Arguments .................................13
86 2.6.4. Types of Arguments .................................13
87 2.7. String Comparison .........................................13
88 2.7.1. Match Type .........................................14
89 2.7.2. Comparisons across Character Sets ..................15
90 2.7.3. Comparators ........................................15
91 2.7.4. Comparisons against Addresses ......................16
92 2.8. Blocks ....................................................17
93 2.9. Commands ..................................................17
94 2.10. Evaluation ...............................................18
95 2.10.1. Action Interaction ................................18
96 2.10.2. Implicit Keep .....................................18
97 2.10.3. Message Uniqueness in a Mailbox ...................19
98 2.10.4. Limits on Numbers of Actions ......................19
99 2.10.5. Extensions and Optional Features ..................19
100 2.10.6. Errors ............................................20
101 2.10.7. Limits on Execution ...............................20
102 3. Control Commands ...............................................21
103 3.1. Control if ................................................21
104 3.2. Control require ...........................................22
105 3.3. Control stop ..............................................22
106 4. Action Commands ................................................23
107 4.1. Action fileinto ...........................................23
108 4.2. Action redirect ...........................................23
109 4.3. Action keep ...............................................24
110 4.4. Action discard ............................................25
114Guenther & Showalter Standards Track [Page 2]
116RFC 5228 Sieve: An Email Filtering Language January 2008
119 5. Test Commands ..................................................26
120 5.1. Test address ..............................................26
121 5.2. Test allof ................................................27
122 5.3. Test anyof ................................................27
123 5.4. Test envelope .............................................27
124 5.5. Test exists ...............................................28
125 5.6. Test false ................................................28
126 5.7. Test header ...............................................29
127 5.8. Test not ..................................................29
128 5.9. Test size .................................................29
129 5.10. Test true ................................................30
130 6. Extensibility ..................................................30
131 6.1. Capability String .........................................31
132 6.2. IANA Considerations .......................................31
133 6.2.1. Template for Capability Registrations ..............32
134 6.2.2. Handling of Existing Capability Registrations ......32
135 6.2.3. Initial Capability Registrations ...................32
136 6.3. Capability Transport ......................................33
137 7. Transmission ...................................................33
138 8. Parsing ........................................................34
139 8.1. Lexical Tokens ............................................34
140 8.2. Grammar ...................................................36
141 8.3. Statement Elements ........................................36
142 9. Extended Example ...............................................37
143 10. Security Considerations .......................................38
144 11. Acknowledgments ...............................................39
145 12. Normative References ..........................................39
146 13. Informative References ........................................40
147 14. Changes from RFC 3028 .........................................41
170Guenther & Showalter Standards Track [Page 3]
172RFC 5228 Sieve: An Email Filtering Language January 2008
177 This memo documents a language that can be used to create filters for
178 electronic mail. It is not tied to any particular operating system
179 or mail architecture. It requires the use of [IMAIL]-compliant
180 messages, but should otherwise generalize to many systems.
182 The language is powerful enough to be useful but limited in order to
183 allow for a safe server-side filtering system. The intention is to
184 make it impossible for users to do anything more complex (and
185 dangerous) than write simple mail filters, along with facilitating
186 the use of graphical user interfaces (GUIs) for filter creation and
187 manipulation. The base language was not designed to be Turing-
188 complete: it does not have a loop control structure or functions.
190 Scripts written in Sieve are executed during final delivery, when the
191 message is moved to the user-accessible mailbox. In systems where
192 the Mail Transfer Agent (MTA) does final delivery, such as
193 traditional Unix mail, it is reasonable to filter when the MTA
194 deposits mail into the user's mailbox.
196 There are a number of reasons to use a filtering system. Mail
197 traffic for most users has been increasing due to increased usage of
198 email, the emergence of unsolicited email as a form of advertising,
199 and increased usage of mailing lists.
201 Experience at Carnegie Mellon has shown that if a filtering system is
202 made available to users, many will make use of it in order to file
203 messages from specific users or mailing lists. However, many others
204 did not make use of the Andrew system's FLAMES filtering language
205 [FLAMES] due to difficulty in setting it up.
207 Because of the expectation that users will make use of filtering if
208 it is offered and easy to use, this language has been made simple
209 enough to allow many users to make use of it, but rich enough that it
210 can be used productively. However, it is expected that GUI-based
211 editors will be the preferred way of editing filters for a large
2141.1. Conventions Used in This Document
216 In the sections of this document that discuss the requirements of
217 various keywords and operators, the following conventions have been
220 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
221 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
222 document are to be interpreted as described in [KEYWORDS].
226Guenther & Showalter Standards Track [Page 4]
228RFC 5228 Sieve: An Email Filtering Language January 2008
231 Each section on a command (test, action, or control) has a line
232 labeled "Usage:". This line describes the usage of the command,
233 including its name and its arguments. Required arguments are listed
234 inside angle brackets ("<" and ">"). Optional arguments are listed
235 inside square brackets ("[" and "]"). Each argument is followed by
236 its type, so "<key: string>" represents an argument called "key" that
237 is a string. Literal strings are represented with double-quoted
238 strings. Alternatives are separated with slashes, and parentheses
239 are used for grouping, similar to [ABNF].
241 In the "Usage:" line, there are three special pieces of syntax that
242 are frequently repeated, MATCH-TYPE, COMPARATOR, and ADDRESS-PART.
243 These are discussed in sections 2.7.1, 2.7.3, and 2.7.4,
246 The formal grammar for these commands is defined in section 8 and is
247 the authoritative reference on how to construct commands, but the
248 formal grammar does not specify the order, semantics, number or types
249 of arguments to commands, or the legal command names. The intent is
250 to allow for extension without changing the grammar.
2521.2. Example Mail Messages
254 The following mail messages will be used throughout this document in
258 -----------------------------------------------------------
259 Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
260 From: coyote@desert.example.org
261 To: roadrunner@acme.example.com
262 Subject: I have a present for you
264 Look, I'm sorry about the whole anvil thing, and I really
265 didn't mean to try and drop it on you from the top of the
266 cliff. I want to try to make it up to you. I've got some
267 great birdseed over here at my place--top of the line
268 stuff--and if you come by, I'll have it all wrapped up
269 for you. I'm really sorry for all the problems I've caused
270 for you over the years, but I know we can work this out.
272 Wile E. Coyote "Super Genius" coyote@desert.example.org
273 -----------------------------------------------------------
282Guenther & Showalter Standards Track [Page 5]
284RFC 5228 Sieve: An Email Filtering Language January 2008
288 -----------------------------------------------------------
289 From: youcouldberich!@reply-by-postal-mail.invalid
290 Sender: b1ff@de.res.example.com
291 To: rube@landru.example.com
292 Date: Mon, 31 Mar 1997 18:26:10 -0800
293 Subject: $$$ YOU, TOO, CAN BE A MILLIONAIRE! $$$
295 YOU MAY HAVE ALREADY WON TEN MILLION DOLLARS, BUT I DOUBT
296 IT! SO JUST POST THIS TO SIX HUNDRED NEWSGROUPS! IT WILL
297 GUARANTEE THAT YOU GET AT LEAST FIVE RESPONSES WITH MONEY!
298 MONEY! MONEY! COLD HARD CASH! YOU WILL RECEIVE OVER
299 $20,000 IN LESS THAN TWO MONTHS! AND IT'S LEGAL!!!!!!!!!
300 !!!!!!!!!!!!!!!!!!111111111!!!!!!!11111111111!!1 JUST
301 SEND $5 IN SMALL, UNMARKED BILLS TO THE ADDRESSES BELOW!
302 -----------------------------------------------------------
3062.1. Form of the Language
308 The language consists of a set of commands. Each command consists of
309 a set of tokens delimited by whitespace. The command identifier is
310 the first token and it is followed by zero or more argument tokens.
311 Arguments may be literal data, tags, blocks of commands, or test
314 With the exceptions of strings and comments, the language is limited
315 to US-ASCII characters. Strings and comments may contain octets
316 outside the US-ASCII range. Specifically, they will normally be in
317 UTF-8, as specified in [UTF-8]. NUL (US-ASCII 0) is never permitted
318 in scripts, while CR and LF can only appear as the CRLF line ending.
320 Note: While this specification permits arbitrary octets to appear
321 in Sieve scripts inside strings and comments, this has made it
322 difficult to robustly handle Sieve scripts in programs that are
323 sensitive to the encodings used. The "encoded-character"
324 capability (section 2.4.2.4) provides an alternative means of
325 representing such octets in strings using just US-ASCII
326 characters. As such, the use of non-UTF-8 text in scripts should
327 be considered a deprecated feature that may be abandoned.
329 Tokens other than strings are considered case-insensitive.
338Guenther & Showalter Standards Track [Page 6]
340RFC 5228 Sieve: An Email Filtering Language January 2008
345 Whitespace is used to separate tokens. Whitespace is made up of
346 tabs, newlines (CRLF, never just CR or LF), and the space character.
347 The amount of whitespace used is not significant.
351 Two types of comments are offered. Comments are semantically
352 equivalent to whitespace and can be used anyplace that whitespace is
353 (with one exception in multi-line strings, as described in the
356 Hash comments begin with a "#" character that is not contained within
357 a string and continue until the next CRLF.
359 Example: if size :over 100k { # this is a comment
363 Bracketed comments begin with the token "/*" and end with "*/"
364 outside of a string. Bracketed comments may span multiple lines.
365 Bracketed comments do not nest.
367 Example: if size :over 100K { /* this is a comment
368 this is still a comment */ discard /* this is a comment
374 Literal data means data that is not executed, merely evaluated "as
375 is", to be used as arguments to commands. Literal data is limited to
376 numbers, strings, and string lists.
380 Numbers are given as ordinary decimal numbers. As a shorthand for
381 expressing larger values, such as message sizes, a suffix of "K",
382 "M", or "G" MAY be appended to indicate a multiple of a power of two.
383 To be comparable with the power-of-two-based versions of SI units
384 that computers frequently use, "K" specifies kibi-, or 1,024 (2^10)
385 times the value of the number; "M" specifies mebi-, or 1,048,576
386 (2^20) times the value of the number; and "G" specifies gibi-, or
387 1,073,741,824 (2^30) times the value of the number [BINARY-SI].
394Guenther & Showalter Standards Track [Page 7]
396RFC 5228 Sieve: An Email Filtering Language January 2008
399 Implementations MUST support integer values in the inclusive range
400 zero to 2,147,483,647 (2^31 - 1), but MAY support larger values.
402 Only non-negative integers are permitted by this specification.
406 Scripts involve large numbers of string values as they are used for
407 pattern matching, addresses, textual bodies, etc. Typically, short
408 quoted strings suffice for most uses, but a more convenient form is
409 provided for longer strings such as bodies of messages.
411 A quoted string starts and ends with a single double quote (the <">
412 character, US-ASCII 34). A backslash ("\", US-ASCII 92) inside of a
413 quoted string is followed by either another backslash or a double
414 quote. These two-character sequences represent a single backslash or
415 double quote within the value, respectively.
417 Scripts SHOULD NOT escape other characters with a backslash.
419 An undefined escape sequence (such as "\a" in a context where "a" has
420 no special meaning) is interpreted as if there were no backslash (in
421 this case, "\a" is just "a"), though that may be changed by
424 Non-printing characters such as tabs, CRLF, and control characters
425 are permitted in quoted strings. Quoted strings MAY span multiple
426 lines. An unencoded NUL (US-ASCII 0) is not allowed in strings; see
427 section 2.4.2.4 for how it can be encoded.
429 As message header data is converted to [UTF-8] for comparison (see
430 section 2.7.2), most string values will use the UTF-8 encoding.
431 However, implementations MUST accept all strings that match the
432 grammar in section 8. The ability to use non-UTF-8 encoded strings
433 matches existing practice and has proven to be useful both in tests
434 for invalid data and in arguments containing raw MIME parts for
435 extension actions that generate outgoing messages.
437 For entering larger amounts of text, such as an email message, a
438 multi-line form is allowed. It starts with the keyword "text:",
439 followed by a CRLF, and ends with the sequence of a CRLF, a single
440 period, and another CRLF. The CRLF before the final period is
441 considered part of the value. In order to allow the message to
442 contain lines with a single dot, lines are dot-stuffed. That is,
443 when composing a message body, an extra '.' is added before each line
444 that begins with a '.'. When the server interprets the script, these
445 extra dots are removed. Note that a line that begins with a dot
446 followed by a non-dot character is not interpreted as dot-stuffed;
450Guenther & Showalter Standards Track [Page 8]
452RFC 5228 Sieve: An Email Filtering Language January 2008
455 that is, ".foo" is interpreted as ".foo". However, because this is
456 potentially ambiguous, scripts SHOULD be properly dot-stuffed so such
459 Note that a hashed comment or whitespace may occur in between the
460 "text:" and the CRLF, but not within the string itself. Bracketed
461 comments are not allowed here.
465 When matching patterns, it is frequently convenient to match against
466 groups of strings instead of single strings. For this reason, a list
467 of strings is allowed in many tests, implying that if the test is
468 true using any one of the strings, then the test is true.
470 For instance, the test 'header :contains ["To", "Cc"]
471 ["me@example.com", "me00@landru.example.com"]' is true if either a To
472 header or Cc header of the input message contains either of the email
473 addresses "me@example.com" or "me00@landru.example.com".
475 Conversely, in any case where a list of strings is appropriate, a
476 single string is allowed without being a member of a list: it is
477 equivalent to a list with a single member. This means that the test
478 'exists "To"' is equivalent to the test 'exists ["To"]'.
482 Headers are a subset of strings. In the Internet Message
483 Specification [IMAIL], each header line is allowed to have whitespace
484 nearly anywhere in the line, including after the field name and
485 before the subsequent colon. Extra spaces between the header name
486 and the ":" in a header field are ignored.
488 A header name never contains a colon. The "From" header refers to a
489 line beginning "From:" (or "From :", etc.). No header will match
490 the string "From:" due to the trailing colon.
492 Similarly, no header will match a syntactically invalid header name.
493 An implementation MUST NOT cause an error for syntactically invalid
494 header names in tests.
496 Header lines are unfolded as described in [IMAIL] section 2.2.3.
497 Interpretation of header data SHOULD be done according to [MIME3]
498 section 6.2 (see section 2.7.2 below for details).
506Guenther & Showalter Standards Track [Page 9]
508RFC 5228 Sieve: An Email Filtering Language January 2008
513 A number of commands call for email addresses, which are also a
514 subset of strings. When these addresses are used in outbound
515 contexts, addresses must be compliant with [IMAIL], but are further
516 constrained within this document. Using the symbols defined in
517 [IMAIL], section 3, the syntax of an address is:
519 sieve-address = addr-spec ; simple address
520 / phrase "<" addr-spec ">" ; name & addr-spec
522 That is, routes and group syntax are not permitted. If multiple
523 addresses are required, use a string list. Named groups are not
526 It is an error for a script to execute an action with a value for use
527 as an outbound address that doesn't match the "sieve-address" syntax.
5292.4.2.4. Encoding Characters Using "encoded-character"
531 When the "encoded-character" extension is in effect, certain
532 character sequences in strings are replaced by their decoded value.
533 This happens after escape sequences are interpreted and dot-
534 unstuffing has been done. Implementations SHOULD support "encoded-
537 Arbitrary octets can be embedded in strings by using the syntax
538 encoded-arb-octets. The sequence is replaced by the octets with the
539 hexadecimal values given by each hex-pair.
542 encoded-arb-octets = "${hex:" hex-pair-seq "}"
543 hex-pair-seq = *blank hex-pair *(1*blank hex-pair) *blank
546 Where WSP and HEXDIG non-terminals are defined in Appendix B.1 of
549 It may be inconvenient or undesirable to enter Unicode characters
550 verbatim, and for these cases the syntax encoded-unicode-char can be
551 used. The sequence is replaced by the UTF-8 encoding of the
552 specified Unicode characters, which are identified by the hexadecimal
553 value of unicode-hex.
555 encoded-unicode-char = "${unicode:" unicode-hex-seq "}"
556 unicode-hex-seq = *blank unicode-hex
557 *(1*blank unicode-hex) *blank
558 unicode-hex = 1*HEXDIG
562Guenther & Showalter Standards Track [Page 10]
564RFC 5228 Sieve: An Email Filtering Language January 2008
567 It is an error for a script to use a hexadecimal value that isn't in
568 either the range 0 to D7FF or the range E000 to 10FFFF. (The range
569 D800 to DFFF is excluded as those character numbers are only used as
570 part of the UTF-16 encoding form and are not applicable to the UTF-8
571 encoding that the syntax here represents.)
573 Note: Implementations MUST NOT raise an error for an out-of-range
574 Unicode value unless the sequence containing it is well-formed
575 according to the grammar.
577 The capability string for use with the require command is "encoded-
580 In the following script, message B is discarded, since the specified
581 test string is equivalent to "$$$".
583 Example: require "encoded-character";
584 if header :contains "Subject" "$${hex:24 24}" {
587 The following examples demonstrate valid and invalid encodings and
588 how they are handled:
593 "${hex:40" -> "${hex:40"
594 "${hex:400}" -> "${hex:400}"
595 "${hex:4${hex:30}}" -> "${hex:40}"
596 "${unicode:40}" -> "@"
597 "${ unicode:40}" -> "${ unicode:40}"
598 "${UNICODE:40}" -> "@"
599 "${UnICoDE:0000040}" -> "@"
600 "${Unicode:40}" -> "@"
601 "${Unicode:Cool}" -> "${Unicode:Cool}"
602 "${unicode:200000}" -> error
603 "${Unicode:DF01} -> error
607 Tests are given as arguments to commands in order to control their
608 actions. In this document, tests are given to if/elsif to decide
609 which block of code is run.
618Guenther & Showalter Standards Track [Page 11]
620RFC 5228 Sieve: An Email Filtering Language January 2008
625 Some tests ("allof" and "anyof", which implement logical "and" and
626 logical "or", respectively) may require more than a single test as an
627 argument. The test-list syntax element provides a way of grouping
628 tests as a comma-separated list in parentheses.
630 Example: if anyof (not exists ["From", "Date"],
631 header :contains "from" "fool@example.com") {
637 In order to specify what to do, most commands take arguments. There
638 are three types of arguments: positional, tagged, and optional.
640 It is an error for a script, on a single command, to use conflicting
641 arguments or to use a tagged or optional argument more than once.
6432.6.1. Positional Arguments
645 Positional arguments are given to a command that discerns their
646 meaning based on their order. When a command takes positional
647 arguments, all positional arguments must be supplied and must be in
648 the order prescribed.
6502.6.2. Tagged Arguments
652 This document provides for tagged arguments in the style of
653 CommonLISP. These are also similar to flags given to commands in
654 most command-line systems.
656 A tagged argument is an argument for a command that begins with ":"
657 followed by a tag naming the argument, such as ":contains". This
658 argument means that zero or more of the next tokens have some
659 particular meaning depending on the argument. These next tokens may
660 be literal data, but they are never blocks.
662 Tagged arguments are similar to positional arguments, except that
663 instead of the meaning being derived from the command, it is derived
666 Tagged arguments must appear before positional arguments, but they
667 may appear in any order with other tagged arguments. For simplicity
668 of the specification, this is not expressed in the syntax definitions
674Guenther & Showalter Standards Track [Page 12]
676RFC 5228 Sieve: An Email Filtering Language January 2008
679 with commands, but they still may be reordered arbitrarily provided
680 they appear before positional arguments. Tagged arguments may be
681 mixed with optional arguments.
683 Tagged arguments SHOULD NOT take tagged arguments as arguments.
6852.6.3. Optional Arguments
687 Optional arguments are exactly like tagged arguments except that they
688 may be left out, in which case a default value is implied. Because
689 optional arguments tend to result in shorter scripts, they have been
690 used far more than tagged arguments.
692 One particularly noteworthy case is the ":comparator" argument, which
693 allows the user to specify which comparator [COLLATION] will be used
694 to compare two strings, since different languages may impose
695 different orderings on UTF-8 [UTF-8] strings.
6972.6.4. Types of Arguments
699 Abstractly, arguments may be literal data, tests, or blocks of
700 commands. In this way, an "if" control structure is merely a command
701 that happens to take a test and a block as arguments and may execute
704 However, this abstraction is ambiguous from a parsing standpoint.
706 The grammar in section 8.2 presents a parsable version of this:
707 Arguments are string lists (string-lists), numbers, and tags, which
708 may be followed by a test or a test list (test-list), which may be
709 followed by a block of commands. No more than one test or test list,
710 or more than one block of commands, may be used, and commands that
711 end with a block of commands do not end with semicolons.
7132.7. String Comparison
715 When matching one string against another, there are a number of ways
716 of performing the match operation. These are accomplished with three
717 types of matches: an exact match, a substring match, and a wildcard
718 glob-style match. These are described below.
720 In order to provide for matches between character sets and case
721 insensitivity, Sieve uses the comparators defined in the Internet
722 Application Protocol Collation Registry [COLLATION].
730Guenther & Showalter Standards Track [Page 13]
732RFC 5228 Sieve: An Email Filtering Language January 2008
735 However, when a string represents the name of a header, the
736 comparator is never user-specified. Header comparisons are always
737 done with the "i;ascii-casemap" operator, i.e., case-insensitive
738 comparisons, because this is the way things are defined in the
739 message specification [IMAIL].
743 Commands that perform string comparisons may have an optional match
744 type argument. The three match types in this specification are
745 ":contains", ":is", and ":matches".
747 The ":contains" match type describes a substring match. If the value
748 argument contains the key argument as a substring, the match is true.
749 For instance, the string "frobnitzm" contains "frob" and "nit", but
750 not "fbm". The empty key ("") is contained in all values.
752 The ":is" match type describes an absolute match; if the contents of
753 the first string are absolutely the same as the contents of the
754 second string, they match. Only the string "frobnitzm" is the string
755 "frobnitzm". The empty key ("") only ":is" matches with the empty
758 The ":matches" match type specifies a wildcard match using the
759 characters "*" and "?"; the entire value must be matched. "*"
760 matches zero or more characters in the value and "?" matches a single
761 character in the value, where the comparator that is used (see
762 section 2.7.3) defines what a character is. For example, the
763 comparators "i;octet" and "i;ascii-casemap" define a character to be
764 a single octet, so "?" will always match exactly one octet when one
765 of those comparators is in use. In contrast, a Unicode-based
766 comparator would define a character to be any UTF-8 octet sequence
767 encoding one Unicode character and thus "?" may match more than one
768 octet. "?" and "*" may be escaped as "\\?" and "\\*" in strings to
769 match against themselves. The first backslash escapes the second
770 backslash; together, they escape the "*". This is awkward, but it is
771 commonplace in several programming languages that use globs and
774 In order to specify what type of match is supposed to happen,
775 commands that support matching take optional arguments ":matches",
776 ":is", and ":contains". Commands default to using ":is" matching if
777 no match type argument is supplied. Note that these modifiers
778 interact with comparators; in particular, only comparators that
779 support the "substring match" operation are suitable for matching
780 with ":contains" or ":matches". It is an error to use a comparator
781 with ":contains" or ":matches" that is not compatible with it.
786Guenther & Showalter Standards Track [Page 14]
788RFC 5228 Sieve: An Email Filtering Language January 2008
791 It is an error to give more than one of these arguments to a given
794 For convenience, the "MATCH-TYPE" syntax element is defined here as
797 Syntax: ":is" / ":contains" / ":matches"
7992.7.2. Comparisons across Character Sets
801 Messages may involve a number of character sets. In order for
802 comparisons to work across character sets, implementations SHOULD
803 implement the following behavior:
805 Comparisons are performed on octets. Implementations convert text
806 from header fields in all charsets [MIME3] to Unicode, encoded as
807 UTF-8, as input to the comparator (see section 2.7.3).
808 Implementations MUST be capable of converting US-ASCII, ISO-8859-
809 1, the US-ASCII subset of ISO-8859-* character sets, and UTF-8.
810 Text that the implementation cannot convert to Unicode for any
811 reason MAY be treated as plain US-ASCII (including any [MIME3]
812 syntax) or processed according to local conventions. An encoded
813 NUL octet (character zero) SHOULD NOT cause early termination of
814 the header content being compared against.
816 If implementations fail to support the above behavior, they MUST
817 conform to the following:
819 No two strings can be considered equal if one contains octets
824 In order to allow for language-independent, case-independent matches,
825 the match type may be coupled with a comparator name. The Internet
826 Application Protocol Collation Registry [COLLATION] provides the
827 framework for describing and naming comparators.
829 All implementations MUST support the "i;octet" comparator (simply
830 compares octets) and the "i;ascii-casemap" comparator (which treats
831 uppercase and lowercase characters in the US-ASCII subset of UTF-8 as
832 the same). If left unspecified, the default is "i;ascii-casemap".
834 Some comparators may not be usable with substring matches; that is,
835 they may only work with ":is". It is an error to try to use a
836 comparator with ":matches" or ":contains" that is not compatible with
842Guenther & Showalter Standards Track [Page 15]
844RFC 5228 Sieve: An Email Filtering Language January 2008
847 Sieve treats a comparator result of "undefined" the same as a result
848 of "no-match". That is, this base specification does not provide any
849 means to directly detect invalid comparator input.
851 A comparator is specified by the ":comparator" option with commands
852 that support matching. This option is followed by a string providing
853 the name of the comparator to be used. For convenience, the syntax
854 of a comparator is abbreviated to "COMPARATOR", and (repeated in
855 several tests) is as follows:
857 Syntax: ":comparator" <comparator-name: string>
861 Example: if header :contains :comparator "i;octet" "Subject"
866 would discard any message with subjects like "You can MAKE MONEY
867 FAST", but not "You can Make Money Fast", since the comparator used
870 Comparators other than "i;octet" and "i;ascii-casemap" must be
871 declared with require, as they are extensions. If a comparator
872 declared with require is not known, it is an error, and execution
873 fails. If the comparator is not declared with require, it is also an
874 error, even if the comparator is supported. (See section 2.10.5.)
876 Both ":matches" and ":contains" match types are compatible with the
877 "i;octet" and "i;ascii-casemap" comparators and may be used with
880 It is an error to give more than one of these arguments to a given
8832.7.4. Comparisons against Addresses
885 Addresses are one of the most frequent things represented as strings.
886 These are structured, and being able to compare against the local-
887 part or the domain of an address is useful, so some tests that act
888 exclusively on addresses take an additional optional argument that
889 specifies what the test acts on.
891 These optional arguments are ":localpart", ":domain", and ":all",
892 which act on the local-part (left side), the domain-part (right
893 side), and the whole address.
898Guenther & Showalter Standards Track [Page 16]
900RFC 5228 Sieve: An Email Filtering Language January 2008
903 If an address is not syntactically valid, then it will not be matched
904 by tests specifying ":localpart" or ":domain".
906 The kind of comparison done, such as whether or not the test done is
907 case-insensitive, is specified as a comparator argument to the test.
909 If an optional address-part is omitted, the default is ":all".
911 It is an error to give more than one of these arguments to a given
914 For convenience, the "ADDRESS-PART" syntax element is defined here as
917 Syntax: ":localpart" / ":domain" / ":all"
921 Blocks are sets of commands enclosed within curly braces and supplied
922 as the final argument to a command. Such a command is a control
923 structure: when executed it has control over the number of times the
924 commands in the block are executed.
926 With the commands supplied in this memo, there are no loops. The
927 control structures supplied--if, elsif, and else--run a block either
932 Sieve scripts are sequences of commands. Commands can take any of
933 the tokens above as arguments, and arguments may be either tagged or
934 positional arguments. Not all commands take all arguments.
936 There are three kinds of commands: test commands, action commands,
937 and control commands.
939 The simplest is an action command. An action command is an
940 identifier followed by zero or more arguments, terminated by a
941 semicolon. Action commands do not take tests or blocks as arguments.
942 The actions referenced in this document are:
944 - keep, to save the message in the default location
945 - fileinto, to save the message in a specific mailbox
946 - redirect, to forward the message to another address
947 - discard, to silently throw away the message
954Guenther & Showalter Standards Track [Page 17]
956RFC 5228 Sieve: An Email Filtering Language January 2008
959 A control command is a command that affects the parsing or the flow
960 of execution of the Sieve script in some way. A control structure is
961 a control command that ends with a block instead of a semicolon.
963 A test command is used as part of a control command. It is used to
964 specify whether or not the block of code given to the control command
9692.10.1. Action Interaction
971 Some actions cannot be used with other actions because the result
972 would be absurd. These restrictions are noted throughout this memo.
974 Extension actions MUST state how they interact with actions defined
975 in this specification.
979 Previous experience with filtering systems suggests that cases tend
980 to be missed in scripts. To prevent errors, Sieve has an "implicit
983 An implicit keep is a keep action (see section 4.3) performed in
984 absence of any action that cancels the implicit keep.
986 An implicit keep is performed if a message is not written to a
987 mailbox, redirected to a new address, or explicitly thrown out. That
988 is, if a fileinto, a keep, a redirect, or a discard is performed, an
989 implicit keep is not.
991 Some actions may be defined to not cancel the implicit keep. These
992 actions may not directly affect the delivery of a message, and are
993 used for their side effects. None of the actions specified in this
994 document meet that criteria, but extension actions may.
996 For instance, with any of the short messages offered above, the
997 following script produces no actions.
999 Example: if size :over 500K { discard; }
1001 As a result, the implicit keep is taken.
1010Guenther & Showalter Standards Track [Page 18]
1012RFC 5228 Sieve: An Email Filtering Language January 2008
10152.10.3. Message Uniqueness in a Mailbox
1017 Implementations SHOULD NOT deliver a message to the same mailbox more
1018 than once, even if a script explicitly asks for a message to be
1019 written to a mailbox twice.
1021 The test for equality of two messages is implementation-defined.
1023 If a script asks for a message to be written to a mailbox twice, it
1024 MUST NOT be treated as an error.
10262.10.4. Limits on Numbers of Actions
1028 Site policy MAY limit the number of actions taken and MAY impose
1029 restrictions on which actions can be used together. In the event
1030 that a script hits a policy limit on the number of actions taken for
1031 a particular message, an error occurs.
1033 Implementations MUST allow at least one keep or one fileinto. If
1034 fileinto is not implemented, implementations MUST allow at least one
10372.10.5. Extensions and Optional Features
1039 Because of the differing capabilities of many mail systems, several
1040 features of this specification are optional. Before any of these
1041 extensions can be executed, they must be declared with the "require"
1044 If an extension is not enabled with "require", implementations MUST
1045 treat it as if they did not support it at all. This protects scripts
1046 from having their behavior altered by extensions that the script
1047 author might not have even been aware of.
1049 Implementations MUST NOT execute any Sieve script test or command
1050 subsequent to "require" if one of the required extensions is
1053 Note: The reason for this restriction is that prior experiences
1054 with languages such as LISP and Tcl suggest that this is a
1055 workable way of noting that a given script uses an extension.
1057 Extensions that define actions MUST state how they interact with
1058 actions discussed in the base specification.
1066Guenther & Showalter Standards Track [Page 19]
1068RFC 5228 Sieve: An Email Filtering Language January 2008
1073 In any programming language, there are compile-time and run-time
1076 Compile-time errors are ones in syntax that are detectable if a
1077 syntax check is done.
1079 Run-time errors are not detectable until the script is run. This
1080 includes transient failures like disk full conditions, but also
1081 includes issues like invalid combinations of actions.
1083 When an error occurs in a Sieve script, all processing stops.
1085 Implementations MAY choose to do a full parse, then evaluate the
1086 script, then do all actions. Implementations might even go so far as
1087 to ensure that execution is atomic (either all actions are executed
1088 or none are executed).
1090 Other implementations may choose to parse and run at the same time.
1091 Such implementations are simpler, but have issues with partial
1092 failure (some actions happen, others don't).
1094 Implementations MUST perform syntactic, semantic, and run-time checks
1095 on code that is actually executed. Implementations MAY perform those
1096 checks or any part of them on code that is not reached during
1099 When an error happens, implementations MUST notify the user that an
1100 error occurred and which actions (if any) were taken, and do an
11032.10.7. Limits on Execution
1105 Implementations may limit certain constructs. However, this
1106 specification places a lower bound on some of these limits.
1108 Implementations MUST support fifteen levels of nested blocks.
1110 Implementations MUST support fifteen levels of nested test lists.
1122Guenther & Showalter Standards Track [Page 20]
1124RFC 5228 Sieve: An Email Filtering Language January 2008
1129 Control structures are needed to allow for multiple and conditional
1134 There are three pieces to if: "if", "elsif", and "else". Each is
1135 actually a separate command in terms of the grammar. However, an
1136 elsif or else MUST only follow an if or elsif. An error occurs if
1137 these conditions are not met.
1139 Usage: if <test1: test> <block1: block>
1141 Usage: elsif <test2: test> <block2: block>
1143 Usage: else <block3: block>
1145 The semantics are similar to those of any of the many other
1146 programming languages these control structures appear in. When the
1147 interpreter sees an "if", it evaluates the test associated with it.
1148 If the test is true, it executes the block associated with it.
1150 If the test of the "if" is false, it evaluates the test of the first
1151 "elsif" (if any). If the test of "elsif" is true, it runs the
1152 elsif's block. An elsif may be followed by an elsif, in which case,
1153 the interpreter repeats this process until it runs out of elsifs.
1155 When the interpreter runs out of elsifs, there may be an "else" case.
1156 If there is, and none of the if or elsif tests were true, the
1157 interpreter runs the else's block.
1159 This provides a way of performing exactly one of the blocks in the
1162 In the following example, both messages A and B are dropped.
1164 Example: require "fileinto";
1165 if header :contains "from" "coyote" {
1167 } elsif header :contains ["subject"] ["$$$"] {
1178Guenther & Showalter Standards Track [Page 21]
1180RFC 5228 Sieve: An Email Filtering Language January 2008
1183 When the script below is run over message A, it redirects the message
1184 to acm@example.com; message B, to postmaster@example.com; any other
1185 message is redirected to field@example.com.
1187 Example: if header :contains ["From"] ["coyote"] {
1188 redirect "acm@example.com";
1189 } elsif header :contains "Subject" "$$$" {
1190 redirect "postmaster@example.com";
1192 redirect "field@example.com";
1195 Note that this definition prohibits the "... else if ..." sequence
1196 used by C. This is intentional, because this construct produces a
1197 shift-reduce conflict.
1201 Usage: require <capabilities: string-list>
1203 The require action notes that a script makes use of a certain
1204 extension. Such a declaration is required to use the extension, as
1205 discussed in section 2.10.5. Multiple capabilities can be declared
1206 with a single require.
1208 The require command, if present, MUST be used before anything other
1209 than a require can be used. An error occurs if a require appears
1210 after a command other than require.
1212 Example: require ["fileinto", "reject"];
1214 Example: require "fileinto";
1221 The "stop" action ends all processing. If the implicit keep has not
1222 been cancelled, then it is taken.
1234Guenther & Showalter Standards Track [Page 22]
1236RFC 5228 Sieve: An Email Filtering Language January 2008
1241 This document supplies four actions that may be taken on a message:
1242 keep, fileinto, redirect, and discard.
1244 Implementations MUST support the "keep", "discard", and "redirect"
1247 Implementations SHOULD support "fileinto".
1249 Implementations MAY limit the number of certain actions taken (see
1254 Usage: fileinto <mailbox: string>
1256 The "fileinto" action delivers the message into the specified
1257 mailbox. Implementations SHOULD support fileinto, but in some
1258 environments this may be impossible. Implementations MAY place
1259 restrictions on mailbox names; use of an invalid mailbox name MAY be
1260 treated as an error or result in delivery to an implementation-
1261 defined mailbox. If the specified mailbox doesn't exist, the
1262 implementation MAY treat it as an error, create the mailbox, or
1263 deliver the message to an implementation-defined mailbox. If the
1264 implementation uses a different encoding scheme than UTF-8 for
1265 mailbox names, it SHOULD reencode the mailbox name from UTF-8 to its
1266 encoding scheme. For example, the Internet Message Access Protocol
1267 [IMAP] uses modified UTF-7, such that a mailbox argument of "odds &
1268 ends" would appear in IMAP as "odds &- ends".
1270 The capability string for use with the require command is "fileinto".
1272 In the following script, message A is filed into mailbox
1275 Example: require "fileinto";
1276 if header :contains ["from"] "coyote" {
1277 fileinto "INBOX.harassment";
1282 Usage: redirect <address: string>
1284 The "redirect" action is used to send the message to another user at
1285 a supplied address, as a mail forwarding feature does. The
1286 "redirect" action makes no changes to the message body or existing
1290Guenther & Showalter Standards Track [Page 23]
1292RFC 5228 Sieve: An Email Filtering Language January 2008
1295 headers, but it may add new headers. In particular, existing
1296 Received headers MUST be preserved and the count of Received headers
1297 in the outgoing message MUST be larger than the same count on the
1298 message as received by the implementation. (An implementation that
1299 adds a Received header before processing the message does not need to
1300 add another when redirecting.)
1302 The message is sent back out with the address from the redirect
1303 command as an envelope recipient. Implementations MAY combine
1304 separate redirects for a given message into a single submission with
1305 multiple envelope recipients. (This is not a Mail User Agent (MUA)-
1306 style forward, which creates a new message with a different sender
1307 and message ID, wrapping the old message in a new one.)
1309 The envelope sender address on the outgoing message is chosen by the
1310 sieve implementation. It MAY be copied from the message being
1311 processed. However, if the message being processed has an empty
1312 envelope sender address the outgoing message MUST also have an empty
1313 envelope sender address. This last requirement is imposed to prevent
1314 loops in the case where a message is redirected to an invalid address
1315 when then returns a delivery status notification that also ends up
1316 being redirected to the same invalid address.
1318 A simple script can be used for redirecting all mail:
1320 Example: redirect "bart@example.com";
1322 Implementations MUST take measures to implement loop control,
1323 possibly including adding headers to the message or counting Received
1324 headers as specified in section 6.2 of [SMTP]. If an implementation
1325 detects a loop, it causes an error.
1327 Implementations MUST provide means of limiting the number of
1328 redirects a Sieve script can perform. See section 10 for more
1331 Implementations MAY ignore a redirect action silently due to policy
1332 reasons. For example, an implementation MAY choose not to redirect
1333 to an address that is known to be undeliverable. Any ignored
1334 redirect MUST NOT cancel the implicit keep.
1340 The "keep" action is whatever action is taken in lieu of all other
1341 actions, if no filtering happens at all; generally, this simply means
1342 to file the message into the user's main mailbox. This command
1346Guenther & Showalter Standards Track [Page 24]
1348RFC 5228 Sieve: An Email Filtering Language January 2008
1351 provides a way to execute this action without needing to know the
1352 name of the user's main mailbox, providing a way to call it without
1353 needing to understand the user's setup or the underlying mail system.
1355 For instance, in an implementation where the IMAP server is running
1356 scripts on behalf of the user at time of delivery, a keep command is
1357 equivalent to a fileinto "INBOX".
1359 Example: if size :under 1M { keep; } else { discard; }
1361 Note that the above script is identical to the one below.
1363 Example: if not size :under 1M { discard; }
1369 Discard is used to silently throw away the message. It does so by
1370 simply canceling the implicit keep. If discard is used with other
1371 actions, the other actions still happen. Discard is compatible with
1372 all other actions. (For instance, fileinto+discard is equivalent to
1375 Discard MUST be silent; that is, it MUST NOT return a non-delivery
1376 notification of any kind ([DSN], [MDN], or otherwise).
1378 In the following script, any mail from "idiot@example.com" is thrown
1381 Example: if header :contains ["from"] ["idiot@example.com"] {
1385 While an important part of this language, "discard" has the potential
1386 to create serious problems for users: Students who leave themselves
1387 logged in to an unattended machine in a public computer lab may find
1388 their script changed to just "discard". In order to protect users in
1389 this situation (along with similar situations), implementations MAY
1390 keep messages destroyed by a script for an indefinite period, and MAY
1391 disallow scripts that throw out all mail.
1402Guenther & Showalter Standards Track [Page 25]
1404RFC 5228 Sieve: An Email Filtering Language January 2008
1409 Tests are used in conditionals to decide which part(s) of the
1410 conditional to execute.
1412 Implementations MUST support these tests: "address", "allof",
1413 "anyof", "exists", "false", "header", "not", "size", and "true".
1415 Implementations SHOULD support the "envelope" test.
1419 Usage: address [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
1420 <header-list: string-list> <key-list: string-list>
1422 The "address" test matches Internet addresses in structured headers
1423 that contain addresses. It returns true if any header contains any
1424 key in the specified part of the address, as modified by the
1425 comparator and the match keyword. Whether there are other addresses
1426 present in the header doesn't affect this test; this test does not
1427 provide any way to determine whether an address is the only address
1430 Like envelope and header, this test returns true if any combination
1431 of the header-list and key-list arguments match and returns false
1434 Internet email addresses [IMAIL] have the somewhat awkward
1435 characteristic that the local-part to the left of the at-sign is
1436 considered case sensitive, and the domain-part to the right of the
1437 at-sign is case insensitive. The "address" command does not deal
1438 with this itself, but provides the ADDRESS-PART argument for allowing
1439 users to deal with it.
1441 The address primitive never acts on the phrase part of an email
1442 address or on comments within that address. It also never acts on
1443 group names, although it does act on the addresses within the group
1446 Implementations MUST restrict the address test to headers that
1447 contain addresses, but MUST include at least From, To, Cc, Bcc,
1448 Sender, Resent-From, and Resent-To, and it SHOULD include any other
1449 header that utilizes an "address-list" structured header body.
1451 Example: if address :is :all "from" "tim@example.com" {
1458Guenther & Showalter Standards Track [Page 26]
1460RFC 5228 Sieve: An Email Filtering Language January 2008
1465 Usage: allof <tests: test-list>
1467 The "allof" test performs a logical AND on the tests supplied to it.
1469 Example: allof (false, false) => false
1470 allof (false, true) => false
1471 allof (true, true) => true
1473 The allof test takes as its argument a test-list.
1477 Usage: anyof <tests: test-list>
1479 The "anyof" test performs a logical OR on the tests supplied to it.
1481 Example: anyof (false, false) => false
1482 anyof (false, true) => true
1483 anyof (true, true) => true
1487 Usage: envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
1488 <envelope-part: string-list> <key-list: string-list>
1490 The "envelope" test is true if the specified part of the [SMTP] (or
1491 equivalent) envelope matches the specified key. This specification
1492 defines the interpretation of the (case insensitive) "from" and "to"
1493 envelope-parts. Additional envelope-parts may be defined by other
1494 extensions; implementations SHOULD consider unknown envelope parts an
1497 If one of the envelope-part strings is (case insensitive) "from",
1498 then matching occurs against the FROM address used in the SMTP MAIL
1499 command. The null reverse-path is matched against as the empty
1500 string, regardless of the ADDRESS-PART argument specified.
1502 If one of the envelope-part strings is (case insensitive) "to", then
1503 matching occurs against the TO address used in the SMTP RCPT command
1504 that resulted in this message getting delivered to this user. Note
1505 that only the most recent TO is available, and only the one relevant
1508 The envelope-part is a string list and may contain more than one
1509 parameter, in which case all of the strings specified in the key-list
1510 are matched against all parts given in the envelope-part list.
1514Guenther & Showalter Standards Track [Page 27]
1516RFC 5228 Sieve: An Email Filtering Language January 2008
1519 Like address and header, this test returns true if any combination of
1520 the envelope-part list and key-list arguments match and returns false
1523 All tests against envelopes MUST drop source routes.
1525 If the SMTP transaction involved several RCPT commands, only the data
1526 from the RCPT command that caused delivery to this user is available
1527 in the "to" part of the envelope.
1529 If a protocol other than SMTP is used for message transport,
1530 implementations are expected to adapt this command appropriately.
1532 The envelope command is optional. Implementations SHOULD support it,
1533 but the necessary information may not be available in all cases. The
1534 capability string for use with the require command is "envelope".
1536 Example: require "envelope";
1537 if envelope :all :is "from" "tim@example.com" {
1543 Usage: exists <header-names: string-list>
1545 The "exists" test is true if the headers listed in the header-names
1546 argument exist within the message. All of the headers must exist or
1549 The following example throws out mail that doesn't have a From header
1552 Example: if not exists ["From","Date"] {
1560 The "false" test always evaluates to false.
1570Guenther & Showalter Standards Track [Page 28]
1572RFC 5228 Sieve: An Email Filtering Language January 2008
1577 Usage: header [COMPARATOR] [MATCH-TYPE]
1578 <header-names: string-list> <key-list: string-list>
1580 The "header" test evaluates to true if the value of any of the named
1581 headers, ignoring leading and trailing whitespace, matches any key.
1582 The type of match is specified by the optional match argument, which
1583 defaults to ":is" if not specified, as specified in section 2.6.
1585 Like address and envelope, this test returns true if any combination
1586 of the header-names list and key-list arguments match and returns
1589 If a header listed in the header-names argument exists, it contains
1590 the empty key (""). However, if the named header is not present, it
1591 does not match any key, including the empty key. So if a message
1592 contained the header
1594 X-Caffeine: C8H10N4O2
1596 these tests on that header evaluate as follows:
1598 header :is ["X-Caffeine"] [""] => false
1599 header :contains ["X-Caffeine"] [""] => true
1601 Testing whether a given header is either absent or doesn't contain
1602 any non-whitespace characters can be done using a negated "header"
1605 not header :matches "Cc" "?*"
1609 Usage: not <test1: test>
1611 The "not" test takes some other test as an argument, and yields the
1612 opposite result. "not false" evaluates to "true" and "not true"
1613 evaluates to "false".
1617 Usage: size <":over" / ":under"> <limit: number>
1619 The "size" test deals with the size of a message. It takes either a
1620 tagged argument of ":over" or ":under", followed by a number
1621 representing the size of the message.
1626Guenther & Showalter Standards Track [Page 29]
1628RFC 5228 Sieve: An Email Filtering Language January 2008
1631 If the argument is ":over", and the size of the message is greater
1632 than the number provided, the test is true; otherwise, it is false.
1634 If the argument is ":under", and the size of the message is less than
1635 the number provided, the test is true; otherwise, it is false.
1637 Exactly one of ":over" or ":under" must be specified, and anything
1640 The size of a message is defined to be the number of octets in the
1641 [IMAIL] representation of the message.
1643 Note that for a message that is exactly 4,000 octets, the message is
1644 neither ":over" nor ":under" 4000 octets.
1650 The "true" test always evaluates to true.
1654 New control commands, actions, and tests can be added to the
1655 language. Sites must make these features known to their users; this
1656 document does not define a way to discover the list of extensions
1657 supported by the server.
1659 Any extensions to this language MUST define a capability string that
1660 uniquely identifies that extension. Capability string are case-
1661 sensitive; for example, "foo" and "FOO" are different capabilities.
1662 If a new version of an extension changes the functionality of a
1663 previously defined extension, it MUST use a different name.
1664 Extensions may register a set of related capabilities by registering
1665 just a unique prefix for them. The "comparator-" prefix is an
1666 example of this. The prefix MUST end with a "-" and MUST NOT overlap
1667 any existing registrations.
1669 In a situation where there is a script submission protocol and an
1670 extension advertisement mechanism aware of the details of this
1671 language, scripts submitted can be checked against the mail server to
1672 prevent use of an extension that the server does not support.
1674 Extensions MUST state how they interact with constraints defined in
1675 section 2.10, e.g., whether they cancel the implicit keep, and which
1676 actions they are compatible and incompatible with. Extensions MUST
1677 NOT change the behavior of the "require" control command or alter the
1678 interpretation of the argument to the "require" control.
1682Guenther & Showalter Standards Track [Page 30]
1684RFC 5228 Sieve: An Email Filtering Language January 2008
1687 Extensions that can submit new email messages or otherwise generate
1688 new protocol requests MUST consider loop suppression, at least to
1689 document any security considerations.
16916.1. Capability String
1693 Capability strings are typically short strings describing what
1694 capabilities are supported by the server.
1696 Capability strings beginning with "vnd." represent vendor-defined
1697 extensions. Such extensions are not defined by Internet standards or
1698 RFCs, but are still registered with IANA in order to prevent
1699 conflicts. Extensions starting with "vnd." SHOULD be followed by the
1700 name of the vendor and product, such as "vnd.acme.rocket-sled".
1702 The following capability strings are defined by this document:
1704 encoded-character The string "encoded-character" indicates that the
1705 implementation supports the interpretation of
1706 "${hex:...}" and "${unicode:...}" in strings.
1708 envelope The string "envelope" indicates that the implementation
1709 supports the "envelope" command.
1711 fileinto The string "fileinto" indicates that the implementation
1712 supports the "fileinto" command.
1714 comparator- The string "comparator-elbonia" is provided if the
1715 implementation supports the "elbonia" comparator.
1716 Therefore, all implementations have at least the
1717 "comparator-i;octet" and "comparator-i;ascii-casemap"
1718 capabilities. However, these comparators may be used
1719 without being declared with require.
17216.2. IANA Considerations
1723 In order to provide a standard set of extensions, a registry is
1724 maintained by IANA. This registry contains both vendor-controlled
1725 capability names (beginning with "vnd.") and IETF-controlled
1726 capability names. Vendor-controlled capability names may be
1727 registered on a first-come, first-served basis, by applying to IANA
1728 with the form in the following section. Registration of capability
1729 prefixes that do not begin with "vnd." REQUIRES a standards track or
1730 IESG-approved experimental RFC.
1732 Extensions designed for interoperable use SHOULD use IETF-controlled
1738Guenther & Showalter Standards Track [Page 31]
1740RFC 5228 Sieve: An Email Filtering Language January 2008
17436.2.1. Template for Capability Registrations
1745 The following template is to be used for registering new Sieve
1746 extensions with IANA.
1749 Subject: Registration of new Sieve extension
1751 Capability name: [the string for use in the 'require' statement]
1752 Description: [a brief description of what the extension adds
1754 RFC number: [for extensions published as RFCs]
1755 Contact address: [email and/or physical address to contact for
1756 additional information]
17586.2.2. Handling of Existing Capability Registrations
1760 In order to bring the existing capability registrations in line with
1761 the new template, IANA has modified each as follows:
1763 1. The "capability name" and "capability arguments" fields have been
1765 2. The "capability keyword" field have been renamed to "Capability
1767 3. An empty "Description" field has been added
1768 4. The "Standards Track/IESG-approved experimental RFC number" field
1769 has been renamed to "RFC number"
1770 5. The "Person and email address to contact for further information"
1771 field should be renamed to "Contact address"
17736.2.3. Initial Capability Registrations
1775 This RFC updates the following entries in the IANA registry for Sieve
1778 Capability name: encoded-character
1779 Description: changes the interpretation of strings to allow
1780 arbitrary octets and Unicode characters to be
1781 represented using US-ASCII
1782 RFC number: RFC 5228 (Sieve base spec)
1783 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
1785 Capability name: fileinto
1786 Description: adds the 'fileinto' action for delivering to a
1787 mailbox other than the default
1788 RFC number: RFC 5228 (Sieve base spec)
1789 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
1794Guenther & Showalter Standards Track [Page 32]
1796RFC 5228 Sieve: An Email Filtering Language January 2008
1799 Capability name: envelope
1800 Description: adds the 'envelope' test for testing the message
1801 transport sender and recipient address
1802 RFC number: RFC 5228 (Sieve base spec)
1803 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
1805 Capability name: comparator-* (anything starting with "comparator-")
1806 Description: adds the indicated comparator for use with the
1807 :comparator argument
1808 RFC number: RFC 5228 (Sieve base spec) and [COLLATION]
1809 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
18116.3. Capability Transport
1813 A method of advertising which capabilities an implementation supports
1814 is difficult due to the wide range of possible implementations. Such
1815 a mechanism, however, should have the property that the
1816 implementation can advertise the complete set of extensions that it
1821 The [MIME] type for a Sieve script is "application/sieve".
1823 The registration of this type for RFC 2048 requirements is updated as
1826 Subject: Registration of MIME media type application/sieve
1828 MIME media type name: application
1829 MIME subtype name: sieve
1830 Required parameters: none
1831 Optional parameters: none
1832 Encoding considerations: Most Sieve scripts will be textual,
1833 written in UTF-8. When non-7bit characters are used,
1834 quoted-printable is appropriate for transport systems
1835 that require 7bit encoding.
1836 Security considerations: Discussed in section 10 of this RFC.
1837 Interoperability considerations: Discussed in section 2.10.5
1839 Published specification: this RFC.
1840 Applications that use this media type: sieve-enabled mail
1842 Additional information:
1844 File extension(s): .siv .sieve
1845 Macintosh File Type Code(s):
1850Guenther & Showalter Standards Track [Page 33]
1852RFC 5228 Sieve: An Email Filtering Language January 2008
1855 Person & email address to contact for further information:
1856 See the discussion list at ietf-mta-filters@imc.org.
1859 Author/Change controller:
1860 The SIEVE WG, delegated by the IESG.
1864 The Sieve grammar is separated into tokens and a separate grammar as
1865 most programming languages are. Additional rules are supplied here
1866 for common arguments to various language facilities.
1870 Sieve scripts are encoded in UTF-8. The following assumes a valid
1871 UTF-8 encoding; special characters in Sieve scripts are all US-ASCII.
1873 The following are tokens in Sieve:
1879 - multi-line strings
1882 Identifiers, tags, and numbers are case-insensitive, while quoted
1883 strings and multi-line strings are case-sensitive.
1885 Blanks, horizontal tabs, CRLFs, and comments ("whitespace") are
1886 ignored except as they separate tokens. Some whitespace is required
1887 to separate otherwise adjacent tokens and in specific places in the
1888 multi-line strings. CR and LF can only appear in CRLF pairs.
1890 The other separators are single individual characters and are
1891 mentioned explicitly in the grammar.
1893 The lexical structure of sieve is defined in the following grammar
1894 (as described in [ABNF]):
1896 bracket-comment = "/*" *not-star 1*STAR
1897 *(not-star-slash *not-star 1*STAR) "/"
1898 ; No */ allowed inside a comment.
1899 ; (No * is allowed unless it is the last
1900 ; character, or unless it is followed by a
1901 ; character that isn't a slash.)
1906Guenther & Showalter Standards Track [Page 34]
1908RFC 5228 Sieve: An Email Filtering Language January 2008
1911 comment = bracket-comment / hash-comment
1913 hash-comment = "#" *octet-not-crlf CRLF
1915 identifier = (ALPHA / "_") *(ALPHA / DIGIT / "_")
1917 multi-line = "text:" *(SP / HTAB) (hash-comment / CRLF)
1918 *(multiline-literal / multiline-dotstart)
1921 multiline-literal = [ octet-not-period *octet-not-crlf ] CRLF
1923 multiline-dotstart = "." 1*octet-not-crlf CRLF
1924 ; A line containing only "." ends the
1925 ; multi-line. Remove a leading '.' if
1926 ; followed by another '.'.
1928 not-star = CRLF / %x01-09 / %x0B-0C / %x0E-29 / %x2B-FF
1929 ; either a CRLF pair, OR a single octet
1930 ; other than NUL, CR, LF, or star
1932 not-star-slash = CRLF / %x01-09 / %x0B-0C / %x0E-29 / %x2B-2E /
1934 ; either a CRLF pair, OR a single octet
1935 ; other than NUL, CR, LF, star, or slash
1937 number = 1*DIGIT [ QUANTIFIER ]
1939 octet-not-crlf = %x01-09 / %x0B-0C / %x0E-FF
1940 ; a single octet other than NUL, CR, or LF
1942 octet-not-period = %x01-09 / %x0B-0C / %x0E-2D / %x2F-FF
1943 ; a single octet other than NUL,
1946 octet-not-qspecial = %x01-09 / %x0B-0C / %x0E-21 / %x23-5B / %x5D-FF
1947 ; a single octet other than NUL,
1948 ; CR, LF, double-quote, or backslash
1950 QUANTIFIER = "K" / "M" / "G"
1952 quoted-other = "\" octet-not-qspecial
1953 ; represents just the octet-no-qspecial
1954 ; character. SHOULD NOT be used
1956 quoted-safe = CRLF / octet-not-qspecial
1957 ; either a CRLF pair, OR a single octet other
1958 ; than NUL, CR, LF, double-quote, or backslash
1962Guenther & Showalter Standards Track [Page 35]
1964RFC 5228 Sieve: An Email Filtering Language January 2008
1967 quoted-special = "\" (DQUOTE / "\")
1968 ; represents just a double-quote or backslash
1970 quoted-string = DQUOTE quoted-text DQUOTE
1972 quoted-text = *(quoted-safe / quoted-special / quoted-other)
1976 tag = ":" identifier
1978 white-space = 1*(SP / CRLF / HTAB) / comment
1982 The following is the grammar of Sieve after it has been lexically
1983 interpreted. No whitespace or comments appear below. The start
1986 argument = string-list / number / tag
1988 arguments = *argument [ test / test-list ]
1990 block = "{" commands "}"
1992 command = identifier arguments (";" / block)
1998 string = quoted-string / multi-line
2000 string-list = "[" string *("," string) "]" / string
2001 ; if there is only a single string, the brackets
2004 test = identifier arguments
2006 test-list = "(" test *("," test) ")"
20088.3. Statement Elements
2010 These elements are collected from the "Syntax" sections elsewhere in
2011 this document, and are provided here in [ABNF] syntax so that they
2012 can be modified by extensions.
2014 ADDRESS-PART = ":localpart" / ":domain" / ":all"
2018Guenther & Showalter Standards Track [Page 36]
2020RFC 5228 Sieve: An Email Filtering Language January 2008
2023 COMPARATOR = ":comparator" string
2025 MATCH-TYPE = ":is" / ":contains" / ":matches"
2029 The following is an extended example of a Sieve script. Note that it
2030 does not make use of the implicit keep.
2033 # Example Sieve Filter
2034 # Declare any optional features or extension used by the script
2036 require ["fileinto"];
2039 # Handle messages from known mailing lists
2040 # Move messages from IETF filter discussion list to filter mailbox
2042 if header :is "Sender" "owner-ietf-mta-filters@imc.org"
2044 fileinto "filter"; # move to "filter" mailbox
2047 # Keep all messages to or from people in my company
2049 elsif address :DOMAIN :is ["From", "To"] "example.com"
2051 keep; # keep in "In" mailbox
2055 # Try and catch unsolicited email. If a message is not to me,
2056 # or it contains a subject known to be spam, file it away.
2058 elsif anyof (NOT address :all :contains
2059 ["To", "Cc", "Bcc"] "me@example.com",
2060 header :matches "subject"
2061 ["*make*money*fast*", "*university*dipl*mas*"])
2063 fileinto "spam"; # move to "spam" mailbox
2067 # Move all other (non-company) mail to "personal"
2069 fileinto "personal";
2074Guenther & Showalter Standards Track [Page 37]
2076RFC 5228 Sieve: An Email Filtering Language January 2008
207910. Security Considerations
2081 Users must get their mail. It is imperative that whatever
2082 implementations use to store the user-defined filtering scripts
2083 protect them from unauthorized modification, to preserve the
2084 integrity of the mail system. An attacker who can modify a script
2085 can cause mail to be discarded, rejected, or forwarded to an
2086 unauthorized recipient. In addition, it's possible that Sieve
2087 scripts might expose private information, such as mailbox names, or
2088 email addresses of favored (or disfavored) correspondents. Because
2089 of that, scripts SHOULD also be protected from unauthorized
2092 Several commands, such as "discard", "redirect", and "fileinto",
2093 allow for actions to be taken that are potentially very dangerous.
2095 Use of the "redirect" command to generate notifications may easily
2096 overwhelm the target address, especially if it was not designed to
2097 handle large messages.
2099 Allowing a single script to redirect to multiple destinations can be
2100 used as a means of amplifying the number of messages in an attack.
2101 Moreover, if loop detection is not properly implemented, it may be
2102 possible to set up exponentially growing message loops. Accordingly,
2103 Sieve implementations:
2105 (1) MUST implement facilities to detect and break message loops. See
2106 section 6.2 of [SMTP] for additional information on basic loop
2107 detection strategies.
2109 (2) MUST provide the means for administrators to limit the ability of
2110 users to abuse redirect. In particular, it MUST be possible to
2111 limit the number of redirects a script can perform.
2112 Additionally, if no use cases exist for using redirect to
2113 multiple destinations, this limit SHOULD be set to 1. Additional
2114 limits, such as the ability to restrict redirect to local users,
2115 MAY also be implemented.
2117 (3) MUST provide facilities to log use of redirect in order to
2118 facilitate tracking down abuse.
2120 (4) MAY use script analysis to determine whether or not a given
2121 script can be executed safely. While the Sieve language is
2122 sufficiently complex that full analysis of all possible scripts
2123 is computationally infeasible, the majority of real-world scripts
2124 are amenable to analysis. For example, an implementation might
2130Guenther & Showalter Standards Track [Page 38]
2132RFC 5228 Sieve: An Email Filtering Language January 2008
2135 allow scripts that it has determined are safe to run unhindered,
2136 block scripts that are potentially problematic, and subject
2137 unclassifiable scripts to additional auditing and logging.
2139 Allowing redirects at all may not be appropriate in situations where
2140 email accounts are freely available and/or not trackable to a human
2141 who can be held accountable for creating message bombs or other
2144 As with any filter on a message stream, if the Sieve implementation
2145 and the mail agents 'behind' Sieve in the message stream differ in
2146 their interpretation of the messages, it may be possible for an
2147 attacker to subvert the filter. Of particular note are differences
2148 in the interpretation of malformed messages (e.g., missing or extra
2149 syntax characters) or those that exhibit corner cases (e.g., NUL
2150 octets encoded via [MIME3]).
2154 This document has been revised in part based on comments and
2155 discussions that took place on and off the SIEVE mailing list.
2156 Thanks to Sharon Chisholm, Cyrus Daboo, Ned Freed, Arnt Gulbrandsen,
2157 Michael Haardt, Kjetil Torgrim Homme, Barry Leiba, Mark E. Mallett,
2158 Alexey Melnikov, Eric Rescorla, Rob Siemborski, and Nigel Swinson for
2159 reviews and suggestions.
216112. Normative References
2163 [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for
2164 Syntax Specifications: ABNF", RFC 4234, October 2005.
2166 [COLLATION] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
2167 Application Protocol Collation Registry", RFC 4790, March
2170 [IMAIL] Resnick, P., Ed., "Internet Message Format", RFC 2822,
2173 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
2174 Requirement Levels", BCP 14, RFC 2119, March 1997.
2176 [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
2177 Extensions (MIME) Part One: Format of Internet Message
2178 Bodies", RFC 2045, November 1996.
2180 [MIME3] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
2181 Part Three: Message Header Extensions for Non-ASCII
2182 Text", RFC 2047, November 1996.
2186Guenther & Showalter Standards Track [Page 39]
2188RFC 5228 Sieve: An Email Filtering Language January 2008
2191 [SMTP] Klensin, J., Ed., "Simple Mail Transfer Protocol", RFC
2194 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
2195 10646", STD 63, RFC 3629, November 2003.
219713. Informative References
2199 [BINARY-SI] "Standard IEC 60027-2: Letter symbols to be used in
2200 electrical technology - Part 2: Telecommunications and
2201 electronics", January 1999.
2203 [DSN] Moore, K. and G. Vaudreuil, "An Extensible Message Format
2204 for Delivery Status Notifications", RFC 3464, January
2207 [FLAMES] Borenstein, N, and C. Thyberg, "Power, Ease of Use, and
2208 Cooperative Work in a Practical Multimedia Message
2209 System", Int. J. of Man-Machine Studies, April, 1991.
2210 Reprinted in Computer-Supported Cooperative Work and
2211 Groupware, Saul Greenberg, editor, Harcourt Brace
2212 Jovanovich, 1991. Reprinted in Readings in Groupware and
2213 Computer-Supported Cooperative Work, Ronald Baecker,
2214 editor, Morgan Kaufmann, 1993.
2216 [IMAP] Crispin, M., "Internet Message Access Protocol - version
2217 4rev1", RFC 3501, March 2003.
2219 [MDN] Hansen, T., Ed., and G. Vaudreuil, Ed., "Message
2220 Disposition Notification", RFC 3798, May 2004.
2222 [RFC3028] Showalter, T., "Sieve: A Mail Filtering Language", RFC
2242Guenther & Showalter Standards Track [Page 40]
2244RFC 5228 Sieve: An Email Filtering Language January 2008
224714. Changes from RFC 3028
2249 This following list is a summary of the changes that have been made
2250 in the Sieve language base specification from [RFC3028].
2252 1. Removed ban on tests having side-effects
2253 2. Removed reject extension (will be specified in a separate RFC)
2254 3. Clarified description of comparators to match [COLLATION], the
2255 new base specification for them
2256 4. Require stripping of leading and trailing whitespace in "header"
2258 5. Clarified or tightened handling of many minor items, including:
2259 - invalid [MIME3] encoding
2260 - invalid addresses in headers
2261 - invalid header field names in tests
2262 - 'undefined' comparator result
2263 - unknown envelope parts
2264 - null return-path in "envelope" test
2265 6. Capability strings are case-sensitive
2266 7. Clarified that fileinto should reencode non-ASCII mailbox
2267 names to match the mailstore's conventions
2268 8. Errors in the ABNF were corrected
2269 9. The references were updated and split into normative and
2271 10. Added encoded-character capability and deprecated (but did not
2272 remove) use of arbitrary binary octets in Sieve scripts.
2273 11. Updated IANA registration template, and added IANA
2274 considerations to permit capability prefix registrations.
2275 12. Added .sieve as a valid extension for Sieve scripts.
2281 6425 Christie St. Ste 400
2282 Emeryville, CA 94608
2283 EMail: guenther@sendmail.com
2286 EMail: tjs@psaux.com
2298Guenther & Showalter Standards Track [Page 41]
2300RFC 5228 Sieve: An Email Filtering Language January 2008
2303Full Copyright Statement
2305 Copyright (C) The IETF Trust (2008).
2307 This document is subject to the rights, licenses and restrictions
2308 contained in BCP 78, and except as set forth therein, the authors
2309 retain all their rights.
2311 This document and the information contained herein are provided on an
2312 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
2313 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
2314 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
2315 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
2316 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
2317 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
2319Intellectual Property
2321 The IETF takes no position regarding the validity or scope of any
2322 Intellectual Property Rights or other rights that might be claimed to
2323 pertain to the implementation or use of the technology described in
2324 this document or the extent to which any license under such rights
2325 might or might not be available; nor does it represent that it has
2326 made any independent effort to identify any such rights. Information
2327 on the procedures with respect to rights in RFC documents can be
2328 found in BCP 78 and BCP 79.
2330 Copies of IPR disclosures made to the IETF Secretariat and any
2331 assurances of licenses to be made available, or the result of an
2332 attempt made to obtain a general license or permission for the use of
2333 such proprietary rights by implementers or users of this
2334 specification can be obtained from the IETF on-line IPR repository at
2335 http://www.ietf.org/ipr.
2337 The IETF invites any interested party to bring to its attention any
2338 copyrights, patents or patent applications, or other proprietary
2339 rights that may cover technology that may be required to implement
2340 this standard. Please address the information to the IETF at
2354Guenther & Showalter Standards Track [Page 42]