7Network Working Group W. Segmuller
8Request for Comments: 5231 B. Leiba
9Obsoletes: 3431 IBM T.J. Watson Research Center
10Category: Standards Track January 2008
13 Sieve Email Filtering: Relational Extension
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 the RELATIONAL extension to the Sieve mail
26 filtering language defined in RFC 3028. This extension extends
27 existing conditional tests in Sieve to allow relational operators.
28 In addition to testing their content, it also allows for testing of
29 the number of entities in header and envelope fields.
31 This document obsoletes RFC 3431.
35 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
36 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
37 3. Comparators . . . . . . . . . . . . . . . . . . . . . . . . . . 2
38 4. Match Types . . . . . . . . . . . . . . . . . . . . . . . . . . 3
39 4.1. Match Type VALUE . . . . . . . . . . . . . . . . . . . . . 3
40 4.2. Match Type COUNT . . . . . . . . . . . . . . . . . . . . . 3
41 5. Interaction with Other Sieve Actions . . . . . . . . . . . . . 4
42 6. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
43 7. Extended Example . . . . . . . . . . . . . . . . . . . . . . . 6
44 8. Changes since RFC 3431 . . . . . . . . . . . . . . . . . . . . 6
45 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
46 10. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
47 11. Normative References . . . . . . . . . . . . . . . . . . . . . 7
58Segmuller & Leiba Standards Track [Page 1]
60RFC 5231 Sieve: Relational Extension January 2008
65 The RELATIONAL extension to the Sieve mail filtering language [Sieve]
66 provides relational operators on the address, envelope, and header
67 tests. This extension also provides a way of counting the entities
68 in a message header or address field.
70 With this extension, the Sieve script may now determine if a field is
71 greater than or less than a value instead of just equivalent. One
72 use is for the x-priority field: move messages with a priority
73 greater than 3 to the "work on later" folder. Mail could also be
74 sorted by the from address. Those userids that start with 'a'-'m' go
75 to one folder, and the rest go to another folder.
77 The Sieve script can also determine the number of fields in the
78 header, or the number of addresses in a recipient field, for example,
79 whether there are more than 5 addresses in the to and cc fields.
81 The capability string associated with the extension defined in this
82 document is "relational".
842. Conventions Used in This Document
86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
88 document are to be interpreted as described in BCP 14, RFC 2119.
90 Conventions for notations are as in [Sieve] section 1.1, including
91 the use of [Kwds] and the use of [ABNF].
95 This document does not define any comparators or exempt any
96 comparators from the require clause. Any comparator used must be
97 treated as defined in [Sieve].
99 The "i;ascii-numeric" comparator, as defined in [RFC4790], MUST be
100 supported for any implementation of this extension. The comparator
101 "i;ascii-numeric" MUST support at least 32-bit unsigned integers.
103 Larger integers MAY be supported. Note: the "i;ascii-numeric"
104 comparator does not support negative numbers.
114Segmuller & Leiba Standards Track [Page 2]
116RFC 5231 Sieve: Relational Extension January 2008
121 This document defines two new match types. They are the VALUE match
122 type and the COUNT match type.
126 MATCH-TYPE =/ COUNT / VALUE
128 COUNT = ":count" relational-match
130 VALUE = ":value" relational-match
132 relational-match = DQUOTE
133 ("gt" / "ge" / "lt" / "le" / "eq" / "ne") DQUOTE
134 ; "gt" means "greater than", the C operator ">".
135 ; "ge" means "greater than or equal", the C operator ">=".
136 ; "lt" means "less than", the C operator "<".
137 ; "le" means "less than or equal", the C operator "<=".
138 ; "eq" means "equal to", the C operator "==".
139 ; "ne" means "not equal to", the C operator "!=".
143 The VALUE match type does a relational comparison between strings.
145 The VALUE match type may be used with any comparator that returns
148 A value from the message is considered the left side of the relation.
149 A value from the test expression, the key-list for address, envelope,
150 and header tests, is the right side of the relation.
152 If there are multiple values on either side or both sides, the test
153 is considered true if any pair is true.
157 The COUNT match type first determines the number of the specified
158 entities in the message and does a relational comparison of the
159 number of entities, as defined below, to the values specified in the
162 The COUNT match type SHOULD only be used with numeric comparators.
164 The Address Test counts the number of addresses (the number of
165 "mailbox" elements, as defined in [RFC2822]) in the specified fields.
166 Group names are ignored, but the contained mailboxes are counted.
170Segmuller & Leiba Standards Track [Page 3]
172RFC 5231 Sieve: Relational Extension January 2008
175 The Envelope Test counts the number of addresses in the specified
176 envelope parts. The envelope "to" will always have only one entry,
177 which is the address of the user for whom the Sieve script is
178 running. Using this test, there is no way a Sieve script can
179 determine if the message was actually sent to someone else. The
180 envelope "from" will be 0 if the MAIL FROM is empty, or 1 if MAIL
183 The Header Test counts the total number of instances of the specified
184 fields. This does not count individual addresses in the "to", "cc",
185 and other recipient fields.
187 In all cases, if more than one field name is specified, the counts
188 for all specified fields are added together to obtain the number for
189 comparison. Thus, specifying ["to", "cc"] in an address COUNT test
190 compares the total number of "to" and "cc" addresses; if separate
191 counts are desired, they must be done in two comparisons, perhaps
192 joined by "allof" or "anyof".
1945. Interaction with Other Sieve Actions
196 This specification adds two match types. The VALUE match type only
197 works with comparators that return sort information. The COUNT match
198 type only makes sense with numeric comparators.
200 There is no interaction with any other Sieve operations, nor with any
201 known extensions. In particular, this specification has no effect on
202 implicit KEEP, nor on any explicit message actions.
211 to: foo@example.com, baz@example.com
216 address :count "ge" :comparator "i;ascii-numeric"
219 would evaluate to true, and the test
226Segmuller & Leiba Standards Track [Page 4]
228RFC 5231 Sieve: Relational Extension January 2008
231 anyof ( address :count "ge" :comparator "i;ascii-numeric"
233 address :count "ge" :comparator "i;ascii-numeric"
236 would evaluate to false.
238 To check the number of received fields in the header, the following
241 header :count "ge" :comparator "i;ascii-numeric"
244 This would evaluate to false. But
246 header :count "ge" :comparator "i;ascii-numeric"
247 ["received", "subject"] ["3"]
249 would evaluate to true.
253 header :count "ge" :comparator "i;ascii-numeric"
256 will always evaluate to false on an RFC 2822 compliant message
257 [RFC2822], since a message can have at most one "to" field and at
258 most one "cc" field. This test counts the number of fields, not the
282Segmuller & Leiba Standards Track [Page 5]
284RFC 5231 Sieve: Relational Extension January 2008
289 require ["relational", "comparator-i;ascii-numeric", "fileinto"];
291 if header :value "lt" :comparator "i;ascii-numeric"
297 elsif address :count "gt" :comparator "i;ascii-numeric"
300 # everything with more than 5 recipients in the "to" field
305 elsif address :value "gt" :all :comparator "i;ascii-casemap"
313 if allof ( address :count "eq" :comparator "i;ascii-numeric"
315 address :all :comparator "i;ascii-casemap"
316 ["to", "cc"] ["me@foo.example.com"] )
3218. Changes since RFC 3431
323 Apart from several minor editorial/wording changes, the following
324 list describes the notable changes to this specification since RFC
327 o Updated references, including changing the comparator reference
328 from the Application Configuration Access Protocol (ACAP) to the
329 "Internet Application Protocol Collation Registry" document
332 o Updated and corrected the examples.
338Segmuller & Leiba Standards Track [Page 6]
340RFC 5231 Sieve: Relational Extension January 2008
343 o Added definition comments to ABNF for "gt", "lt", etc.
345 o Clarified what RFC 2822 elements are counted in the COUNT test.
347 o Removed the requirement to strip white space from header fields
348 before comparing; a more general version of this requirement has
349 been added to the Sieve base spec.
3519. IANA Considerations
353 The following template specifies the IANA registration of the
354 relational Sieve extension specified in this document:
357 Subject: Registration of new Sieve extension
359 Capability name: relational
360 Description: Extends existing conditional tests in Sieve language
361 to allow relational operators
363 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
36510. Security Considerations
367 An implementation MUST ensure that the test for envelope "to" only
368 reflects the delivery to the current user. Using this test, it MUST
369 not be possible for a user to determine if this message was delivered
372 Additional security considerations are discussed in [Sieve].
37411. Normative References
376 [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
377 Specifications: ABNF", RFC 4234, October 2005.
379 [Kwds] Bradner, S., "Key words for use in RFCs to Indicate
380 Requirement Levels", RFC 2119, March 1997.
382 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822,
385 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
386 Application Protocol Collation Registry", RFC 4790,
389 [Sieve] Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email
390 Filtering Language", RFC 5228, January 2008.
394Segmuller & Leiba Standards Track [Page 7]
396RFC 5231 Sieve: Relational Extension January 2008
402 IBM T.J. Watson Research Center
407 Phone: +1 914 784 7408
408 EMail: werewolf@us.ibm.com
412 IBM T.J. Watson Research Center
417 Phone: +1 914 784 7941
418 EMail: leiba@watson.ibm.com
450Segmuller & Leiba Standards Track [Page 8]
452RFC 5231 Sieve: Relational Extension January 2008
455Full Copyright Statement
457 Copyright (C) The IETF Trust (2008).
459 This document is subject to the rights, licenses and restrictions
460 contained in BCP 78, and except as set forth therein, the authors
461 retain all their rights.
463 This document and the information contained herein are provided on an
464 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
465 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
466 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
467 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
468 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
469 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
473 The IETF takes no position regarding the validity or scope of any
474 Intellectual Property Rights or other rights that might be claimed to
475 pertain to the implementation or use of the technology described in
476 this document or the extent to which any license under such rights
477 might or might not be available; nor does it represent that it has
478 made any independent effort to identify any such rights. Information
479 on the procedures with respect to rights in RFC documents can be
480 found in BCP 78 and BCP 79.
482 Copies of IPR disclosures made to the IETF Secretariat and any
483 assurances of licenses to be made available, or the result of an
484 attempt made to obtain a general license or permission for the use of
485 such proprietary rights by implementers or users of this
486 specification can be obtained from the IETF on-line IPR repository at
487 http://www.ietf.org/ipr.
489 The IETF invites any interested party to bring to its attention any
490 copyrights, patents or patent applications, or other proprietary
491 rights that may cover technology that may be required to implement
492 this standard. Please address the information to the IETF at
506Segmuller & Leiba Standards Track [Page 9]