rfc3028.txt - rohrpost - A commandline mail client to change the world as we see it.
(HTM) git clone git://r-36.net/rohrpost
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
rfc3028.txt (73582B)
---
1
2
3
4
5
6
7 Network Working Group T. Showalter
8 Request for Comments: 3028 Mirapoint, Inc.
9 Category: Standards Track January 2001
10
11
12 Sieve: A Mail Filtering Language
13
14 Status of this Memo
15
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
21
22 Copyright Notice
23
24 Copyright (C) The Internet Society (2001). All Rights Reserved.
25
26 Abstract
27
28 This document describes a language for filtering e-mail messages at
29 time of final delivery. It is designed to be implementable on either
30 a mail client or mail server. It is meant to be extensible, simple,
31 and independent of access protocol, mail architecture, and operating
32 system. It is suitable for running on a mail server where users may
33 not be allowed to execute arbitrary programs, such as on black box
34 Internet Message Access Protocol (IMAP) servers, as it has no
35 variables, loops, or ability to shell out to external programs.
36
37 Table of Contents
38
39 1. Introduction ........................................... 3
40 1.1. Conventions Used in This Document ..................... 4
41 1.2. Example mail messages ................................. 4
42 2. Design ................................................. 5
43 2.1. Form of the Language .................................. 5
44 2.2. Whitespace ............................................ 5
45 2.3. Comments .............................................. 6
46 2.4. Literal Data .......................................... 6
47 2.4.1. Numbers ............................................... 6
48 2.4.2. Strings ............................................... 7
49 2.4.2.1. String Lists .......................................... 7
50 2.4.2.2. Headers ............................................... 8
51 2.4.2.3. Addresses ............................................. 8
52 2.4.2.4. MIME Parts ............................................ 9
53 2.5. Tests ................................................. 9
54 2.5.1. Test Lists ............................................ 9
55
56
57
58 Showalter Standards Track [Page 1]
59
60 RFC 3028 Sieve: A Mail Filtering Language January 2001
61
62
63 2.6. Arguments ............................................. 9
64 2.6.1. Positional Arguments .................................. 9
65 2.6.2. Tagged Arguments ...................................... 10
66 2.6.3. Optional Arguments .................................... 10
67 2.6.4. Types of Arguments .................................... 10
68 2.7. String Comparison ..................................... 11
69 2.7.1. Match Type ............................................ 11
70 2.7.2. Comparisons Across Character Sets ..................... 12
71 2.7.3. Comparators ........................................... 12
72 2.7.4. Comparisons Against Addresses ......................... 13
73 2.8. Blocks ................................................ 14
74 2.9. Commands .............................................. 14
75 2.10. Evaluation ............................................ 15
76 2.10.1. Action Interaction .................................... 15
77 2.10.2. Implicit Keep ......................................... 15
78 2.10.3. Message Uniqueness in a Mailbox ....................... 15
79 2.10.4. Limits on Numbers of Actions .......................... 16
80 2.10.5. Extensions and Optional Features ...................... 16
81 2.10.6. Errors ................................................ 17
82 2.10.7. Limits on Execution ................................... 17
83 3. Control Commands ....................................... 17
84 3.1. Control Structure If .................................. 18
85 3.2. Control Structure Require ............................. 19
86 3.3. Control Structure Stop ................................ 19
87 4. Action Commands ........................................ 19
88 4.1. Action reject ......................................... 20
89 4.2. Action fileinto ....................................... 20
90 4.3. Action redirect ....................................... 21
91 4.4. Action keep ........................................... 21
92 4.5. Action discard ........................................ 22
93 5. Test Commands .......................................... 22
94 5.1. Test address .......................................... 23
95 5.2. Test allof ............................................ 23
96 5.3. Test anyof ............................................ 24
97 5.4. Test envelope ......................................... 24
98 5.5. Test exists ........................................... 25
99 5.6. Test false ............................................ 25
100 5.7. Test header ........................................... 25
101 5.8. Test not .............................................. 26
102 5.9. Test size ............................................. 26
103 5.10. Test true ............................................. 26
104 6. Extensibility .......................................... 26
105 6.1. Capability String ..................................... 27
106 6.2. IANA Considerations ................................... 28
107 6.2.1. Template for Capability Registrations ................. 28
108 6.2.2. Initial Capability Registrations ...................... 28
109 6.3. Capability Transport .................................. 29
110 7. Transmission ........................................... 29
111
112
113
114 Showalter Standards Track [Page 2]
115
116 RFC 3028 Sieve: A Mail Filtering Language January 2001
117
118
119 8. Parsing ................................................ 30
120 8.1. Lexical Tokens ........................................ 30
121 8.2. Grammar ............................................... 31
122 9. Extended Example ....................................... 32
123 10. Security Considerations ................................ 34
124 11. Acknowledgments ........................................ 34
125 12. Author's Address ....................................... 34
126 13. References ............................................. 34
127 14. Full Copyright Statement ............................... 36
128
129 1. Introduction
130
131 This memo documents a language that can be used to create filters for
132 electronic mail. It is not tied to any particular operating system or
133 mail architecture. It requires the use of [IMAIL]-compliant
134 messages, but should otherwise generalize to many systems.
135
136 The language is powerful enough to be useful but limited in order to
137 allow for a safe server-side filtering system. The intention is to
138 make it impossible for users to do anything more complex (and
139 dangerous) than write simple mail filters, along with facilitating
140 the use of GUIs for filter creation and manipulation. The language is
141 not Turing-complete: it provides no way to write a loop or a function
142 and variables are not provided.
143
144 Scripts written in Sieve are executed during final delivery, when the
145 message is moved to the user-accessible mailbox. In systems where
146 the MTA does final delivery, such as traditional Unix mail, it is
147 reasonable to sort when the MTA deposits mail into the user's
148 mailbox.
149
150 There are a number of reasons to use a filtering system. Mail
151 traffic for most users has been increasing due to increased usage of
152 e-mail, the emergence of unsolicited email as a form of advertising,
153 and increased usage of mailing lists.
154
155 Experience at Carnegie Mellon has shown that if a filtering system is
156 made available to users, many will make use of it in order to file
157 messages from specific users or mailing lists. However, many others
158 did not make use of the Andrew system's FLAMES filtering language
159 [FLAMES] due to difficulty in setting it up.
160
161 Because of the expectation that users will make use of filtering if
162 it is offered and easy to use, this language has been made simple
163 enough to allow many users to make use of it, but rich enough that it
164 can be used productively. However, it is expected that GUI-based
165 editors will be the preferred way of editing filters for a large
166 number of users.
167
168
169
170 Showalter Standards Track [Page 3]
171
172 RFC 3028 Sieve: A Mail Filtering Language January 2001
173
174
175 1.1. Conventions Used in This Document
176
177 In the sections of this document that discuss the requirements of
178 various keywords and operators, the following conventions have been
179 adopted.
180
181 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and
182 "MAY" in this document are to be interpreted as defined in
183 [KEYWORDS].
184
185 Each section on a command (test, action, or control structure) has a
186 line labeled "Syntax:". This line describes the syntax of the
187 command, including its name and its arguments. Required arguments
188 are listed inside angle brackets ("<" and ">"). Optional arguments
189 are listed inside square brackets ("[" and "]"). Each argument is
190 followed by its type, so "<key: string>" represents an argument
191 called "key" that is a string. Literal strings are represented with
192 double-quoted strings. Alternatives are separated with slashes, and
193 parenthesis are used for grouping, similar to [ABNF].
194
195 In the "Syntax" line, there are three special pieces of syntax that
196 are frequently repeated, MATCH-TYPE, COMPARATOR, and ADDRESS-PART.
197 These are discussed in sections 2.7.1, 2.7.3, and 2.7.4,
198 respectively.
199
200 The formal grammar for these commands in section 10 and is the
201 authoritative reference on how to construct commands, but the formal
202 grammar does not specify the order, semantics, number or types of
203 arguments to commands, nor the legal command names. The intent is to
204 allow for extension without changing the grammar.
205
206 1.2. Example mail messages
207
208 The following mail messages will be used throughout this document in
209 examples.
210
211 Message A
212 -----------------------------------------------------------
213 Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
214 From: coyote@desert.example.org
215 To: roadrunner@acme.example.com
216 Subject: I have a present for you
217
218 Look, I'm sorry about the whole anvil thing, and I really
219 didn't mean to try and drop it on you from the top of the
220 cliff. I want to try to make it up to you. I've got some
221 great birdseed over here at my place--top of the line
222
223
224
225
226 Showalter Standards Track [Page 4]
227
228 RFC 3028 Sieve: A Mail Filtering Language January 2001
229
230
231 stuff--and if you come by, I'll have it all wrapped up
232 for you. I'm really sorry for all the problems I've caused
233 for you over the years, but I know we can work this out.
234 --
235 Wile E. Coyote "Super Genius" coyote@desert.example.org
236 -----------------------------------------------------------
237
238 Message B
239 -----------------------------------------------------------
240 From: youcouldberich!@reply-by-postal-mail.invalid
241 Sender: b1ff@de.res.example.com
242 To: rube@landru.example.edu
243 Date: Mon, 31 Mar 1997 18:26:10 -0800
244 Subject: $$$ YOU, TOO, CAN BE A MILLIONAIRE! $$$
245
246 YOU MAY HAVE ALREADY WON TEN MILLION DOLLARS, BUT I DOUBT
247 IT! SO JUST POST THIS TO SIX HUNDRED NEWSGROUPS! IT WILL
248 GUARANTEE THAT YOU GET AT LEAST FIVE RESPONSES WITH MONEY!
249 MONEY! MONEY! COLD HARD CASH! YOU WILL RECEIVE OVER
250 $20,000 IN LESS THAN TWO MONTHS! AND IT'S LEGAL!!!!!!!!!
251 !!!!!!!!!!!!!!!!!!111111111!!!!!!!11111111111!!1 JUST
252 SEND $5 IN SMALL, UNMARKED BILLS TO THE ADDRESSES BELOW!
253 -----------------------------------------------------------
254
255 2. Design
256
257 2.1. Form of the Language
258
259 The language consists of a set of commands. Each command consists of
260 a set of tokens delimited by whitespace. The command identifier is
261 the first token and it is followed by zero or more argument tokens.
262 Arguments may be literal data, tags, blocks of commands, or test
263 commands.
264
265 The language is represented in UTF-8, as specified in [UTF-8].
266
267 Tokens in the ASCII range are considered case-insensitive.
268
269 2.2. Whitespace
270
271 Whitespace is used to separate tokens. Whitespace is made up of
272 tabs, newlines (CRLF, never just CR or LF), and the space character.
273 The amount of whitespace used is not significant.
274
275
276
277
278
279
280
281
282 Showalter Standards Track [Page 5]
283
284 RFC 3028 Sieve: A Mail Filtering Language January 2001
285
286
287 2.3. Comments
288
289 Two types of comments are offered. Comments are semantically
290 equivalent to whitespace and can be used anyplace that whitespace is
291 (with one exception in multi-line strings, as described in the
292 grammar).
293
294 Hash comments begin with a "#" character that is not contained within
295 a string and continue until the next CRLF.
296
297 Example: if size :over 100K { # this is a comment
298 discard;
299 }
300
301 Bracketed comments begin with the token "/*" and end with "*/" outside
302 of a string. Bracketed comments may span multiple lines. Bracketed
303 comments do not nest.
304
305 Example: if size :over 100K { /* this is a comment
306 this is still a comment */ discard /* this is a comment
307 */ ;
308 }
309
310 2.4. Literal Data
311
312 Literal data means data that is not executed, merely evaluated "as
313 is", to be used as arguments to commands. Literal data is limited to
314 numbers and strings.
315
316 2.4.1. Numbers
317
318 Numbers are given as ordinary decimal numbers. However, those
319 numbers that have a tendency to be fairly large, such as message
320 sizes, MAY have a "K", "M", or "G" appended to indicate a multiple of
321 a power of two. To be comparable with the power-of-two-based
322 versions of SI units that computers frequently use, K specifies
323 kibi-, or 1,024 (2^10) times the value of the number; M specifies
324 mebi-, or 1,048,576 (2^20) times the value of the number; and G
325 specifies tebi-, or 1,073,741,824 (2^30) times the value of the
326 number [BINARY-SI].
327
328 Implementations MUST provide 31 bits of magnitude in numbers, but MAY
329 provide more.
330
331 Only positive integers are permitted by this specification.
332
333
334
335
336
337
338 Showalter Standards Track [Page 6]
339
340 RFC 3028 Sieve: A Mail Filtering Language January 2001
341
342
343 2.4.2. Strings
344
345 Scripts involve large numbers of strings as they are used for pattern
346 matching, addresses, textual bodies, etc. Typically, short quoted
347 strings suffice for most uses, but a more convenient form is provided
348 for longer strings such as bodies of messages.
349
350 A quoted string starts and ends with a single double quote (the <">
351 character, ASCII 34). A backslash ("\", ASCII 92) inside of a quoted
352 string is followed by either another backslash or a double quote.
353 This two-character sequence represents a single backslash or double-
354 quote within the string, respectively.
355
356 No other characters should be escaped with a single backslash.
357
358 An undefined escape sequence (such as "\a" in a context where "a" has
359 no special meaning) is interpreted as if there were no backslash (in
360 this case, "\a" is just "a").
361
362 Non-printing characters such as tabs, CR and LF, and control
363 characters are permitted in quoted strings. Quoted strings MAY span
364 multiple lines. NUL (ASCII 0) is not allowed in strings.
365
366 For entering larger amounts of text, such as an email message, a
367 multi-line form is allowed. It starts with the keyword "text:",
368 followed by a CRLF, and ends with the sequence of a CRLF, a single
369 period, and another CRLF. In order to allow the message to contain
370 lines with a single-dot, lines are dot-stuffed. That is, when
371 composing a message body, an extra `.' is added before each line
372 which begins with a `.'. When the server interprets the script,
373 these extra dots are removed. Note that a line that begins with a
374 dot followed by a non-dot character is not interpreted dot-stuffed;
375 that is, ".foo" is interpreted as ".foo". However, because this is
376 potentially ambiguous, scripts SHOULD be properly dot-stuffed so such
377 lines do not appear.
378
379 Note that a hashed comment or whitespace may occur in between the
380 "text:" and the CRLF, but not within the string itself. Bracketed
381 comments are not allowed here.
382
383 2.4.2.1. String Lists
384
385 When matching patterns, it is frequently convenient to match against
386 groups of strings instead of single strings. For this reason, a list
387 of strings is allowed in many tests, implying that if the test is
388 true using any one of the strings, then the test is true.
389 Implementations are encouraged to use short-circuit evaluation in
390 these cases.
391
392
393
394 Showalter Standards Track [Page 7]
395
396 RFC 3028 Sieve: A Mail Filtering Language January 2001
397
398
399 For instance, the test `header :contains ["To", "Cc"]
400 ["me@example.com", "me00@landru.example.edu"]' is true if either the
401 To header or Cc header of the input message contains either of the
402 e-mail addresses "me@example.com" or "me00@landru.example.edu".
403
404 Conversely, in any case where a list of strings is appropriate, a
405 single string is allowed without being a member of a list: it is
406 equivalent to a list with a single member. This means that the test
407 `exists "To"' is equivalent to the test `exists ["To"]'.
408
409 2.4.2.2. Headers
410
411 Headers are a subset of strings. In the Internet Message
412 Specification [IMAIL] [RFC1123], each header line is allowed to have
413 whitespace nearly anywhere in the line, including after the field
414 name and before the subsequent colon. Extra spaces between the
415 header name and the ":" in a header field are ignored.
416
417 A header name never contains a colon. The "From" header refers to a
418 line beginning "From:" (or "From :", etc.). No header will match
419 the string "From:" due to the trailing colon.
420
421 Folding of long header lines (as described in [IMAIL] 3.4.8) is
422 removed prior to interpretation of the data. The folding syntax (the
423 CRLF that ends a line plus any leading whitespace at the beginning of
424 the next line that indicates folding) are interpreted as if they were
425 a single space.
426
427 2.4.2.3. Addresses
428
429 A number of commands call for email addresses, which are also a
430 subset of strings. When these addresses are used in outbound
431 contexts, addresses must be compliant with [IMAIL], but are further
432 constrained. Using the symbols defined in [IMAIL], section 6.1, the
433 syntax of an address is:
434
435 sieve-address = addr-spec ; simple address
436 / phrase "<" addr-spec ">" ; name & addr-spec
437
438 That is, routes and group syntax are not permitted. If multiple
439 addresses are required, use a string list. Named groups are not used
440 here.
441
442 Implementations MUST ensure that the addresses are syntactically
443 valid, but need not ensure that they actually identify an email
444 recipient.
445
446
447
448
449
450 Showalter Standards Track [Page 8]
451
452 RFC 3028 Sieve: A Mail Filtering Language January 2001
453
454
455 2.4.2.4. MIME Parts
456
457 In a few places, [MIME] body parts are represented as strings. These
458 parts include MIME headers and the body. This provides a way of
459 embedding typed data within a Sieve script so that, among other
460 things, character sets other than UTF-8 can be used for output
461 messages.
462
463 2.5. Tests
464
465 Tests are given as arguments to commands in order to control their
466 actions. In this document, tests are given to if/elsif/else to
467 decide which block of code is run.
468
469 Tests MUST NOT have side effects. That is, a test cannot affect the
470 state of the filter or message. No tests in this specification have
471 side effects, and side effects are forbidden in extension tests as
472 well.
473
474 The rationale for this is that tests with side effects impair
475 readability and maintainability and are difficult to represent in a
476 graphic interface for generating scripts. Side effects are confined
477 to actions where they are clearer.
478
479 2.5.1. Test Lists
480
481 Some tests ("allof" and "anyof", which implement logical "and" and
482 logical "or", respectively) may require more than a single test as an
483 argument. The test-list syntax element provides a way of grouping
484 tests.
485
486 Example: if anyof (not exists ["From", "Date"],
487 header :contains "from" "fool@example.edu") {
488 discard;
489 }
490
491 2.6. Arguments
492
493 In order to specify what to do, most commands take arguments. There
494 are three types of arguments: positional, tagged, and optional.
495
496 2.6.1. Positional Arguments
497
498 Positional arguments are given to a command which discerns their
499 meaning based on their order. When a command takes positional
500 arguments, all positional arguments must be supplied and must be in
501 the order prescribed.
502
503
504
505
506 Showalter Standards Track [Page 9]
507
508 RFC 3028 Sieve: A Mail Filtering Language January 2001
509
510
511 2.6.2. Tagged Arguments
512
513 This document provides for tagged arguments in the style of
514 CommonLISP. These are also similar to flags given to commands in
515 most command-line systems.
516
517 A tagged argument is an argument for a command that begins with ":"
518 followed by a tag naming the argument, such as ":contains". This
519 argument means that zero or more of the next tokens have some
520 particular meaning depending on the argument. These next tokens may
521 be numbers or strings but they are never blocks.
522
523 Tagged arguments are similar to positional arguments, except that
524 instead of the meaning being derived from the command, it is derived
525 from the tag.
526
527 Tagged arguments must appear before positional arguments, but they
528 may appear in any order with other tagged arguments. For simplicity
529 of the specification, this is not expressed in the syntax definitions
530 with commands, but they still may be reordered arbitrarily provided
531 they appear before positional arguments. Tagged arguments may be
532 mixed with optional arguments.
533
534 To simplify this specification, tagged arguments SHOULD NOT take
535 tagged arguments as arguments.
536
537 2.6.3. Optional Arguments
538
539 Optional arguments are exactly like tagged arguments except that they
540 may be left out, in which case a default value is implied. Because
541 optional arguments tend to result in shorter scripts, they have been
542 used far more than tagged arguments.
543
544 One particularly noteworthy case is the ":comparator" argument, which
545 allows the user to specify which [ACAP] comparator will be used to
546 compare two strings, since different languages may impose different
547 orderings on UTF-8 [UTF-8] characters.
548
549 2.6.4. Types of Arguments
550
551 Abstractly, arguments may be literal data, tests, or blocks of
552 commands. In this way, an "if" control structure is merely a command
553 that happens to take a test and a block as arguments and may execute
554 the block of code.
555
556 However, this abstraction is ambiguous from a parsing standpoint.
557 The grammar in section 9.2 presents a parsable version of this:
558 Arguments are string-lists, numbers, and tags, which may be followed
559
560
561
562 Showalter Standards Track [Page 10]
563
564 RFC 3028 Sieve: A Mail Filtering Language January 2001
565
566
567 by a test or a test-list, which may be followed by a block of
568 commands. No more than one test or test list, nor more than one
569 block of commands, may be used, and commands that end with blocks of
570 commands do not end with semicolons.
571
572 2.7. String Comparison
573
574 When matching one string against another, there are a number of ways
575 of performing the match operation. These are accomplished with three
576 types of matches: an exact match, a substring match, and a wildcard
577 glob-style match. These are described below.
578
579 In order to provide for matches between character sets and case
580 insensitivity, Sieve borrows ACAP's comparator registry.
581
582 However, when a string represents the name of a header, the
583 comparator is never user-specified. Header comparisons are always
584 done with the "i;ascii-casemap" operator, i.e., case-insensitive
585 comparisons, because this is the way things are defined in the
586 message specification [IMAIL].
587
588 2.7.1. Match Type
589
590 There are three match types describing the matching used in this
591 specification: ":is", ":contains", and ":matches". Match type
592 arguments are supplied to those commands which allow them to specify
593 what kind of match is to be performed.
594
595 These are used as tagged arguments to tests that perform string
596 comparison.
597
598 The ":contains" match type describes a substring match. If the value
599 argument contains the key argument as a substring, the match is true.
600 For instance, the string "frobnitzm" contains "frob" and "nit", but
601 not "fbm". The null key ("") is contained in all values.
602
603 The ":is" match type describes an absolute match; if the contents of
604 the first string are absolutely the same as the contents of the
605 second string, they match. Only the string "frobnitzm" is the string
606 "frobnitzm". The null key ":is" and only ":is" the null value.
607
608 The ":matches" version specifies a wildcard match using the
609 characters "*" and "?". "*" matches zero or more characters, and "?"
610 matches a single character. "?" and "*" may be escaped as "\\?" and
611 "\\*" in strings to match against themselves. The first backslash
612 escapes the second backslash; together, they escape the "*". This is
613 awkward, but it is commonplace in several programming languages that
614 use globs and regular expressions.
615
616
617
618 Showalter Standards Track [Page 11]
619
620 RFC 3028 Sieve: A Mail Filtering Language January 2001
621
622
623 In order to specify what type of match is supposed to happen,
624 commands that support matching take optional tagged arguments
625 ":matches", ":is", and ":contains". Commands default to using ":is"
626 matching if no match type argument is supplied. Note that these
627 modifiers may interact with comparators; in particular, some
628 comparators are not suitable for matching with ":contains" or
629 ":matches". It is an error to use a comparator with ":contains" or
630 ":matches" that is not compatible with it.
631
632 It is an error to give more than one of these arguments to a given
633 command.
634
635 For convenience, the "MATCH-TYPE" syntax element is defined here as
636 follows:
637
638 Syntax: ":is" / ":contains" / ":matches"
639
640 2.7.2. Comparisons Across Character Sets
641
642 All Sieve scripts are represented in UTF-8, but messages may involve
643 a number of character sets. In order for comparisons to work across
644 character sets, implementations SHOULD implement the following
645 behavior:
646
647 Implementations decode header charsets to UTF-8. Two strings are
648 considered equal if their UTF-8 representations are identical.
649 Implementations should decode charsets represented in the forms
650 specified by [MIME] for both message headers and bodies.
651 Implementations must be capable of decoding US-ASCII, ISO-8859-1,
652 the ASCII subset of ISO-8859-* character sets, and UTF-8.
653
654 If implementations fail to support the above behavior, they MUST
655 conform to the following:
656
657 No two strings can be considered equal if one contains octets
658 greater than 127.
659
660 2.7.3. Comparators
661
662 In order to allow for language-independent, case-independent matches,
663 the match type may be coupled with a comparator name. Comparators
664 are described for [ACAP]; a registry is defined for ACAP, and this
665 specification uses that registry.
666
667 ACAP defines multiple comparator types. Only equality types are used
668 in this specification.
669
670
671
672
673
674 Showalter Standards Track [Page 12]
675
676 RFC 3028 Sieve: A Mail Filtering Language January 2001
677
678
679 All implementations MUST support the "i;octet" comparator (simply
680 compares octets) and the "i;ascii-casemap" comparator (which treats
681 uppercase and lowercase characters in the ASCII subset of UTF-8 as
682 the same). If left unspecified, the default is "i;ascii-casemap".
683
684 Some comparators may not be usable with substring matches; that is,
685 they may only work with ":is". It is an error to try and use a
686 comparator with ":matches" or ":contains" that is not compatible with
687 it.
688
689 A comparator is specified by the ":comparator" option with commands
690 that support matching. This option is followed by a string providing
691 the name of the comparator to be used. For convenience, the syntax
692 of a comparator is abbreviated to "COMPARATOR", and (repeated in
693 several tests) is as follows:
694
695 Syntax: ":comparator" <comparator-name: string>
696
697 So in this example,
698
699 Example: if header :contains :comparator "i;octet" "Subject"
700 "MAKE MONEY FAST" {
701 discard;
702 }
703
704 would discard any message with subjects like "You can MAKE MONEY
705 FAST", but not "You can Make Money Fast", since the comparator used
706 is case-sensitive.
707
708 Comparators other than i;octet and i;ascii-casemap must be declared
709 with require, as they are extensions. If a comparator declared with
710 require is not known, it is an error, and execution fails. If the
711 comparator is not declared with require, it is also an error, even if
712 the comparator is supported. (See 2.10.5.)
713
714 Both ":matches" and ":contains" match types are compatible with the
715 "i;octet" and "i;ascii-casemap" comparators and may be used with
716 them.
717
718 It is an error to give more than one of these arguments to a given
719 command.
720
721 2.7.4. Comparisons Against Addresses
722
723 Addresses are one of the most frequent things represented as strings.
724 These are structured, and being able to compare against the local-
725 part or the domain of an address is useful, so some tests that act
726
727
728
729
730 Showalter Standards Track [Page 13]
731
732 RFC 3028 Sieve: A Mail Filtering Language January 2001
733
734
735 exclusively on addresses take an additional optional argument that
736 specifies what the test acts on.
737
738 These optional arguments are ":localpart", ":domain", and ":all",
739 which act on the local-part (left-side), the domain part (right-
740 side), and the whole address.
741
742 The kind of comparison done, such as whether or not the test done is
743 case-insensitive, is specified as a comparator argument to the test.
744
745 If an optional address-part is omitted, the default is ":all".
746
747 It is an error to give more than one of these arguments to a given
748 command.
749
750 For convenience, the "ADDRESS-PART" syntax element is defined here as
751 follows:
752
753 Syntax: ":localpart" / ":domain" / ":all"
754
755 2.8. Blocks
756
757 Blocks are sets of commands enclosed within curly braces. Blocks are
758 supplied to commands so that the commands can implement control
759 commands.
760
761 A control structure is a command that happens to take a test and a
762 block as one of its arguments; depending on the result of the test
763 supplied as another argument, it runs the code in the block some
764 number of times.
765
766 With the commands supplied in this memo, there are no loops. The
767 control structures supplied--if, elsif, and else--run a block either
768 once or not at all. So there are two arguments, the test and the
769 block.
770
771 2.9. Commands
772
773 Sieve scripts are sequences of commands. Commands can take any of
774 the tokens above as arguments, and arguments may be either tagged or
775 positional arguments. Not all commands take all arguments.
776
777 There are three kinds of commands: test commands, action commands,
778 and control commands.
779
780 The simplest is an action command. An action command is an
781 identifier followed by zero or more arguments, terminated by a
782 semicolon. Action commands do not take tests or blocks as arguments.
783
784
785
786 Showalter Standards Track [Page 14]
787
788 RFC 3028 Sieve: A Mail Filtering Language January 2001
789
790
791 A control command is similar, but it takes a test as an argument, and
792 ends with a block instead of a semicolon.
793
794 A test command is used as part of a control command. It is used to
795 specify whether or not the block of code given to the control command
796 is executed.
797
798 2.10. Evaluation
799
800 2.10.1. Action Interaction
801
802 Some actions cannot be used with other actions because the result
803 would be absurd. These restrictions are noted throughout this memo.
804
805 Extension actions MUST state how they interact with actions defined
806 in this specification.
807
808 2.10.2. Implicit Keep
809
810 Previous experience with filtering systems suggests that cases tend
811 to be missed in scripts. To prevent errors, Sieve has an "implicit
812 keep".
813
814 An implicit keep is a keep action (see 4.4) performed in absence of
815 any action that cancels the implicit keep.
816
817 An implicit keep is performed if a message is not written to a
818 mailbox, redirected to a new address, or explicitly thrown out. That
819 is, if a fileinto, a keep, a redirect, or a discard is performed, an
820 implicit keep is not.
821
822 Some actions may be defined to not cancel the implicit keep. These
823 actions may not directly affect the delivery of a message, and are
824 used for their side effects. None of the actions specified in this
825 document meet that criteria, but extension actions will.
826
827 For instance, with any of the short messages offered above, the
828 following script produces no actions.
829
830 Example: if size :over 500K { discard; }
831
832 As a result, the implicit keep is taken.
833
834 2.10.3. Message Uniqueness in a Mailbox
835
836 Implementations SHOULD NOT deliver a message to the same folder more
837 than once, even if a script explicitly asks for a message to be
838 written to a mailbox twice.
839
840
841
842 Showalter Standards Track [Page 15]
843
844 RFC 3028 Sieve: A Mail Filtering Language January 2001
845
846
847 The test for equality of two messages is implementation-defined.
848
849 If a script asks for a message to be written to a mailbox twice, it
850 MUST NOT be treated as an error.
851
852 2.10.4. Limits on Numbers of Actions
853
854 Site policy MAY limit numbers of actions taken and MAY impose
855 restrictions on which actions can be used together. In the event
856 that a script hits a policy limit on the number of actions taken for
857 a particular message, an error occurs.
858
859 Implementations MUST prohibit more than one reject.
860
861 Implementations MUST allow at least one keep or one fileinto. If
862 fileinto is not implemented, implementations MUST allow at least one
863 keep.
864
865 Implementations SHOULD prohibit reject when used with other actions.
866
867 2.10.5. Extensions and Optional Features
868
869 Because of the differing capabilities of many mail systems, several
870 features of this specification are optional. Before any of these
871 extensions can be executed, they must be declared with the "require"
872 action.
873
874 If an extension is not enabled with "require", implementations MUST
875 treat it as if they did not support it at all.
876
877 If a script does not understand an extension declared with require,
878 the script must not be used at all. Implementations MUST NOT execute
879 scripts which require unknown capability names.
880
881 Note: The reason for this restriction is that prior experiences with
882 languages such as LISP and Tcl suggest that this is a workable
883 way of noting that a given script uses an extension.
884
885 Experience with PostScript suggests that mechanisms that allow
886 a script to work around missing extensions are not used in
887 practice.
888
889 Extensions which define actions MUST state how they interact with
890 actions discussed in the base specification.
891
892
893
894
895
896
897
898 Showalter Standards Track [Page 16]
899
900 RFC 3028 Sieve: A Mail Filtering Language January 2001
901
902
903 2.10.6. Errors
904
905 In any programming language, there are compile-time and run-time
906 errors.
907
908 Compile-time errors are ones in syntax that are detectable if a
909 syntax check is done.
910
911 Run-time errors are not detectable until the script is run. This
912 includes transient failures like disk full conditions, but also
913 includes issues like invalid combinations of actions.
914
915 When an error occurs in a Sieve script, all processing stops.
916
917 Implementations MAY choose to do a full parse, then evaluate the
918 script, then do all actions. Implementations might even go so far as
919 to ensure that execution is atomic (either all actions are executed
920 or none are executed).
921
922 Other implementations may choose to parse and run at the same time.
923 Such implementations are simpler, but have issues with partial
924 failure (some actions happen, others don't).
925
926 Implementations might even go so far as to ensure that scripts can
927 never execute an invalid set of actions (e.g., reject + fileinto)
928 before execution, although this could involve solving the Halting
929 Problem.
930
931 This specification allows any of these approaches. Solving the
932 Halting Problem is considered extra credit.
933
934 When an error happens, implementations MUST notify the user that an
935 error occurred, which actions (if any) were taken, and do an implicit
936 keep.
937
938 2.10.7. Limits on Execution
939
940 Implementations may limit certain constructs. However, this
941 specification places a lower bound on some of these limits.
942
943 Implementations MUST support fifteen levels of nested blocks.
944
945 Implementations MUST support fifteen levels of nested test lists.
946
947 3. Control Commands
948
949 Control structures are needed to allow for multiple and conditional
950 actions.
951
952
953
954 Showalter Standards Track [Page 17]
955
956 RFC 3028 Sieve: A Mail Filtering Language January 2001
957
958
959 3.1. Control Structure If
960
961 There are three pieces to if: "if", "elsif", and "else". Each is
962 actually a separate command in terms of the grammar. However, an
963 elsif MUST only follow an if, and an else MUST follow only either an
964 if or an elsif. An error occurs if these conditions are not met.
965
966 Syntax: if <test1: test> <block1: block>
967
968 Syntax: elsif <test2: test> <block2: block>
969
970 Syntax: else <block>
971
972 The semantics are similar to those of any of the many other
973 programming languages these control commands appear in. When the
974 interpreter sees an "if", it evaluates the test associated with it.
975 If the test is true, it executes the block associated with it.
976
977 If the test of the "if" is false, it evaluates the test of the first
978 "elsif" (if any). If the test of "elsif" is true, it runs the
979 elsif's block. An elsif may be followed by an elsif, in which case,
980 the interpreter repeats this process until it runs out of elsifs.
981
982 When the interpreter runs out of elsifs, there may be an "else" case.
983 If there is, and none of the if or elsif tests were true, the
984 interpreter runs the else case.
985
986 This provides a way of performing exactly one of the blocks in the
987 chain.
988
989 In the following example, both Message A and B are dropped.
990
991 Example: require "fileinto";
992 if header :contains "from" "coyote" {
993 discard;
994 } elsif header :contains ["subject"] ["$$$"] {
995 discard;
996 } else {
997 fileinto "INBOX";
998 }
999
1000
1001 When the script below is run over message A, it redirects the message
1002 to acm@example.edu; message B, to postmaster@example.edu; any other
1003 message is redirected to field@example.edu.
1004
1005
1006
1007
1008
1009
1010 Showalter Standards Track [Page 18]
1011
1012 RFC 3028 Sieve: A Mail Filtering Language January 2001
1013
1014
1015 Example: if header :contains ["From"] ["coyote"] {
1016 redirect "acm@example.edu";
1017 } elsif header :contains "Subject" "$$$" {
1018 redirect "postmaster@example.edu";
1019 } else {
1020 redirect "field@example.edu";
1021 }
1022
1023 Note that this definition prohibits the "... else if ..." sequence
1024 used by C. This is intentional, because this construct produces a
1025 shift-reduce conflict.
1026
1027 3.2. Control Structure Require
1028
1029 Syntax: require <capabilities: string-list>
1030
1031 The require action notes that a script makes use of a certain
1032 extension. Such a declaration is required to use the extension, as
1033 discussed in section 2.10.5. Multiple capabilities can be declared
1034 with a single require.
1035
1036 The require command, if present, MUST be used before anything other
1037 than a require can be used. An error occurs if a require appears
1038 after a command other than require.
1039
1040 Example: require ["fileinto", "reject"];
1041
1042 Example: require "fileinto";
1043 require "vacation";
1044
1045 3.3. Control Structure Stop
1046
1047 Syntax: stop
1048
1049 The "stop" action ends all processing. If no actions have been
1050 executed, then the keep action is taken.
1051
1052 4. Action Commands
1053
1054 This document supplies five actions that may be taken on a message:
1055 keep, fileinto, redirect, reject, and discard.
1056
1057 Implementations MUST support the "keep", "discard", and "redirect"
1058 actions.
1059
1060 Implementations SHOULD support "reject" and "fileinto".
1061
1062
1063
1064
1065
1066 Showalter Standards Track [Page 19]
1067
1068 RFC 3028 Sieve: A Mail Filtering Language January 2001
1069
1070
1071 Implementations MAY limit the number of certain actions taken (see
1072 section 2.10.4).
1073
1074 4.1. Action reject
1075
1076 Syntax: reject <reason: string>
1077
1078 The optional "reject" action refuses delivery of a message by sending
1079 back an [MDN] to the sender. It resends the message to the sender,
1080 wrapping it in a "reject" form, noting that it was rejected by the
1081 recipient. In the following script, message A is rejected and
1082 returned to the sender.
1083
1084 Example: if header :contains "from" "coyote@desert.example.org" {
1085 reject "I am not taking mail from you, and I don't want
1086 your birdseed, either!";
1087 }
1088
1089 A reject message MUST take the form of a failure MDN as specified by
1090 [MDN]. The human-readable portion of the message, the first
1091 component of the MDN, contains the human readable message describing
1092 the error, and it SHOULD contain additional text alerting the
1093 original sender that mail was refused by a filter. This part of the
1094 MDN might appear as follows:
1095
1096 ------------------------------------------------------------
1097 Message was refused by recipient's mail filtering program. Reason
1098 given was as follows:
1099
1100 I am not taking mail from you, and I don't want your birdseed,
1101 either!
1102 ------------------------------------------------------------
1103
1104 The MDN action-value field as defined in the MDN specification MUST
1105 be "deleted" and MUST have the MDN-sent-automatically and automatic-
1106 action modes set.
1107
1108 Because some implementations can not or will not implement the reject
1109 command, it is optional. The capability string to be used with the
1110 require command is "reject".
1111
1112 4.2. Action fileinto
1113
1114 Syntax: fileinto <folder: string>
1115
1116 The "fileinto" action delivers the message into the specified folder.
1117 Implementations SHOULD support fileinto, but in some environments
1118 this may be impossible.
1119
1120
1121
1122 Showalter Standards Track [Page 20]
1123
1124 RFC 3028 Sieve: A Mail Filtering Language January 2001
1125
1126
1127 The capability string for use with the require command is "fileinto".
1128
1129 In the following script, message A is filed into folder
1130 "INBOX.harassment".
1131
1132 Example: require "fileinto";
1133 if header :contains ["from"] "coyote" {
1134 fileinto "INBOX.harassment";
1135 }
1136
1137 4.3. Action redirect
1138
1139 Syntax: redirect <address: string>
1140
1141 The "redirect" action is used to send the message to another user at
1142 a supplied address, as a mail forwarding feature does. The
1143 "redirect" action makes no changes to the message body or existing
1144 headers, but it may add new headers. The "redirect" modifies the
1145 envelope recipient.
1146
1147 The redirect command performs an MTA-style "forward"--that is, what
1148 you get from a .forward file using sendmail under UNIX. The address
1149 on the SMTP envelope is replaced with the one on the redirect command
1150 and the message is sent back out. (This is not an MUA-style forward,
1151 which creates a new message with a different sender and message ID,
1152 wrapping the old message in a new one.)
1153
1154 A simple script can be used for redirecting all mail:
1155
1156 Example: redirect "bart@example.edu";
1157
1158 Implementations SHOULD take measures to implement loop control,
1159 possibly including adding headers to the message or counting received
1160 headers. If an implementation detects a loop, it causes an error.
1161
1162 4.4. Action keep
1163
1164 Syntax: keep
1165
1166 The "keep" action is whatever action is taken in lieu of all other
1167 actions, if no filtering happens at all; generally, this simply means
1168 to file the message into the user's main mailbox. This command
1169 provides a way to execute this action without needing to know the
1170 name of the user's main mailbox, providing a way to call it without
1171 needing to understand the user's setup, or the underlying mail
1172 system.
1173
1174
1175
1176
1177
1178 Showalter Standards Track [Page 21]
1179
1180 RFC 3028 Sieve: A Mail Filtering Language January 2001
1181
1182
1183 For instance, in an implementation where the IMAP server is running
1184 scripts on behalf of the user at time of delivery, a keep command is
1185 equivalent to a fileinto "INBOX".
1186
1187 Example: if size :under 1M { keep; } else { discard; }
1188
1189 Note that the above script is identical to the one below.
1190
1191 Example: if not size :under 1M { discard; }
1192
1193 4.5. Action discard
1194
1195 Syntax: discard
1196
1197 Discard is used to silently throw away the message. It does so by
1198 simply canceling the implicit keep. If discard is used with other
1199 actions, the other actions still happen. Discard is compatible with
1200 all other actions. (For instance fileinto+discard is equivalent to
1201 fileinto.)
1202
1203 Discard MUST be silent; that is, it MUST NOT return a non-delivery
1204 notification of any kind ([DSN], [MDN], or otherwise).
1205
1206 In the following script, any mail from "idiot@example.edu" is thrown
1207 out.
1208
1209 Example: if header :contains ["from"] ["idiot@example.edu"] {
1210 discard;
1211 }
1212
1213 While an important part of this language, "discard" has the potential
1214 to create serious problems for users: Students who leave themselves
1215 logged in to an unattended machine in a public computer lab may find
1216 their script changed to just "discard". In order to protect users in
1217 this situation (along with similar situations), implementations MAY
1218 keep messages destroyed by a script for an indefinite period, and MAY
1219 disallow scripts that throw out all mail.
1220
1221 5. Test Commands
1222
1223 Tests are used in conditionals to decide which part(s) of the
1224 conditional to execute.
1225
1226 Implementations MUST support these tests: "address", "allof",
1227 "anyof", "exists", "false", "header", "not", "size", and "true".
1228
1229 Implementations SHOULD support the "envelope" test.
1230
1231
1232
1233
1234 Showalter Standards Track [Page 22]
1235
1236 RFC 3028 Sieve: A Mail Filtering Language January 2001
1237
1238
1239 5.1. Test address
1240
1241 Syntax: address [ADDRESS-PART] [COMPARATOR] [MATCH-TYPE]
1242 <header-list: string-list> <key-list: string-list>
1243
1244 The address test matches Internet addresses in structured headers
1245 that contain addresses. It returns true if any header contains any
1246 key in the specified part of the address, as modified by the
1247 comparator and the match keyword.
1248
1249 Like envelope and header, this test returns true if any combination
1250 of the header-list and key-list arguments match.
1251
1252 Internet email addresses [IMAIL] have the somewhat awkward
1253 characteristic that the local-part to the left of the at-sign is
1254 considered case sensitive, and the domain-part to the right of the
1255 at-sign is case insensitive. The "address" command does not deal
1256 with this itself, but provides the ADDRESS-PART argument for allowing
1257 users to deal with it.
1258
1259 The address primitive never acts on the phrase part of an email
1260 address, nor on comments within that address. It also never acts on
1261 group names, although it does act on the addresses within the group
1262 construct.
1263
1264 Implementations MUST restrict the address test to headers that
1265 contain addresses, but MUST include at least From, To, Cc, Bcc,
1266 Sender, Resent-From, Resent-To, and SHOULD include any other header
1267 that utilizes an "address-list" structured header body.
1268
1269 Example: if address :is :all "from" "tim@example.com" {
1270 discard;
1271
1272 5.2. Test allof
1273
1274 Syntax: allof <tests: test-list>
1275
1276 The allof test performs a logical AND on the tests supplied to it.
1277
1278 Example: allof (false, false) => false
1279 allof (false, true) => false
1280 allof (true, true) => true
1281
1282 The allof test takes as its argument a test-list.
1283
1284
1285
1286
1287
1288
1289
1290 Showalter Standards Track [Page 23]
1291
1292 RFC 3028 Sieve: A Mail Filtering Language January 2001
1293
1294
1295 5.3. Test anyof
1296
1297 Syntax: anyof <tests: test-list>
1298
1299 The anyof test performs a logical OR on the tests supplied to it.
1300
1301 Example: anyof (false, false) => false
1302 anyof (false, true) => true
1303 anyof (true, true) => true
1304
1305 5.4. Test envelope
1306
1307 Syntax: envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
1308 <envelope-part: string-list> <key-list: string-list>
1309
1310 The "envelope" test is true if the specified part of the SMTP (or
1311 equivalent) envelope matches the specified key.
1312
1313 If one of the envelope-part strings is (case insensitive) "from",
1314 then matching occurs against the FROM address used in the SMTP MAIL
1315 command.
1316
1317 If one of the envelope-part strings is (case insensitive) "to", then
1318 matching occurs against the TO address used in the SMTP RCPT command
1319 that resulted in this message getting delivered to this user. Note
1320 that only the most recent TO is available, and only the one relevant
1321 to this user.
1322
1323 The envelope-part is a string list and may contain more than one
1324 parameter, in which case all of the strings specified in the key-list
1325 are matched against all parts given in the envelope-part list.
1326
1327 Like address and header, this test returns true if any combination of
1328 the envelope-part and key-list arguments is true.
1329
1330 All tests against envelopes MUST drop source routes.
1331
1332 If the SMTP transaction involved several RCPT commands, only the data
1333 from the RCPT command that caused delivery to this user is available
1334 in the "to" part of the envelope.
1335
1336 If a protocol other than SMTP is used for message transport,
1337 implementations are expected to adapt this command appropriately.
1338
1339 The envelope command is optional. Implementations SHOULD support it,
1340 but the necessary information may not be available in all cases.
1341
1342
1343
1344
1345
1346 Showalter Standards Track [Page 24]
1347
1348 RFC 3028 Sieve: A Mail Filtering Language January 2001
1349
1350
1351 Example: require "envelope";
1352 if envelope :all :is "from" "tim@example.com" {
1353 discard;
1354 }
1355
1356 5.5. Test exists
1357
1358 Syntax: exists <header-names: string-list>
1359
1360 The "exists" test is true if the headers listed in the header-names
1361 argument exist within the message. All of the headers must exist or
1362 the test is false.
1363
1364 The following example throws out mail that doesn't have a From header
1365 and a Date header.
1366
1367 Example: if not exists ["From","Date"] {
1368 discard;
1369 }
1370
1371 5.6. Test false
1372
1373 Syntax: false
1374
1375 The "false" test always evaluates to false.
1376
1377 5.7. Test header
1378
1379 Syntax: header [COMPARATOR] [MATCH-TYPE]
1380 <header-names: string-list> <key-list: string-list>
1381
1382 The "header" test evaluates to true if any header name matches any
1383 key. The type of match is specified by the optional match argument,
1384 which defaults to ":is" if not specified, as specified in section
1385 2.6.
1386
1387 Like address and envelope, this test returns true if any combination
1388 of the string-list and key-list arguments match.
1389
1390 If a header listed in the header-names argument exists, it contains
1391 the null key (""). However, if the named header is not present, it
1392 does not contain the null key. So if a message contained the header
1393
1394 X-Caffeine: C8H10N4O2
1395
1396
1397
1398
1399
1400
1401
1402 Showalter Standards Track [Page 25]
1403
1404 RFC 3028 Sieve: A Mail Filtering Language January 2001
1405
1406
1407 these tests on that header evaluate as follows:
1408
1409 header :is ["X-Caffeine"] [""] => false
1410 header :contains ["X-Caffeine"] [""] => true
1411
1412 5.8. Test not
1413
1414 Syntax: not <test>
1415
1416 The "not" test takes some other test as an argument, and yields the
1417 opposite result. "not false" evaluates to "true" and "not true"
1418 evaluates to "false".
1419
1420 5.9. Test size
1421
1422 Syntax: size <":over" / ":under"> <limit: number>
1423
1424 The "size" test deals with the size of a message. It takes either a
1425 tagged argument of ":over" or ":under", followed by a number
1426 representing the size of the message.
1427
1428 If the argument is ":over", and the size of the message is greater
1429 than the number provided, the test is true; otherwise, it is false.
1430
1431 If the argument is ":under", and the size of the message is less than
1432 the number provided, the test is true; otherwise, it is false.
1433
1434 Exactly one of ":over" or ":under" must be specified, and anything
1435 else is an error.
1436
1437 The size of a message is defined to be the number of octets from the
1438 initial header until the last character in the message body.
1439
1440 Note that for a message that is exactly 4,000 octets, the message is
1441 neither ":over" 4000 octets or ":under" 4000 octets.
1442
1443 5.10. Test true
1444
1445 Syntax: true
1446
1447 The "true" test always evaluates to true.
1448
1449 6. Extensibility
1450
1451 New control structures, actions, and tests can be added to the
1452 language. Sites must make these features known to their users; this
1453 document does not define a way to discover the list of extensions
1454 supported by the server.
1455
1456
1457
1458 Showalter Standards Track [Page 26]
1459
1460 RFC 3028 Sieve: A Mail Filtering Language January 2001
1461
1462
1463 Any extensions to this language MUST define a capability string that
1464 uniquely identifies that extension. If a new version of an extension
1465 changes the functionality of a previously defined extension, it MUST
1466 use a different name.
1467
1468 In a situation where there is a submission protocol and an extension
1469 advertisement mechanism aware of the details of this language,
1470 scripts submitted can be checked against the mail server to prevent
1471 use of an extension that the server does not support.
1472
1473 Extensions MUST state how they interact with constraints defined in
1474 section 2.10, e.g., whether they cancel the implicit keep, and which
1475 actions they are compatible and incompatible with.
1476
1477 6.1. Capability String
1478
1479 Capability strings are typically short strings describing what
1480 capabilities are supported by the server.
1481
1482 Capability strings beginning with "vnd." represent vendor-defined
1483 extensions. Such extensions are not defined by Internet standards or
1484 RFCs, but are still registered with IANA in order to prevent
1485 conflicts. Extensions starting with "vnd." SHOULD be followed by the
1486 name of the vendor and product, such as "vnd.acme.rocket-sled".
1487
1488 The following capability strings are defined by this document:
1489
1490 envelope The string "envelope" indicates that the implementation
1491 supports the "envelope" command.
1492
1493 fileinto The string "fileinto" indicates that the implementation
1494 supports the "fileinto" command.
1495
1496 reject The string "reject" indicates that the implementation
1497 supports the "reject" command.
1498
1499 comparator- The string "comparator-elbonia" is provided if the
1500 implementation supports the "elbonia" comparator.
1501 Therefore, all implementations have at least the
1502 "comparator-i;octet" and "comparator-i;ascii-casemap"
1503 capabilities. However, these comparators may be used
1504 without being declared with require.
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514 Showalter Standards Track [Page 27]
1515
1516 RFC 3028 Sieve: A Mail Filtering Language January 2001
1517
1518
1519 6.2. IANA Considerations
1520
1521 In order to provide a standard set of extensions, a registry is
1522 provided by IANA. Capability names may be registered on a first-
1523 come, first-served basis. Extensions designed for interoperable use
1524 SHOULD be defined as standards track or IESG approved experimental
1525 RFCs.
1526
1527 6.2.1. Template for Capability Registrations
1528
1529 The following template is to be used for registering new Sieve
1530 extensions with IANA.
1531
1532 To: iana@iana.org
1533 Subject: Registration of new Sieve extension
1534
1535 Capability name:
1536 Capability keyword:
1537 Capability arguments:
1538 Standards Track/IESG-approved experimental RFC number:
1539 Person and email address to contact for further information:
1540
1541 6.2.2. Initial Capability Registrations
1542
1543 The following are to be added to the IANA registry for Sieve
1544 extensions as the initial contents of the capability registry.
1545
1546 Capability name: fileinto
1547 Capability keyword: fileinto
1548 Capability arguments: fileinto <folder: string>
1549 Standards Track/IESG-approved experimental RFC number:
1550 RFC 3028 (Sieve base spec)
1551 Person and email address to contact for further information:
1552 Tim Showalter
1553 tjs@mirapoint.com
1554
1555 Capability name: reject
1556 Capability keyword: reject
1557 Capability arguments: reject <reason: string>
1558 Standards Track/IESG-approved experimental RFC number:
1559 RFC 3028 (Sieve base spec)
1560 Person and email address to contact for further information:
1561 Tim Showalter
1562 tjs@mirapoint.com
1563
1564
1565
1566
1567
1568
1569
1570 Showalter Standards Track [Page 28]
1571
1572 RFC 3028 Sieve: A Mail Filtering Language January 2001
1573
1574
1575 Capability name: envelope
1576 Capability keyword: envelope
1577 Capability arguments:
1578 envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
1579 <envelope-part: string-list> <key-list: string-list>
1580 Standards Track/IESG-approved experimental RFC number:
1581 RFC 3028 (Sieve base spec)
1582 Person and email address to contact for further information:
1583 Tim Showalter
1584 tjs@mirapoint.com
1585
1586 Capability name: comparator-*
1587 Capability keyword:
1588 comparator-* (anything starting with "comparator-")
1589 Capability arguments: (none)
1590 Standards Track/IESG-approved experimental RFC number:
1591 RFC 3028, Sieve, by reference of
1592 RFC 2244, Application Configuration Access Protocol
1593 Person and email address to contact for further information:
1594 Tim Showalter
1595 tjs@mirapoint.com
1596
1597 6.3. Capability Transport
1598
1599 As the range of mail systems that this document is intended to apply
1600 to is quite varied, a method of advertising which capabilities an
1601 implementation supports is difficult due to the wide range of
1602 possible implementations. Such a mechanism, however, should have
1603 property that the implementation can advertise the complete set of
1604 extensions that it supports.
1605
1606 7. Transmission
1607
1608 The MIME type for a Sieve script is "application/sieve".
1609
1610 The registration of this type for RFC 2048 requirements is as
1611 follows:
1612
1613 Subject: Registration of MIME media type application/sieve
1614
1615 MIME media type name: application
1616 MIME subtype name: sieve
1617 Required parameters: none
1618 Optional parameters: none
1619 Encoding considerations: Most sieve scripts will be textual,
1620 written in UTF-8. When non-7bit characters are used,
1621 quoted-printable is appropriate for transport systems
1622 that require 7bit encoding.
1623
1624
1625
1626 Showalter Standards Track [Page 29]
1627
1628 RFC 3028 Sieve: A Mail Filtering Language January 2001
1629
1630
1631 Security considerations: Discussed in section 10 of RFC 3028.
1632 Interoperability considerations: Discussed in section 2.10.5
1633 of RFC 3028.
1634 Published specification: RFC 3028.
1635 Applications which use this media type: sieve-enabled mail servers
1636 Additional information:
1637 Magic number(s):
1638 File extension(s): .siv
1639 Macintosh File Type Code(s):
1640 Person & email address to contact for further information:
1641 See the discussion list at ietf-mta-filters@imc.org.
1642 Intended usage:
1643 COMMON
1644 Author/Change controller:
1645 See Author information in RFC 3028.
1646
1647 8. Parsing
1648
1649 The Sieve grammar is separated into tokens and a separate grammar as
1650 most programming languages are.
1651
1652 8.1. Lexical Tokens
1653
1654 Sieve scripts are encoded in UTF-8. The following assumes a valid
1655 UTF-8 encoding; special characters in Sieve scripts are all ASCII.
1656
1657 The following are tokens in Sieve:
1658
1659 - identifiers
1660 - tags
1661 - numbers
1662 - quoted strings
1663 - multi-line strings
1664 - other separators
1665
1666 Blanks, horizontal tabs, CRLFs, and comments ("white space") are
1667 ignored except as they separate tokens. Some white space is required
1668 to separate otherwise adjacent tokens and in specific places in the
1669 multi-line strings.
1670
1671 The other separators are single individual characters, and are
1672 mentioned explicitly in the grammar.
1673
1674 The lexical structure of sieve is defined in the following BNF (as
1675 described in [ABNF]):
1676
1677
1678
1679
1680
1681
1682 Showalter Standards Track [Page 30]
1683
1684 RFC 3028 Sieve: A Mail Filtering Language January 2001
1685
1686
1687 bracket-comment = "/*" *(CHAR-NOT-STAR / ("*" CHAR-NOT-SLASH)) "*/"
1688 ;; No */ allowed inside a comment.
1689 ;; (No * is allowed unless it is the last character,
1690 ;; or unless it is followed by a character that isn't a
1691 ;; slash.)
1692
1693 CHAR-NOT-DOT = (%x01-09 / %x0b-0c / %x0e-2d / %x2f-ff)
1694 ;; no dots, no CRLFs
1695
1696 CHAR-NOT-CRLF = (%x01-09 / %x0b-0c / %x0e-ff)
1697
1698 CHAR-NOT-SLASH = (%x00-57 / %x58-ff)
1699
1700 CHAR-NOT-STAR = (%x00-51 / %x53-ff)
1701
1702 comment = bracket-comment / hash-comment
1703
1704 hash-comment = ( "#" *CHAR-NOT-CRLF CRLF )
1705
1706 identifier = (ALPHA / "_") *(ALPHA DIGIT "_")
1707
1708 tag = ":" identifier
1709
1710 number = 1*DIGIT [QUANTIFIER]
1711
1712 QUANTIFIER = "K" / "M" / "G"
1713
1714 quoted-string = DQUOTE *CHAR DQUOTE
1715 ;; in general, \ CHAR inside a string maps to CHAR
1716 ;; so \" maps to " and \\ maps to \
1717 ;; note that newlines and other characters are all allowed
1718 ;; strings
1719
1720 multi-line = "text:" *(SP / HTAB) (hash-comment / CRLF)
1721 *(multi-line-literal / multi-line-dotstuff)
1722 "." CRLF
1723 multi-line-literal = [CHAR-NOT-DOT *CHAR-NOT-CRLF] CRLF
1724 multi-line-dotstuff = "." 1*CHAR-NOT-CRLF CRLF
1725 ;; A line containing only "." ends the multi-line.
1726 ;; Remove a leading '.' if followed by another '.'.
1727
1728 white-space = 1*(SP / CRLF / HTAB) / comment
1729
1730 8.2. Grammar
1731
1732 The following is the grammar of Sieve after it has been lexically
1733 interpreted. No white space or comments appear below. The start
1734 symbol is "start".
1735
1736
1737
1738 Showalter Standards Track [Page 31]
1739
1740 RFC 3028 Sieve: A Mail Filtering Language January 2001
1741
1742
1743 argument = string-list / number / tag
1744
1745 arguments = *argument [test / test-list]
1746
1747 block = "{" commands "}"
1748
1749 command = identifier arguments ( ";" / block )
1750
1751 commands = *command
1752
1753 start = commands
1754
1755 string = quoted-string / multi-line
1756
1757 string-list = "[" string *("," string) "]" / string ;; if
1758 there is only a single string, the brackets are optional
1759
1760 test = identifier arguments
1761
1762 test-list = "(" test *("," test) ")"
1763
1764 9. Extended Example
1765
1766 The following is an extended example of a Sieve script. Note that it
1767 does not make use of the implicit keep.
1768
1769 #
1770 # Example Sieve Filter
1771 # Declare any optional features or extension used by the script
1772 #
1773 require ["fileinto", "reject"];
1774
1775 #
1776 # Reject any large messages (note that the four leading dots get
1777 # "stuffed" to three)
1778 #
1779 if size :over 1M
1780 {
1781 reject text:
1782 Please do not send me large attachments.
1783 Put your file on a server and send me the URL.
1784 Thank you.
1785 .... Fred
1786 .
1787 ;
1788 stop;
1789 }
1790 #
1791
1792
1793
1794 Showalter Standards Track [Page 32]
1795
1796 RFC 3028 Sieve: A Mail Filtering Language January 2001
1797
1798
1799 # Handle messages from known mailing lists
1800 # Move messages from IETF filter discussion list to filter folder
1801 #
1802 if header :is "Sender" "owner-ietf-mta-filters@imc.org"
1803 {
1804 fileinto "filter"; # move to "filter" folder
1805 }
1806 #
1807 # Keep all messages to or from people in my company
1808 #
1809 elsif address :domain :is ["From", "To"] "example.com"
1810 {
1811 keep; # keep in "In" folder
1812 }
1813
1814 #
1815 # Try and catch unsolicited email. If a message is not to me,
1816 # or it contains a subject known to be spam, file it away.
1817 #
1818 elsif anyof (not address :all :contains
1819 ["To", "Cc", "Bcc"] "me@example.com",
1820 header :matches "subject"
1821 ["*make*money*fast*", "*university*dipl*mas*"])
1822 {
1823 # If message header does not contain my address,
1824 # it's from a list.
1825 fileinto "spam"; # move to "spam" folder
1826 }
1827 else
1828 {
1829 # Move all other (non-company) mail to "personal"
1830 # folder.
1831 fileinto "personal";
1832 }
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850 Showalter Standards Track [Page 33]
1851
1852 RFC 3028 Sieve: A Mail Filtering Language January 2001
1853
1854
1855 10. Security Considerations
1856
1857 Users must get their mail. It is imperative that whatever method
1858 implementations use to store the user-defined filtering scripts be
1859 secure.
1860
1861 It is equally important that implementations sanity-check the user's
1862 scripts, and not allow users to create on-demand mailbombs. For
1863 instance, an implementation that allows a user to reject or redirect
1864 multiple times to a single message might also allow a user to create
1865 a mailbomb triggered by mail from a specific user. Site- or
1866 implementation-defined limits on actions are useful for this.
1867
1868 Several commands, such as "discard", "redirect", and "fileinto" allow
1869 for actions to be taken that are potentially very dangerous.
1870
1871 Implementations SHOULD take measures to prevent languages from
1872 looping.
1873
1874 11. Acknowledgments
1875
1876 I am very thankful to Chris Newman for his support and his ABNF
1877 syntax checker, to John Myers and Steve Hole for outlining the
1878 requirements for the original drafts, to Larry Greenfield for nagging
1879 me about the grammar and finally fixing it, to Greg Sereda for
1880 repeatedly fixing and providing examples, to Ned Freed for fixing
1881 everything else, to Rob Earhart for an early implementation and a
1882 great deal of help, and to Randall Gellens for endless amounts of
1883 proofreading. I am grateful to Carnegie Mellon University where most
1884 of the work on this document was done. I am also indebted to all of
1885 the readers of the ietf-mta-filters@imc.org mailing list.
1886
1887 12. Author's Address
1888
1889 Tim Showalter
1890 Mirapoint, Inc.
1891 909 Hermosa Court
1892 Sunnyvale, CA 94085
1893
1894 EMail: tjs@mirapoint.com
1895
1896 13. References
1897
1898 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
1899 Specifications: ABNF", RFC 2234, November 1997.
1900
1901
1902
1903
1904
1905
1906 Showalter Standards Track [Page 34]
1907
1908 RFC 3028 Sieve: A Mail Filtering Language January 2001
1909
1910
1911 [ACAP] Newman, C. and J. G. Myers, "ACAP -- Application
1912 Configuration Access Protocol", RFC 2244, November 1997.
1913
1914 [BINARY-SI] "Standard IEC 60027-2: Letter symbols to be used in
1915 electrical technology - Part 2: Telecommunications and
1916 electronics", January 1999.
1917
1918 [DSN] Moore, K. and G. Vaudreuil, "An Extensible Message Format
1919 for Delivery Status Notifications", RFC 1894, January
1920 1996.
1921
1922 [FLAMES] Borenstein, N, and C. Thyberg, "Power, Ease of Use, and
1923 Cooperative Work in a Practical Multimedia Message
1924 System", Int. J. of Man-Machine Studies, April, 1991.
1925 Reprinted in Computer-Supported Cooperative Work and
1926 Groupware, Saul Greenberg, editor, Harcourt Brace
1927 Jovanovich, 1991. Reprinted in Readings in Groupware and
1928 Computer-Supported Cooperative Work, Ronald Baecker,
1929 editor, Morgan Kaufmann, 1993.
1930
1931 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
1932 Requirement Levels", BCP 14, RFC 2119, March 1997.
1933
1934 [IMAP] Crispin, M., "Internet Message Access Protocol - version
1935 4rev1", RFC 2060, December 1996.
1936
1937 [IMAIL] Crocker, D., "Standard for the Format of ARPA Internet
1938 Text Messages", STD 11, RFC 822, August 1982.
1939
1940 [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
1941 Extensions (MIME) Part One: Format of Internet Message
1942 Bodies", RFC 2045, November 1996.
1943
1944 [MDN] Fajman, R., "An Extensible Message Format for Message
1945 Disposition Notifications", RFC 2298, March 1998.
1946
1947 [RFC1123] Braden, R., "Requirements for Internet Hosts --
1948 Application and Support", STD 3, RFC 1123, November 1989.
1949
1950 [SMTP] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC
1951 821, August 1982.
1952
1953 [UTF-8] Yergeau, F., "UTF-8, a transformation format of Unicode
1954 and ISO 10646", RFC 2044, October 1996.
1955
1956
1957
1958
1959
1960
1961
1962 Showalter Standards Track [Page 35]
1963
1964 RFC 3028 Sieve: A Mail Filtering Language January 2001
1965
1966
1967 14. Full Copyright Statement
1968
1969 Copyright (C) The Internet Society (2001). All Rights Reserved.
1970
1971 This document and translations of it may be copied and furnished to
1972 others, and derivative works that comment on or otherwise explain it
1973 or assist in its implementation may be prepared, copied, published
1974 and distributed, in whole or in part, without restriction of any
1975 kind, provided that the above copyright notice and this paragraph are
1976 included on all such copies and derivative works. However, this
1977 document itself may not be modified in any way, such as by removing
1978 the copyright notice or references to the Internet Society or other
1979 Internet organizations, except as needed for the purpose of
1980 developing Internet standards in which case the procedures for
1981 copyrights defined in the Internet Standards process must be
1982 followed, or as required to translate it into languages other than
1983 English.
1984
1985 The limited permissions granted above are perpetual and will not be
1986 revoked by the Internet Society or its successors or assigns.
1987
1988 This document and the information contained herein is provided on an
1989 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1990 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1991 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1992 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1993 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1994
1995 Acknowledgement
1996
1997 Funding for the RFC Editor function is currently provided by the
1998 Internet Society.
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018 Showalter Standards Track [Page 36]
2019