Network Working Group                                       T. ShowalterRequest for Comments: 3028                               Mirapoint, Inc.Category: Standards Track                                   January 2001                    Sieve: A Mail Filtering LanguageStatus of this Memo   This document specifies an Internet standards track protocol for the   Internet community, and requests discussion and suggestions for   improvements.  Please refer to the current edition of the "Internet   Official Protocol Standards" (STD 1) for the standardization state   and status of this protocol.  Distribution of this memo is unlimited.Copyright Notice   Copyright (C) The Internet Society (2001).  All Rights Reserved.Abstract   This document describes a language for filtering e-mail messages at   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 Message Access Protocol (IMAP) servers, as it has no   variables, loops, or ability to shell out to external programs.Table of Contents   1.      Introduction ...........................................   3   1.1.     Conventions Used in This Document .....................   4   1.2.     Example mail messages .................................   4   2.      Design .................................................   5   2.1.     Form of the Language ..................................   5   2.2.     Whitespace ............................................   5   2.3.     Comments ..............................................   6   2.4.     Literal Data ..........................................   6   2.4.1.   Numbers ...............................................   6   2.4.2.   Strings ...............................................   7   2.4.2.1. String Lists ..........................................   7   2.4.2.2. Headers ...............................................   8   2.4.2.3. Addresses .............................................   8   2.4.2.4. MIME Parts ............................................   9   2.5.     Tests .................................................   9   2.5.1.   Test Lists ............................................   9Showalter                   Standards Track                     [Page 1]RFC 3028            Sieve: A Mail Filtering Language        January 2001   2.6.     Arguments .............................................   9   2.6.1.   Positional Arguments ..................................   9   2.6.2.   Tagged Arguments ......................................  10   2.6.3.   Optional Arguments ....................................  10   2.6.4.   Types of Arguments ....................................  10   2.7.     String Comparison .....................................  11   2.7.1.   Match Type ............................................  11   2.7.2.   Comparisons Across Character Sets .....................  12   2.7.3.   Comparators ...........................................  12   2.7.4.   Comparisons Against Addresses .........................  13   2.8.     Blocks ................................................  14   2.9.     Commands ..............................................  14   2.10.    Evaluation ............................................  15   2.10.1.  Action Interaction ....................................  15   2.10.2.  Implicit Keep .........................................  15   2.10.3.  Message Uniqueness in a Mailbox .......................  15   2.10.4.  Limits on Numbers of Actions ..........................  16   2.10.5.  Extensions and Optional Features ......................  16   2.10.6.  Errors ................................................  17   2.10.7.  Limits on Execution ...................................  17   3.      Control Commands .......................................  17   3.1.     Control Structure If ..................................  18   3.2.     Control Structure Require .............................  19   3.3.     Control Structure Stop ................................  19   4.      Action Commands ........................................  19   4.1.     Action reject .........................................  20   4.2.     Action fileinto .......................................  20   4.3.     Action redirect .......................................  21   4.4.     Action keep ...........................................  21   4.5.     Action discard ........................................  22   5.      Test Commands ..........................................  22   5.1.     Test address ..........................................  23   5.2.     Test allof ............................................  23   5.3.     Test anyof ............................................  24   5.4.     Test envelope .........................................  24   5.5.     Test exists ...........................................  25   5.6.     Test false ............................................  25   5.7.     Test header ...........................................  25   5.8.     Test not ..............................................  26   5.9.     Test size .............................................  26   5.10.    Test true .............................................  26   6.      Extensibility ..........................................  26   6.1.     Capability String .....................................  27   6.2.     IANA Considerations ...................................  28   6.2.1.   Template for Capability Registrations .................  28   6.2.2.   Initial Capability Registrations ......................  28   6.3.     Capability Transport ..................................  29   7.      Transmission ...........................................  29Showalter                   Standards Track                     [Page 2]RFC 3028            Sieve: A Mail Filtering Language        January 2001   8.      Parsing ................................................  30   8.1.     Lexical Tokens ........................................  30   8.2.     Grammar ...............................................  31   9.      Extended Example .......................................  32   10.     Security Considerations ................................  34   11.     Acknowledgments ........................................  34   12.     Author's Address .......................................  34   13.     References .............................................  34   14.     Full Copyright Statement ...............................  361.      Introduction   This memo documents a language that can be used to create filters for   electronic mail.  It is not tied to any particular operating system or   mail architecture.  It requires the use of [IMAIL]-compliant   messages, but should otherwise generalize to many systems.   The language is powerful enough to be useful but limited in order to   allow for a safe server-side filtering system.  The intention is to   make it impossible for users to do anything more complex (and   dangerous) than write simple mail filters, along with facilitating   the use of GUIs for filter creation and manipulation.  The language is   not Turing-complete: it provides no way to write a loop or a function   and variables are not provided.   Scripts written in Sieve are executed during final delivery, when the   message is moved to the user-accessible mailbox.  In systems where   the MTA does final delivery, such as traditional Unix mail, it is   reasonable to sort when the MTA deposits mail into the user's   mailbox.   There are a number of reasons to use a filtering system.  Mail   traffic for most users has been increasing due to increased usage of   e-mail, the emergence of unsolicited email as a form of advertising,   and increased usage of mailing lists.   Experience at Carnegie Mellon has shown that if a filtering system is   made available to users, many will make use of it in order to file   messages from specific users or mailing lists.  However, many others   did not make use of the Andrew system's FLAMES filtering language   [FLAMES] due to difficulty in setting it up.   Because of the expectation that users will make use of filtering if   it is offered and easy to use, this language has been made simple   enough to allow many users to make use of it, but rich enough that it   can be used productively.  However, it is expected that GUI-based   editors will be the preferred way of editing filters for a large   number of users.Showalter                   Standards Track                     [Page 3]RFC 3028            Sieve: A Mail Filtering Language        January 20011.1.     Conventions Used in This Document   In the sections of this document that discuss the requirements of   various keywords and operators, the following conventions have been   adopted.   The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and   "MAY" in this document are to be interpreted as defined in   [KEYWORDS].   Each section on a command (test, action, or control structure) has a   line labeled "Syntax:".  This line describes the syntax of the   command, including its name and its arguments.  Required arguments   are listed inside angle brackets ("<" and ">").  Optional arguments   are listed inside square brackets ("[" and "]").  Each argument is   followed by its type, so "<key: string>" represents an argument   called "key" that is a string.  Literal strings are represented with   double-quoted strings.  Alternatives are separated with slashes, and   parenthesis are used for grouping, similar to [ABNF].   In the "Syntax" line, there are three special pieces of syntax that   are frequently repeated, MATCH-TYPE, COMPARATOR, and ADDRESS-PART.   These are discussed in sections 2.7.1, 2.7.3, and 2.7.4,   respectively.   The formal grammar for these commands in section 10 and is the   authoritative reference on how to construct commands, but the formal   grammar does not specify the order, semantics, number or types of   arguments to commands, nor the legal command names.  The intent is to   allow for extension without changing the grammar.1.2.     Example mail messages   The following mail messages will be used throughout this document in   examples.   Message A   -----------------------------------------------------------   Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)   From: coyote@desert.example.org   To: roadrunner@acme.example.com   Subject: I have a present for you   Look, I'm sorry about the whole anvil thing, and I really   didn't mean to try and drop it on you from the top of the   cliff.  I want to try to make it up to you.  I've got some   great birdseed over here at my place--top of the lineShowalter                   Standards Track                     [Page 4]RFC 3028            Sieve: A Mail Filtering Language        January 2001   stuff--and if you come by, I'll have it all wrapped up   for you.  I'm really sorry for all the problems I've caused   for you over the years, but I know we can work this out.   --   Wile E. Coyote   "Super Genius"   coyote@desert.example.org   -----------------------------------------------------------   Message B   -----------------------------------------------------------   From: youcouldberich!@reply-by-postal-mail.invalid   Sender: b1ff@de.res.example.com   To: rube@landru.example.edu   Date:  Mon, 31 Mar 1997 18:26:10 -0800   Subject: $$$ YOU, TOO, CAN BE A MILLIONAIRE! $$$   YOU MAY HAVE ALREADY WON TEN MILLION DOLLARS, BUT I DOUBT   IT!  SO JUST POST THIS TO SIX HUNDRED NEWSGROUPS!  IT WILL   GUARANTEE THAT YOU GET AT LEAST FIVE RESPONSES WITH MONEY!   MONEY! MONEY! COLD HARD CASH!  YOU WILL RECEIVE OVER   $20,000 IN LESS THAN TWO MONTHS!  AND IT'S LEGAL!!!!!!!!!   !!!!!!!!!!!!!!!!!!111111111!!!!!!!11111111111!!1  JUST   SEND $5 IN SMALL, UNMARKED BILLS TO THE ADDRESSES BELOW!   -----------------------------------------------------------2.      Design2.1.     Form of the Language   The language consists of a set of commands.  Each command consists of   a set of tokens delimited by whitespace.  The command identifier is   the first token and it is followed by zero or more argument tokens.   Arguments may be literal data, tags, blocks of commands, or test   commands.   The language is represented in UTF-8, as specified in [UTF-8].   Tokens in the ASCII range are considered case-insensitive.2.2.     Whitespace   Whitespace is used to separate tokens.  Whitespace is made up of   tabs, newlines (CRLF, never just CR or LF), and the space character.   The amount of whitespace used is not significant.Showalter                   Standards Track                     [Page 5]RFC 3028            Sieve: A Mail Filtering Language        January 20012.3.     Comments   Two types of comments are offered.  Comments are semantically   equivalent to whitespace and can be used anyplace that whitespace is   (with one exception in multi-line strings, as described in the   grammar).   Hash comments begin with a "#" character that is not contained within   a string and continue until the next CRLF.   Example:  if size :over 100K { # this is a comment                discard;             }   Bracketed comments begin with the token "/*" and end with "*/" outside   of a string.  Bracketed comments may span multiple lines. Bracketed   comments do not nest.   Example:  if size :over 100K { /* this is a comment                this is still a comment */ discard /* this is a comment                */ ;             }2.4.     Literal Data   Literal data means data that is not executed, merely evaluated "as   is", to be used as arguments to commands.  Literal data is limited to   numbers and strings.2.4.1.   Numbers   Numbers are given as ordinary decimal numbers.  However, those   numbers that have a tendency to be fairly large, such as message   sizes, MAY have a "K", "M", or "G" appended to indicate a multiple of   a power of two.  To be comparable with the power-of-two-based   versions of SI units that computers frequently use, K specifies   kibi-, or 1,024 (2^10) times the value of the number; M specifies   mebi-, or 1,048,576 (2^20) times the value of the number; and G   specifies tebi-, or 1,073,741,824 (2^30) times the value of the   number [BINARY-SI].   Implementations MUST provide 31 bits of magnitude in numbers, but MAY   provide more.   Only positive integers are permitted by this specification.Showalter                   Standards Track                     [Page 6]RFC 3028            Sieve: A Mail Filtering Language        January 20012.4.2.   Strings   Scripts involve large numbers of strings as they are used for pattern   matching, addresses, textual bodies, etc.  Typically, short quoted   strings suffice for most uses, but a more convenient form is provided   for longer strings such as bodies of messages.   A quoted string starts and ends with a single double quote (the <">   character, ASCII 34).  A backslash ("\", ASCII 92) inside of a quoted   string is followed by either another backslash or a double quote.   This two-character sequence represents a single backslash or double-