7Network Working Group W. Segmuller
8Request for Comment: 3431 IBM T.J. Watson Research Center
9Category: Standards Track December 2002
12 Sieve Extension: Relational Tests
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.
24 Copyright (C) The Internet Society (2002). All Rights Reserved.
28 This document describes the RELATIONAL extension to the Sieve mail
29 filtering language defined in RFC 3028. This extension extends
30 existing conditional tests in Sieve to allow relational operators.
31 In addition to testing their content, it also allows for testing of
32 the number of entities in header and envelope fields.
36 Sieve [SIEVE] is a language for filtering e-mail messages at the time
37 of final delivery. It is designed to be implementable on either a
38 mail client or mail server. It is meant to be extensible, simple,
39 and independent of access protocol, mail architecture, and operating
40 system. It is suitable for running on a mail server where users may
41 not be allowed to execute arbitrary programs, such as on black box
42 Internet Messages Access Protocol (IMAP) servers, as it has no
43 variables, loops, nor the ability to shell out to external programs.
45 The RELATIONAL extension provides relational operators on the
46 address, envelope, and header tests. This extension also provides a
47 way of counting the entities in a message header or address field.
49 With this extension, the sieve script may now determine if a field is
50 greater than or less than a value instead of just equivalent. One
51 use is for the x-priority field: move messages with a priority
52 greater than 3 to the "work on later" folder. Mail could also be
53 sorted by the from address. Those userids that start with 'a'-'m' go
54 to one folder, and the rest go to another folder.
58Segmuller Standards Track [Page 1]
60RFC 3431 Sieve Extension: Relational Tests December 2002
63 The sieve script can also determine the number of fields in the
64 header, or the number of addresses in a recipient field. For
65 example: are there more than 5 addresses in the to and cc fields.
672 Conventions used in this document
69 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
70 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
71 document are to be interpreted as described in BCP 14, RFC 2119.
73 Conventions for notations are as in [SIEVE] section 1.1, including
74 the use of [KEYWORDS] and "Syntax:" label for the definition of
75 action and tagged arguments syntax, and the use of [ABNF].
77 The capability string associated with extension defined in this
78 document is "relational".
82 This document does not define any comparators or exempt any
83 comparators from the require clause. Any comparator used, other than
84 "i;octet" and "i;ascii-casemap", MUST be declared a require clause as
87 The "i;ascii-numeric" comparator, as defined in [ACAP], MUST be
88 supported for any implementation of this extension. The comparator
89 "i;ascii-numeric" MUST support at least 32 bit unsigned integers.
91 Larger integers MAY be supported. Note: the "i;ascii-numeric"
92 comparator does not support negative numbers.
96 This document defines two new match types. They are the VALUE match
97 type and the COUNT match type.
101 MATCH-TYPE =/ COUNT / VALUE
103 COUNT = ":count" relational-match
105 VALUE = ":value" relational-match
107 relational-match = DQUOTE ( "gt" / "ge" / "lt"
108 / "le" / "eq" / "ne" ) DQUOTE
114Segmuller Standards Track [Page 2]
116RFC 3431 Sieve Extension: Relational Tests December 2002
121 The VALUE match type does a relational comparison between strings.
123 The VALUE match type may be used with any comparator which returns
126 Leading and trailing white space MUST be removed from the value of
127 the message for the comparison. White space is defined as
131 A value from the message is considered the left side of the relation.
132 A value from the test expression, the key-list for address, envelope,
133 and header tests, is the right side of the relation.
135 If there are multiple values on either side or both sides, the test
136 is considered true, if any pair is true.
140 The COUNT match type first determines the number of the specified
141 entities in the message and does a relational comparison of the
142 number of entities to the values specified in the test expression.
144 The COUNT match type SHOULD only be used with numeric comparators.
146 The Address Test counts the number of recipients in the specified
147 fields. Group names are ignored.
149 The Envelope Test counts the number of recipients in the specified
150 envelope parts. The envelope "to" will always have only one entry,
151 which is the address of the user for whom the sieve script is
152 running. There is no way a sieve script can determine if the message
153 was actually sent to someone else using this test. The envelope
154 "from" will be 0 if the MAIL FROM is blank, or 1 if MAIL FROM is not
157 The Header Test counts the total number of instances of the specified
158 fields. This does not count individual addresses in the "to", "cc",
159 and other recipient fields.
161 In all cases, if more than one field name is specified, the counts
162 for all specified fields are added together to obtain the number for
163 comparison. Thus, specifying ["to", "cc"] in an address COUNT test,
164 comparing the total number of "to" and "cc" addresses; if separate
165 counts are desired, they must be done in two comparisons, perhaps
166 joined by "allof" or "anyof".
170Segmuller Standards Track [Page 3]
172RFC 3431 Sieve Extension: Relational Tests December 2002
1755 Security Considerations
177 Security considerations are discussed in [SIEVE].
179 An implementation MUST ensure that the test for envelope "to" only
180 reflects the delivery to the current user. It MUST not be possible
181 for a user to determine if this message was delivered to someone else
191 to: foo@example.com.invalid, baz@example.com.invalid
192 cc: qux@example.com.invalid
196 address :count "ge" :comparator "i;ascii-numeric" ["to", "cc"]
199 would be true and the test
201 anyof ( address :count "ge" :comparator "i;ascii-numeric"
203 address :count "ge" :comparator "i;ascii-numeric"
208 To check the number of received fields in the header, the
209 following test may be used:
211 header :count "ge" :comparator "i;ascii-numeric"
214 This would return false. But
216 header :count "ge" :comparator "i;ascii-numeric"
217 ["received", "subject"] ["3"]
226Segmuller Standards Track [Page 4]
228RFC 3431 Sieve Extension: Relational Tests December 2002
233 header :count "ge" :comparator "i;ascii-numeric"
236 will always return false on an RFC 2822 compliant message [RFC2822],
237 since a message can have at most one "to" field and at most one "cc"
238 field. This test counts the number of fields, not the number of
243 require ["relational", "comparator-i;ascii-numeric"];
245 if header :value "lt" :comparator "i;ascii-numeric"
251 elseif address :count "gt" :comparator "i;ascii-numeric"
254 # everything with more than 5 recipients in the "to" field
259 elseif address :value "gt" :all :comparator "i;ascii-casemap"
267 if allof ( address :count "eq" :comparator "i;ascii-numeric"
269 address :all :comparator "i;ascii-casemap"
270 ["to", "cc"] ["me@foo.example.com.invalid"]
282Segmuller Standards Track [Page 5]
284RFC 3431 Sieve Extension: Relational Tests December 2002
289 The following template specifies the IANA registration of the Sieve
290 extension specified in this document:
293 Subject: Registration of new Sieve extension
295 Capability name: RELATIONAL
296 Capability keyword: relational
297 Capability arguments: N/A
298 Standards Track/IESG-approved experimental RFC number: this RFC
299 Person and email address to contact for further information:
301 IBM T.J. Watson Research Center
305 Email: whs@watson.ibm.com
307 This information should be added to the list of sieve extensions
308 given on http://www.iana.org/assignments/sieve-extensions.
3129.1 Normative References
314 [SIEVE] Showalter, T., "Sieve: A Mail Filtering Language", RFC
317 [Keywords] Bradner, S., "Key words for use in RFCs to Indicate
318 Requirement Levels", BCP 14, RFC 2119, March 1997.
320 [ABNF] Crocker, D., "Augmented BNF for Syntax Specifications:
321 ABNF", RFC 2234, November 1997.
323 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April
3269.2 Non-Normative References
328 [ACAP] Newman, C. and J. G. Myers, "ACAP -- Application
329 Configuration Access Protocol", RFC 2244, November 1997.
338Segmuller Standards Track [Page 6]
340RFC 3431 Sieve Extension: Relational Tests December 2002
346 IBM T.J. Watson Research Center
350 EMail: whs@watson.ibm.com
394Segmuller Standards Track [Page 7]
396RFC 3431 Sieve Extension: Relational Tests December 2002
39911 Full Copyright Statement
401 Copyright (C) The Internet Society (2002). All Rights Reserved.
403 This document and translations of it may be copied and furnished to
404 others, and derivative works that comment on or otherwise explain it
405 or assist in its implementation may be prepared, copied, published
406 and distributed, in whole or in part, without restriction of any
407 kind, provided that the above copyright notice and this paragraph are
408 included on all such copies and derivative works. However, this
409 document itself may not be modified in any way, such as by removing
410 the copyright notice or references to the Internet Society or other
411 Internet organizations, except as needed for the purpose of
412 developing Internet standards in which case the procedures for
413 copyrights defined in the Internet Standards process must be
414 followed, or as required to translate it into languages other than
417 The limited permissions granted above are perpetual and will not be
418 revoked by the Internet Society or its successors or assigns.
420 This document and the information contained herein is provided on an
421 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
422 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
423 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
424 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
425 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
429 Funding for the RFC Editor function is currently provided by the
450Segmuller Standards Track [Page 8]