7
Network Working Group P. Guenther, Ed.
8
Request for Comments: 5228 Sendmail, Inc.
9
Obsoletes: 3028 T. Showalter, Ed.
10
Category: 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
58
Guenther & Showalter Standards Track [Page 1]
60
RFC 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
114
Guenther & Showalter Standards Track [Page 2]
116
RFC 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
170
Guenther & Showalter Standards Track [Page 3]
172
RFC 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
214
1.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].
226
Guenther & Showalter Standards Track [Page 4]
228
RFC 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.
252
1.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
-----------------------------------------------------------
282
Guenther & Showalter Standards Track [Page 5]
284
RFC 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
-----------------------------------------------------------
306
2.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.
338
Guenther & Showalter Standards Track [Page 6]
340
RFC 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].
394
Guenther & Showalter Standards Track [Page 7]
396
RFC 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;
450
Guenther & Showalter Standards Track [Page 8]
452
RFC 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.
463
2.4.2.1. String Lists
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).
506
Guenther & Showalter Standards Track [Page 9]
508
RFC 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.
529
2.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
562
Guenther & Showalter Standards Track [Page 10]
564
RFC 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.
618
Guenther & Showalter Standards Track [Page 11]
620
RFC 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.
643
2.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.
650
2.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
674
Guenther & Showalter Standards Track [Page 12]
676
RFC 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.
685
2.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.
697
2.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.
713
2.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].
730
Guenther & Showalter Standards Track [Page 13]
732
RFC 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.
786
Guenther & Showalter Standards Track [Page 14]
788
RFC 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"
799
2.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
842
Guenther & Showalter Standards Track [Page 15]
844
RFC 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
883
2.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.
898
Guenther & Showalter Standards Track [Page 16]
900
RFC 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
954
Guenther & Showalter Standards Track [Page 17]
956
RFC 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
969
2.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.
977
2.10.2. Implicit Keep
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.
1010
Guenther & Showalter Standards Track [Page 18]
1012
RFC 5228 Sieve: An Email Filtering Language January 2008
1015
2.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.
1026
2.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
1037
2.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.
1066
Guenther & Showalter Standards Track [Page 19]
1068
RFC 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
1103
2.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.
1122
Guenther & Showalter Standards Track [Page 20]
1124
RFC 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"] ["$$$"] {
1178
Guenther & Showalter Standards Track [Page 21]
1180
RFC 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.
1199
3.2. Control require
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.
1234
Guenther & Showalter Standards Track [Page 22]
1236
RFC 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
1252
4.1. Action fileinto
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";
1280
4.2. Action redirect
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
1290
Guenther & Showalter Standards Track [Page 23]
1292
RFC 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
1346
Guenther & Showalter Standards Track [Page 24]
1348
RFC 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.
1402
Guenther & Showalter Standards Track [Page 25]
1404
RFC 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" {
1458
Guenther & Showalter Standards Track [Page 26]
1460
RFC 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.
1514
Guenther & Showalter Standards Track [Page 27]
1516
RFC 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.
1570
Guenther & Showalter Standards Track [Page 28]
1572
RFC 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.
1626
Guenther & Showalter Standards Track [Page 29]
1628
RFC 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.
1682
Guenther & Showalter Standards Track [Page 30]
1684
RFC 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.
1691
6.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.
1721
6.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
1738
Guenther & Showalter Standards Track [Page 31]
1740
RFC 5228 Sieve: An Email Filtering Language January 2008
1743
6.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]
1758
6.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"
1773
6.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>
1794
Guenther & Showalter Standards Track [Page 32]
1796
RFC 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>
1811
6.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):
1850
Guenther & Showalter Standards Track [Page 33]
1852
RFC 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.)
1906
Guenther & Showalter Standards Track [Page 34]
1908
RFC 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
1962
Guenther & Showalter Standards Track [Page 35]
1964
RFC 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) ")"
2008
8.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"
2018
Guenther & Showalter Standards Track [Page 36]
2020
RFC 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";
2074
Guenther & Showalter Standards Track [Page 37]
2076
RFC 5228 Sieve: An Email Filtering Language January 2008
2079
10. 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
2130
Guenther & Showalter Standards Track [Page 38]
2132
RFC 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.
2161
12. 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.
2186
Guenther & Showalter Standards Track [Page 39]
2188
RFC 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.
2197
13. 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
2242
Guenther & Showalter Standards Track [Page 40]
2244
RFC 5228 Sieve: An Email Filtering Language January 2008
2247
14. 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
2298
Guenther & Showalter Standards Track [Page 41]
2300
RFC 5228 Sieve: An Email Filtering Language January 2008
2303
Full 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.
2319
Intellectual 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
2354
Guenther & Showalter Standards Track [Page 42]
added
removed
libsieve/doc/rfc/sieve.rfc5228.txt
