rfc3028.txt

RFC3028:Sieve: A Mail Filtering Language

Network Working Group                                       T. Showalter
Request for Comments: 3028                               Mirapoint, Inc.
Category: Standards Track                                   January 2001


                    Sieve: A Mail Filtering Language

Status 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 ............................................   9



Showalter                   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 ...........................................  29



Showalter                   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 ...............................  36

1.      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 2001


1.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: [e-mail]
   To: [e-mail]
   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 line




Showalter                   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"   [e-mail]
   -----------------------------------------------------------

   Message B
   -----------------------------------------------------------
   From: youcouldberich!@reply-by-postal-mail.invalid
   Sender: [e-mail]
   To: [e-mail]
   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.      Design

2.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 2001


2.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 2001


2.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-