Sieve Working Group                                         W. Segmuller
Internet Draft
Internet-Draft                                                  B. Leiba
Obsoletes: 3431 (if approved)            IBM T.J. Watson Research Center
Document: draft-ietf-sieve-3431bis-01.txt                     March 2005
                                                  Expires September
Expires: May 21, 2006                                  November 17, 2005

                   Sieve Extension: Relational Tests

Status of this Document

   This document is an Internet-Draft and is subject to all provisions
   of Section 3 of RFC 3667. Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she become becomes
   aware will be disclosed, in accordance with
   RFC 3668. Section 6 of BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as
   Internet-Drafts. Internet-

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at

   The list of Internet-Draft Shadow Directories can be accessed at

   This Internet-Draft will expire on September 16, 2005. May 21, 2006.

Copyright Notice

   Copyright (C) The Internet Society (2005).


   This document describes the RELATIONAL extension to the Sieve mail
   filtering language defined in RFC 3028.  This extension extends
   existing conditional tests in Sieve to allow relational operators.

Internet DRAFT     Sieve Extension: Relational Tests         March 2005
   In addition to testing their content, it also allows for testing of
   the number of entities in header and envelope fields.

Meta-information on this document

   This information is intended to facilitate discussion.  It will be
   removed when this document leaves the Internet-Draft stage.

   This document is intended to be an update to the existing
   "relational" extension to the Sieve mail filtering language,
   available from the RFC repository as

   This document and the Sieve language itself are being discussed on
   the MTA Filters mailing list at <>.
   Subscription requests can be sent to
   <> (send an email
   message with the word "subscribe" in the body).  More information on
   the mailing list along with a WWW archive of back messages is
   available at <>.

Table of Contents

   1.   Conventions used in this document  . . . . . . . . . . . . .   3

   2.   Introduction . . . . . . . . . . . . . . . . . . . . . . . .   4

   3.   Comparators  . . . . . . . . . . . . . . . . . . . . . . . .   5

   4.   Match Types  . . . . . . . . . . . . . . . . . . . . . . . .   6
   4.1  Match Type VALUE . . . . . . . . . . . . . . . . . . . . . .   6
   4.2  Match Type COUNT . . . . . . . . . . . . . . . . . . . . . .   6

   5.   Interaction With Other Sieve Actions . . . . . . . . . . . .   8

   6.   Example  . . . . . . . . . . . . . . . . . . . . . . . . . .   9

   7.   Extended Example . . . . . . . . . . . . . . . . . . . . . .  10

   8.   IANA Considerations  . . . . . . . . . . . . . . . . . . . .  11

   9.   Security Considerations  . . . . . . . . . . . . . . . . . .  12

   10.  References . . . . . . . . . . . . . . . . . . . . . . . . .  13
   10.1 Normative References . . . . . . . . . . . . . . . . . . . .  13
   10.2 Non-Normative References . . . . . . . . . . . . . . . . . .  13

        Authors' Addresses . . . . . . . . . . . . . . . . . . . . .  13

        Intellectual Property and Copyright Statements . . . . . . .  14

1.  Conventions used in this document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   document are to be interpreted as described in BCP 14, RFC 2119.

   Conventions for notations are as in [SIEVE] [Sieve] section 1.1, including
   the use of [KEYWORDS] and "Syntax:" label for the definition of
   action and tagged arguments syntax, [Kwds] and the use of [ABNF].

   The capability string associated with extension defined in this
   document is "relational".


2.  Introduction

   Sieve [SIEVE]

   [Sieve] is a language for filtering e-mail messages at the time of
   final delivery.  It is designed to be implementable on either a mail
   client or mail server.  It is meant to be extensible, simple, and
   independent of access protocol, mail architecture, and operating
   system.  It is suitable for running on a mail server where users may
   not be allowed to execute arbitrary programs, such as on black box
   Internet Messages Access Protocol (IMAP) servers, as it has no
   variables, loops, nor the ability to shell out to external programs.

   The RELATIONAL extension provides relational operators on the

Internet DRAFT     Sieve Extension: Relational Tests         March 2005
   address, envelope, and header tests.  This extension also provides a
   way of counting the entities in a message header or address field.

   With this extension, the sieve Sieve script may now determine if a field is
   greater than or less than a value instead of just equivalent.  One
   use is for the x-priority field: move messages with a priority
   greater than 3 to the "work on later" folder.  Mail could also be
   sorted by the from address.  Those userids that start with 'a'-'m' go
   to one folder, and the rest go to another folder.

   The sieve Sieve script can also determine the number of fields in the
   header, or the number of addresses in a recipient field.  For
   example: are there more than 5 addresses in the to and cc fields.


   The capability string associated with the extension defined in this
   document is "relational".

3.  Comparators

   This document does not define any comparators or exempt any
   comparators from the require clause.  Any comparator used, other than
   "i;octet" and "i;ascii-casemap", MUST used must be declared a require clause
   treated as defined in [SIEVE]. [Sieve].

   The "i;ascii-numeric" comparator, as defined in [ACAP], [Comp], MUST be
   supported for any implementation of this extension.  The comparator
   "i;ascii-numeric" MUST support at least 32 bit unsigned integers.

   Larger integers MAY be supported.  Note: the "i;ascii-numeric"
   comparator does not support negative numbers.


4.  Match Type Types

   This document defines two new match types.  They are the VALUE match
   type and the COUNT match type.

   The syntax is:


   COUNT = ":count" relational-match

   VALUE = ":value" relational-match

   relational-match = DQUOTE ( "gt"
           ("gt" / "ge" / "lt" / "le" / "eq" / "ne" ) "ne") DQUOTE
           ; "gt" means "greater than", the C operator ">".
           ; "ge" means "greater than or equal", the C operator ">=".
           ; "lt" means "less than", the C operator "<".
           ; "le" means "less than or equal", the C operator "<=".

Internet DRAFT     Sieve Extension: Relational Tests         March 2005
           ; "eq" means "equal to", the C operator "==".
           ; "ne" means "not equal to", the C operator "!=".


4.1  Match Type Value VALUE

   The VALUE match type does a relational comparison between strings.

   The VALUE match type may be used with any comparator which returns
   sort information.

   Leading and trailing white space MUST be removed from the value of
   the message for the comparison.  White space is defined as

       SP / HTAB / CRLF

   A value from the message is considered the left side of the relation.
   A value from the test expression, the key-list for address, envelope,
   and header tests, is the right side of the relation.

   If there are multiple values on either side or both sides, the test
   is considered true, true if any pair is true.


4.2  Match Type Count COUNT

   The COUNT match type first determines the number of the specified
   entities in the message and does a relational comparison of the
   number of entities entities, as defined below to the values specified in the
   test expression.

   The COUNT match type SHOULD only be used with numeric comparators.

   The Address Test counts the number of recipients addresses (the number of
   "mailbox" elements, as defined in [RFC2822]) in the specified fields.

   Group names are ignored. ignored, but the contained mailboxes are counted.

   The Envelope Test counts the number of recipients addresses in the specified
   envelope parts.  The envelope "to" will always have only one entry,
   which is the address of the user for whom the sieve Sieve script is
   running.  There is no way a sieve Sieve script can determine if the message
   was actually sent to someone else using this test.  The envelope
   "from" will be 0 if the MAIL FROM is blank, empty, or 1 if MAIL FROM is not

   The Header Test counts the total number of instances of the specified
   fields.  This does not count individual addresses in the "to", "cc",
   and other recipient fields.

   In all cases, if more than one field name is specified, the counts
   for all specified fields are added together to obtain the number for

Internet DRAFT     Sieve Extension: Relational Tests         March 2005
   comparison.  Thus, specifying ["to", "cc"] in an address COUNT test,
   compares the total number of "to" and "cc" addresses; if separate
   counts are desired, they must be done in two comparisons, perhaps
   joined by "allof" or "anyof".


5.  Interaction With Other Sieve Actions

   This specification adds two match types.  The VALUE match type only
   works with comparators that return sort information.  The COUNT match
   type only makes sense with numeric comparators.

   There is no interaction with any other Sieve operations, nor with any
   known extensions.  In particular, this specification has no effect on
   implicit KEEP, nor on any explicit message actions.

6.  Example

   Using the message:

      received: ...
      received: ...
      subject: example

   The test:

      address :count "ge" :comparator "i;ascii-numeric"
                      ["to", "cc"] ["3"]

   would be evaluate to true and the test

      anyof ( address :count "ge" :comparator "i;ascii-numeric"
                      ["to"] ["3"],
              address :count "ge" :comparator "i;ascii-numeric"
                      ["cc"] ["3"] )

   would be evaluate to false.

   To check the number of received fields in the header, the following
   test may be used:

      header :count "ge" :comparator "i;ascii-numeric"
                      ["received"] ["3"]

   This would return evaluate to false.  But

      header :count "ge" :comparator "i;ascii-numeric"
                      ["received", "subject"] ["3"]

   would return evaluate to true.

   The test:

      header :count "ge" :comparator "i;ascii-numeric"
                      ["to", "cc"] ["3"]

   will always return evaluate to false on an RFC 2822 compliant message

Internet DRAFT     Sieve Extension: Relational Tests         March 2005 since a message can have at most one "to" field and at
   most one "cc" field.  This test counts the number of fields, not the
   number of addresses.


7.  Extended Example

      require ["relational", "comparator-i;ascii-numeric"]; "comparator-i;ascii-numeric", "fileinto"];

      if header :value "lt" :comparator "i;ascii-numeric"
                ["x-priority"] ["3"]
         fileinto "Priority";


      elsif address :count "gt" :comparator "i;ascii-numeric"
                 ["to"] ["5"]
         # everything with more than 5 recipients in the "to" field
         # is considered SPAM
         fileinto "SPAM";


      elsif address :value "gt" :all :comparator "i;ascii-casemap"
                 ["from"] ["M"]
         fileinto "From N-Z";
      } else {
         fileinto "From A-M";

      if allof ( address :count "eq" :comparator "i;ascii-numeric"
                         ["to", "cc"] ["1"] ,
                 address :all :comparator "i;ascii-casemap"
                         ["to", "cc"] [""] [""] )
         fileinto "Only me";


8.  IANA Considerations

   This document requests that the IANA update the entry for the
   "relational" Sieve extension to point to this document.


9.  Security Considerations

   Security considerations are discussed in [SIEVE].

Internet DRAFT     Sieve Extension: Relational Tests         March 2005

   An implementation MUST ensure that the test for envelope "to" only
   reflects the delivery to the current user.  It MUST not be possible
   for a user to determine if this message was delivered to someone else
   using this test.


   Additional security considerations are discussed in [Sieve].

10.  References

10.1  Normative References

   [SIEVE]; Showalter, T.; "Sieve: A Mail Filtering Language";

   [ABNF]     Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", RFC 3028;
   January 2001.

   [Keywords]; 4234, November 1997.

   [Kwds]     Bradner, S.; S., "Key words for use in RFCs to
   IndicateRequirement Levels"; BCP 14; Indicate
              Requirement Levels", RFC 2119; 2119, March 1997.

   [ABNF]; Crocker, D.; "Augmented BNF for Syntax Specifications: ABNF";
   RFC 2234; November 1997.


   [RFC2822]  Resnick, P.; P., "Internet Message Format"; Format", RFC 2822; 2822,
              April 2001.


   [Sieve]    Guenther, P. and T. Showalter, "Sieve: An Email Filtering
              Language", I-D draft-ietf-sieve-3028bis, July 2005.

10.2  Non-Normative References


   [Comp]  Newman, C. C., Duerst, M., and J. G. Myers; "ACAP -- A. Gulbrandsen, "Internet
   Configuration Access Protocol"; RFC 2244; November 1997.

10. Protocol Collation Registry",
           I-D draft-newman-i18n-comparator, September 2005.

Authors' Addresses

   Wolfgang Segmuller
   IBM T.J. Watson Research Center
   19 Skyline Drive
   Hawthorne, NY  10532

   Phone: 1-914-784-7408 +1 914 784 7408

   Barry Leiba
   IBM T.J. Watson Research Center
   19 Skyline Drive
   Hawthorne, NY  10532

   Phone: 1-914-784-7941 +1 914 784 7941

Internet DRAFT     Sieve Extension: Relational Tests         March 2005

Intellectual Property Statement

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at

Disclaimer of Validity

   This document and the information contained herein are provided on an

Copyright Statement

   Copyright (C) The Internet Society (2005).  This document is subject
   to the rights, licenses and restrictions contained in BCP 78, and
   except as set forth therein, the authors retain all their rights.


   Funding for the RFC Editor function is currently provided by the
   Internet Society.