





Network Working Group                                       T. Showalter
Internet Draft: Sieve                                    Carnegie Mellon
Document: draft-showalter-sieve-03.txt                      January 1998
Expire in six months (DD Jun 1998)


                   Sieve -- a Mail Filtering Language


Status of this memo

   This document is an Internet-Draft.  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-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.''

   To learn the current status of any Internet-Draft, please check the
   ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
   Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe),
   munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
   ftp.isi.edu (US West Coast).

   The protocol discussed in this document is experimental and subject
   to change.  Persons planning on either implementing or using this
   protocol are STRONGLY URGED to get in touch with the author before
   embarking on such a project.

Copyright

   Copyright (C) The Internet Society 1998.  All Rights Reserved.

Abstract

   This document describes a mail filtering language for filtering
   messages at time of final delivery.  It is designed to be independent
   of protocol, and 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 IMAP servers, as
   it has no variables, loops, or ability to shell out to external
   programs.




Showalter                 Expires 31 Jun 1998                   [Page 1]

Internet DRAFT                   Sieve                  January 21, 1998





                           Table of Contents



Status of this memo
Copyright
Abstract
0. Meta-information on this draft
0.1. Discussion
0.2. Known Problems
0.2.1. Probable Extensions
0.2.2. Known Bugs
0.3. Open Issues
0.3. Noted Changes
0.3.1 since 02 draft
1. Introduction
1.1. Conventions used in this document
1.2. Example mail messages
2. Design
2.1. Form of the language
2.2. Whitespace
2.3. Comments
2.4. Numbers
2.5. Strings
2.5.2. String lists
2.5.3. Headers
2.5.4. Addresses
2.6. String Comparison
2.6.1. Match Keyword
2.6.2. Comparators
2.7. Evaluation
3. Conditionals and Control Structures
3.1. If
4. Actions
4.1. Action reject
4.2. Action fileinto
4.3. Action forward
4.4. Action keep
4.5. Action reply
4.6. Action stop
4.7. Action discard
5. Tests
5.1. Test allof
5.2. Test anyof
5.3. Test exists



Showalter                 Expires 31 Jun 1998                   [Page 2]

Internet DRAFT                   Sieve                  January 21, 1998


5.4. Test false
5.5. Test header
5.6. Test not
5.7. Test size
5.8. Test support
5.9. Test true
6. Errors in Processing a Script
7. Extensibility
7.1. Capability String
7.2. Registry
7.3. Capability Transport
8. Transmission
9. Acknowledgments
10.  Formal Grammar
11. Security Considerations
12. Author's Address
Appendices
Appendix A.  References
Appendix B. Full Copyright Statement
































Showalter                 Expires 31 Jun 1998                   [Page 3]

Internet DRAFT                   Sieve                  January 21, 1998





















































Showalter                 Expires 31 Jun 1998                   [Page 2]

Internet DRAFT                   Sieve                  January 21, 1998


0. Meta-information on this draft

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

0.1. Discussion

   This draft is being discussed on the MTA Filters mailing list at
   <ietf-mta-filters@imc.org>.  Subscription requests can be sent to
   <ietf-mta-filters-request@imc.org> (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
   <http://www.imc.org/ietf-mta-filters>.

0.2. Known Problems

0.2.1. Probable Extensions

   The following suggestions have been made, and will probably be
   addressed by extensions.

   An extension for regular expressions will be written.  While regular
   expressions are of questionable utility for most users, the
   programmers writing implementations desperately want regular
   expressions.

   Envelope-matching commands are not readily supported by all mail
   systems, and putting them in the draft will result in a system that
   cannot be implemented by a mail architecture that does not adequately
   store envelopes.

   "Detailed" addressing or "sub-addressing" (i.e., the "fmh" in an
   address "tjs+fmh@andrew.cmu.edu") is not handled, and will be moved
   to an extension for those systems that offer it.

   A vacation command has been requested for an extension; a preliminary
   draft exists and will be submitted to the internet-drafts repository.
   It isn't in the draft because having vacation assumes you can store
   the addresses of people who have already received vacation
   notifications, which isn't always the case.

   A suggestion was made to set IMAP flags on delivery (e.g., \Flagged,
   \Deleted, \Answered, \Seen).

   An "include" command is not included, but has been suggested  for  an
   extension.





Showalter                 Expires 31 Jun 1998                   [Page 4]

Internet DRAFT                   Sieve                  January 21, 1998


0.2.2. Known Bugs

   The formal grammar.  (It's better than it was).

   The reject command needs to be rechecked against the DSN
   specification.

   The error-handling clauses of this specification may not be
   completely sensible, and may conflict.

   The discussion of the limits of actions is not there.  Only one
   forward or reject should be allowed per message.  reject should
   prohibit fileinto.  reply should prohibit reject.

   My knowledge of email is not comprehensive, and as a result, there
   might be a better way to express some of the concepts in here.
   Please let me know if there is a good way to clean up the wording.

0.3. Open Issues

   The support tests cause some serious problems with control
   structures.  To some extent, this is solved by separating the block
   construct out from the conditionals themselves.  This has been done
   in this draft (flames welcome, but it seems to be cleaner to me).

   Comma is mandatory in anyof/allof but forbidden in a list of strings;
   it should be required in both.  This needs to be fixed.  I'm clinging
   to the status quo trying to fix the  rest  of  the  problems  at  the
   moment.

   Should there be a way to specify headers transmitted by reply?
   Perhaps a separate command, since there are probably sites that are
   going to be really paranoid about what headers get sent.

   In the event that there is an error while processing a script, what
   happens?  The draft implies you file into INBOX, but what if you've
   already taken actions before you do this?  (The parts of the draft
   that require syntax checking stuff are all SHOULDs.)

   I tried to fill in some of the blanks in previous versions; among
   them, the description of what a rejected input message looks like,
   but it's still nearly incomplete.

   I moved the substring matching stuff out of the  header  command  and
   into  a  section  of  its  own  as  it  is  reusable  by  extensions.
   Suggestions on this section would be appreciated.





Showalter                 Expires 31 Jun 1998                   [Page 5]

Internet DRAFT                   Sieve                  January 21, 1998


   I tried to fill in the blanks in the  section  on  extensibility  and
   borrowed  some stuff from the ACAP spec (specifically, the comparator
   registry), but it's probably not complete or good enough.

   Finally, I suspect that there are a lot of problems relating to what
   filtering for the masses will do to mailing lists, especially what
   will happen the first time someone rolls their own vacation program
   consisting of a reply command.  Should it be an error to reply to a
   message that is not addressed to you (specifically)?

0.3. Noted Changes


0.3.1 since 02 draft

   Changed reply to specify that the message in the reply goes to the
   return-path address (envelope from).

   Added support to the grammar.  (bug)

   Changed reply to take a string as an argument.  (bug)

   Changed "bounce" to "reject".  Was slightly more than a search-
   replace, but may have bugs anyway.  (clarity)

   DSN format reject messages are now REQUIRED.  (feature)

   Reject now overrides everything period, and is not merely a demand to
   send a DSN to the sender.  (feature)

   Changed "all-of" and "any-of" to "allof" and "anyof" respectively
   since Chris said we might want math.



















Showalter                 Expires 31 Jun 1998                   [Page 6]

Internet DRAFT                   Sieve                  January 21, 1998


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
   and support of multiple folders, but should work with a wide variety
   of systems that support these criteria.

   The language is powerful enough to be useful, but limited in power 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 GUI-based editors. The language is not Turing-complete,
   and provides no way to write a loop or a function.  Variables are not
   provided.

   Implementations of the language are expected to take place at time of
   final delivery, when the message is finally moved to the user-
   accessible mailbox.  In systems where the MTA does final delivery,
   such as and traditional UNIX mail, is reasonable to sort when the MTA
   deposits mail into the user's mailbox.  If the MTA does not do final
   delivery, or lacks the power to sort into separate mailboxes, as is
   the case under POP3, the MUA must do filtering into local-disk
   folders.

   There are a number of reasons to use a filtering system.  Mail
   traffic for most users has been increasing due both 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 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.

1.1. Conventions used in this document

   In examples, line breaks have been inserted for readability.

   In the sections of this document that discuss the requirements of



Showalter                 Expires 31 Jun 1998                   [Page 7]

Internet DRAFT                   Sieve                  January 21, 1998


   various keywords and operators, the following conventions have been
   adopted.

   The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "CAN", and
   "MAY" in this document are to be interpreted as defined in
   [KEYWORDS].

   Each section on a 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 "]").  However, the formal grammar
   for these commands in section 10 and is the authoritative reference
   on how to construct these commands.

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.org
   To: roadrunner@birdseed.org
   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
   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@znic.net
   -----------------------------------------------------------














Showalter                 Expires 31 Jun 1998                   [Page 8]

Internet DRAFT                   Sieve                  January 21, 1998


   Message B
   -----------------------------------------------------------
   From: youcouldberich!@reply-by-postal-mail
   Sender: b1ff@de.res.frobnitzm.edu
   To: rube@landru.melon.net
   Date:  Mon, 31 Mar 1997 18:26:10 -0800 (PST)
   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

   This language is made up as a set of commands.  Each command is
   either an action or a conditional.  Each conditional contains a test;
   depending on the results of the test, one set of commands in a
   control structure is taken.

2.2. Whitespace

   Whitespace is used to separate commands.  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.

2.3. Comments

   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;
             }

2.4. 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 base-two number.  To be comparable with the power-of-two-based
   versions of SI units that computers frequently use, K specifies kilo,



Showalter                 Expires 31 Jun 1998                   [Page 9]

Internet DRAFT                   Sieve                  January 21, 1998


   or 1,024 (2^10) times the value of the number; M specifies mega, or
   1,048,576 (2^20) times the value of the number; and G specifies giga,
   or 1,073,741,824 (2^30) times the value of the number.

   Implementations MUST provide 31 bits of magnitude in numbers, but may
   provide more.

   Negative, fractional, and decimal numbers are not permitted  by  this
   specification.

2.5. Strings

   Scripts involve large numbers of strings, as they are used for
   pattern matching, addresses, and 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).  A backslash ("\") 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-quote within the
   string, respectively.

   Other escape sequences may be permitted depending on context (such as
   in globs, defined in section 2.6 on string comparison).  An undefined
   escape sequence (such as "\a" in a context where "a" has no special
   meaning) is interpreted as if there were no backslash (in this case,
   "\a" is just "a").

   Non-printing characters such as tabs, CR and LF, and control
   characters are permitted in strings.  NUL (ASCII 0) is not allowed in
   strings.

   For entering larger amounts of text, such as an email message, a
   multi-line form is allowed.  It starts with the keyword "text:",
   followed by a CRLF, and ends with the sequence of a CRLF, a single
   period, and another CRLF.  In order to allow the message to begin
   lines with a single-dot, lines are dot-stuffed.  That is, when
   composing a message body, an extra `.' is added before each line
   which begins with a `.'.  When the server interprets the script,
   these extra dots are removed.

   Note that a comment may occur in between the "text:" and the CRLF,
   but not within the string itself.

   Example:  if anyof (header ("from") contains
                   ("bart", "homer", "smithers", "burns", "lisa"),
                header ("subject") contains ("URGENT")) {



Showalter                 Expires 31 Jun 1998                  [Page 10]

Internet DRAFT                   Sieve                  January 21, 1998


                keep;
             } else {
                reply text: # multi-line message here:
             You are not one of the people I regularly
             correspond with.  I have deleted your message
             due to the large volume of email I regularly
             receive.  If you feel that you need to speak
             with me directly, and cannot find your answer
             in my web pages, please send mail with the
             word "URGENT" in the subject line.  Thank you
             for your time.
             .
             ;
             }

2.5.2. String lists

   When matching patterns, strings frequently come in groups.  For this
   reason, a list of strings is allowed in many tests, implying that if
   the test is true using any one of the strings, then the test is true.
   Implementations are encouraged to use short-circuit evaluation in
   these cases.

   For instance, the test `header ("To" "Cc") contains
   ("me@frobnitzm.edu", "me00@landru.melon.edu")' is true if either the
   To header or Cc header of the input message contains either of the
   e-mail addresses "me@frobnitzm.edu" or "me00@landru.melon.edu".

   Conversely, in any case where a list of strings would be appropriate,
   a single string is allowed without being a member of a list; it is
   equivalent to a list with a single member.  So the test `exists "To"'
   is equivalent to the test `exists ("To")'.

2.5.3. Headers

   Headers are a subset of strings.  In the Internet Message
   Specification [IMAIL], each header line is allowed to have whitespace
   nearly anywhere in the line, including after the field name and
   before the subsequent colon.  Extra spaces between the header name
   and the ":" in a header field are ignored by the interpreter.

   A header name never contains a colon.  The "From" header refers to a
   line beginning "From:" (or "From   :", etc.).  No header will match
   the string "From:" due to the trailing colon.







Showalter                 Expires 31 Jun 1998                  [Page 11]

Internet DRAFT                   Sieve                  January 21, 1998


2.5.4. Addresses

   A number of commands call for email addresses, which are also a
   subset of strings.  These addresses must be compliant with [IMAIL].
   Implementations MUST ensure the addresses are syntactically valid,
   and need not ensure that they are actually deliverable.

2.6. String Comparison

   When matching one string against another, there are a number of ways
   of performing the match.  These are accomplished with three matches
   -- an exact match, a substring match, and a wildcard glob-style
   match.  In order to provide for matches between character sets and
   case insensitivity, Sieve borrows ACAP's comparator registry.

2.6.1. Match Keyword

   There are three allowed match keywords describing the allowed match
   in this draft; they are "is", "contains", and "matches".

   The "contains" version describes a substring match.  If the value
   argument contains the key argument as a substring, the match is true.
   For instance, the string "frobnitzm" contains "frob" and "nit", but
   not "fbm".  The null key ("") is contained in all values.

   The "is" version describes an absolute match; if the contents of the
   first string are absolutely the same as the contents of the second
   string, they match.  Only the string "frobnitzm" is the string
   "frobnitzm".  The null key only "is" the null value.

   The "matches" is a UNIX-style "glob" match; it specifies that the key
   is not substring, but contains certain special characters that match
   characters that are not themselves.  These characters are

           *     Match zero or more characters
           ?     Match any single character
           \     Escape next character

   Escaped special characters do not take on the meanings listed above.

   The value "frobnitzm" matches the keys "*nit*", "f*b*m", and "fr?b*",
   but not "nit" or "frob".  The null key matches only the null value.

   The "contains" and "matches" versions necessitate that one string
   supplied as an argument is a key, and the other is a value.  Commands
   that utilize these comparisons, generally of the form "<value>
   <match-keyword> <key>", must be sure to differentiate which is which.




Showalter                 Expires 31 Jun 1998                  [Page 12]

Internet DRAFT                   Sieve                  January 21, 1998


2.6.2. Comparators

   In order to allow for character set-independent matches, the match
   keyword may be coupled with a comparator name.  Comparators are
   described for [ACAP]; a registry is defined for ACAP, and this
   specification uses that registry.

   ACAP defines multiple comparator types.  Only equality types are used
   in this specification.

   All implementations MUST support the "i;octet" comparator, which
   simply compares one octet with the next.  If left unspecified, the
   default is octet.

   If an implementation supports a comparator "elbonia", it MUST provide
   the capability "comparator-elbonia" for support tests.

   Some comparators may not be usable with substring matches; that is,
   they may only work with "is".  It is an error to try and use a
   comparator with "matches" or "contains" that is not compatible with
   it.

   OPEN:   Are there any other comparators that SHOULD or MUST be
           supported?


2.7. Evaluation

   If evaluation of the script fails to file the message into any
   mailbox, as in the following script, the message is filed into INBOX.
   With any of the short messages offered above, the following script
   produces no actions.


   Example:  if size over 500K discard;

   In cases like this, the "keep" action is taken.  The "keep" action is
   defined to be the action that is taken in a situation where the user
   does no filtering.  For instance, under an IMAP-based system, this
   implies filing into INBOX.

   Sieve imposes specific limits on actions; for instance, a rejected
   message may not also be filed into a mailbox.  These restrictions are
   noted on a per-command basis.  [no they're not]

   Precedence is not important in any of the commands in this base
   specification.  However, as an extension might make order of
   operation important, all arguments to rules MUST be evaluated in



Showalter                 Expires 31 Jun 1998                  [Page 13]

Internet DRAFT                   Sieve                  January 21, 1998


   left-to-right order.  Those operations that can implement short-
   circuit evaluation (such as "allof" and "anyof") MUST do so.

3. Conditionals and Control Structures


   In order for a script to do more than one set of actions, control
   structures are needed.  In this document, only one control structure
   is supplied.

3.1. If


   Syntax:   if <test> <command> [else <command>]

   The "if" control structure is borrowed from any number of programming
   languages.  It is evaluated in the usual way if the test is true then
   the first command (or set of commands) supplied is evaluated.  If the
   test is false and an else keyword follows the if block, the second
   command is evaluated.  The commands may be command blocks.  [OPEN:
   This allows C-style dangling statements; I construe this as a
   feature.]

   In the following example, both Message A and B are dropped.

   Example:  if header "from" contains "coyote" {
                discard;
             } else if  header ("subject") contains ("$$$") {
                discard;
             } else fileinto "INBOX";


   Only one command or block of commands in an if ... else if ... else
   chain is executed.

   In the script below, when run over message A, forwards the message to
   acm@frobnitzm.edu;  message B, to postmaster@frobnitzm.edu; any other
   message is forwarded to field@frobnitzm.edu.

   Example:  if header ("From") contains ("coyote") {
                forward "acm@frobnitzm.edu";
             } else if header "Subject" contains "$$$" {
                forward "postmaster@frobnitzm.edu";
             } else
                forward "field@frobnitzm.edu";






Showalter                 Expires 31 Jun 1998                  [Page 14]

Internet DRAFT                   Sieve                  January 21, 1998


4. Actions


   This document supplies six actions that may be taken on a message:
   keep, fileinto, forward, reject, discard, and stop.

4.1. Action reject


   Syntax:   reject <reason-string>

   The "reject" action resends the message to the sender, wrapping it in
   a "reject" form, noting that it was rejected by the recipient.  In
   the following script, message A is rejected and returned to the
   sender.

   Example:  if header "from" contains "coyote@znic.net" {
                reject "I am not taking mail from you, and I don't want
                your birdseed, either!";
             }

   A reject message MUST takes the form of a failed DSN as specified  by
   [DSN].    The  human-readable  portion  of  the  message,  the  first
   component of the DSN, contains the human readable message  describing
   the  error,  although  it SHOULD contain additional text alerting the
   original sender that mail was refused by a filter.  This part of  the
   DSN might appear as follows:

   ------------------------------------------------------------
   Message was refused by recipient's mail filtering program.
   Reason given was as follows:

   I am not taking mail from you, and I don't want your
   birdseed, either!
   ------------------------------------------------------------

   The action-value field as defined in the DSN specification MUST be
   "failed".

   OPEN:   This section is probably incomplete.  I am not sure that the
           right answer is to make it easy to refuse messages, but
           secretly keep a copy.  Should "reject" prevent all other
           actions from taking affect?


   A rejected message may not be filed, forwarded, or kept.  A message
   that triggers a "reject" action is never allowed to be kept by the
   user, and the "reject" overrides all other actions.



Showalter                 Expires 31 Jun 1998                  [Page 15]

Internet DRAFT                   Sieve                  January 21, 1998


   A message may only be rejected once.

4.2. Action fileinto


   Syntax:   fileinto <folder>

   The "fileinto" action drops the message into a named folder.
   Implementations SHOULD support fileinto, but may not be able to in
   cases where the filtering agent is not able to write to the users'
   folders (such as a [POP3] implementation running inside the mail
   server where the folders are stored on the users' local disks).

   As such, a server supporting fileinto MUST provide the "fileinto"
   capability for the support tests.

   In  the  following  script,  message   A   is   filed   into   folder
   "INBOX.harassment".

   Example:  if header ("to") contains "coyote" {
                fileinto "INBOX.harassment";
             }

4.3. Action forward


   Syntax:   forward <address>

   The "forward" action is used to forward the message to another user
   at the supplied address, as a mail forwarding feature does.  The
   "forward" action makes no changes to the message body or headers, and
   only modifies the envelope recipient.

   A simple script can be used for forwarding:

   Example:  forward "bart@frobnitzm.edu";

   The forward command performs an MTA-style forward --  that  is,  what
   you  get from a .forward file using sendmail under UNIX.  The address
   on the SMTP envelope is replaced with the one on the forward  command
   and the message is sent back out.  (This is not an MUA-style forward,
   which creates a new message with a different sender and  message  ID,
   wrapping the old message in a new one.)

4.4. Action keep


   Syntax:   keep



Showalter                 Expires 31 Jun 1998                  [Page 16]

Internet DRAFT                   Sieve                  January 21, 1998


   The "keep" action is whatever action is taken in lieu of all other
   actions, if no filtering happens at all; generally, this simply means
   to file the message into the user's main mailbox.  This command
   provides a way to execute this action without needing to know the
   name of the user's main mailbox, providing a way to call it without
   needing to understand the user's setup, or the underlying mail
   system.

   Example:  if size under 1M keep; else discard;

4.5. Action reply


   Syntax:   reply <message>

   The "reply" action is used to generate a form letter reply to the
   original sender, as specified in the return-path header of the
   incoming message.  Message is a string to be sent as a reply message.
   In the following example, any message larger than 500K (524288
   octets) would be replied to with a message explaining that it was
   rejected; otherwise, the message would be filed into INBOX (by
   default).

   Example:  if size over 500K {
                reply text:
             Your message was unnecessarily large.  I reject all large
             messages; if you need to send me a large message, please
             contact me first and arrange outer means.
             .
             ; discard; }

4.6. Action stop


   Syntax:   stop

   The "stop" action ends all processing.  If no actions have been
   executed, then the keep action is taken.

   In the following script, if the mail is from the address
   "boss@frobnitzm.edu" it is forwarded to "pleeb@frobnitzm.edu";
   otherwise the mail receives a reply, and is thrown out.

   Example:  if header ("from") matches ("boss@frobnitzm.edu") {
                forward "pleeb@xanadu.wv.us";
                stop;
             } reply text:
             I'm on vacation and not taking any messages; try after



Showalter                 Expires 31 Jun 1998                  [Page 17]

Internet DRAFT                   Sieve                  January 21, 1998


             Sunday.  I have thrown your message out.  Please resend it
             later.
             .
             ; discard;

4.7. Action discard


   Syntax:   discard

   Discard drops the message.  In the following script, any mail from
   "idiot@frobnitzm.edu" is thrown out.

   Example:  if header ("from") contains ("idiot@frobnitzm.edu")
             discard;

   While an important part of this language, "discard" has the potential
   to create serious problems for users.  For instance, a student
   leaving themselves logged in to a machine in a computer lab may find
   their script changed to just "discard".  In order to protect users in
   this situation (along with similar situations), implementations MAY
   keep messages destroyed by a script for an indefinite period, and MAY
   disallow scripts that throw out all mail.

5. Tests


   Tests are used in conditionals to decide which part(s) of the
   conditional to execute.

5.1. Test allof


   Syntax:   allof ( <test> , <test> , ... <test> )

   The allof test preforms a logical AND on the tests supplied to it.

   Example:  allof (false, false)  =>   false
             allof (false, true)   =>   false
             allof (true, true)    =>   true











Showalter                 Expires 31 Jun 1998                  [Page 18]

Internet DRAFT                   Sieve                  January 21, 1998


5.2. Test anyof


   Syntax:   anyof ( <test> , <test> , ... <test> )

   The anyof test preforms a logical OR on the tests supplied to it.

   Example:  anyof (false, false)  =>   false
             anyof (false, true)   =>   true
             anyof (true, true)    =>   true

5.3. Test exists


   Syntax:   exists <header-name-list>

   The "exists" test is true if the headers listed in the
   <header-name-list> argument exist within the message.  All of the
   headers must exist or the test is false.  The test
           exists ("From", "To", "Cc")
   is equivalent to
           header ("From", "To", "Cc") contains ""

   The following example throws out mail that doesn't have a From header
   and a Date header.

   Example:  if not exists ("From","Date") {
                discard;
             }

5.4. Test false


   Syntax:   false

   The "false" test always evaluates to false.

5.5. Test header


   Syntax:   header <header-name-list> <match-keyword> <key-list>

   The "header" test evaluates to true if the any header name matches
   any key.  How the match is done is described by the second argument,
   which is one of the string comparison arguments discussed in section
   2.6.  The first argument to header, the header-name-list, is a list
   of headers to get values from to be searched.  The key-list is a list
   of keys.



Showalter                 Expires 31 Jun 1998                  [Page 19]

Internet DRAFT                   Sieve                  January 21, 1998


   If a header  listed  in  the  header-name-list  argument  exists,  it
   contains  the  null  key  ("").   However, if the named header is not
   present, it does not contain the null key. So if a message  contained
   the header

           X-Caffeine: C8H10N4O2

   these tests on that header evaluate as follows:

           header ("X-Caffeine") is ("")         => false
           header ("X-Caffeine") matches ("")    => false
           header ("X-Caffeine") contains ("")   => true

5.6. Test not


   Syntax:   not <test>

   The "not" test takes some other test as an argument, and yields the
   opposite result.

5.7. Test size


   Syntax:   size <"over" / "under"> <limit [quantifier]>

   The "size" test deals with the size of a message.  The test is true
   only if the first argument is "over" and the size of the message is
   strictly greater than the number of octets specified as limit.  If
   the first argument is "under", then the test is true only if the
   message size is strictly less than the number of octets specified as
   limit.  In either case, if the message size is exactly the limit, the
   test is false.

   The size of a message is defined to be the number of octets from the
   initial header until the last character in the message body.

5.8. Test support


   Syntax:   support <extension-name>

   The "support" test evaluates to true if the extension named by
   <extension-name> is supported.  In the following script, all mail is
   filed into INBOX unless the "black-magic" extension is supported.
   Otherwise, behavior is defined by the black-magic extension.





Showalter                 Expires 31 Jun 1998                  [Page 20]

Internet DRAFT                   Sieve                  January 21, 1998


   Example:  if support "black-magic" {
                black-magic ("zork@frobnitzm.edu");
             }

5.9. Test true


   Syntax:   true

   The "true" test is always true.

6. Errors in Processing a Script

   In any programming language, errors are inevitable.  Users are
   expected to make errors, and changes in the environment, such as a
   change in a user's rights on a mailbox, can cause a script to fail.
   It is imperative that mail be allowed to get through.

   Implementations SHOULD check a script before it is run in order to
   ensure that it is valid.  Implementations SHOULD NOT try and recover
   from a script with errors, and should file mail into the user's
   primary mailbox.

   Users MUST be notified of errors in processing a script.  The method
   by which users are notified is implementation defined, but a mail
   message clearly describing the error is suggested if a preferable
   alternative cannot be found.

   In an implementation that allows for a script to be checked when it
   is turned over to the server, the script can be checked for errors
   before it is submitted.  Implementations SHOULD notify the user of
   the error and refuse to accept a syntactically invalid script or one
   that makes use of extensions that the server does not report.

   Implementations MUST allow mail to be filed without filtering in case
   of a syntax error in the script.  Implementations MUST avoid sending
   multiple messages describing the same error.

   Implementations are REQUIRED to notify users of errors in filtering
   scripts.  If there are errors in the script being used, mail SHOULD
   be filed into the user's main mailbox.  Implementations MUST NOT
   discard mail unless a command explicitly demands it.

7. Extensibility

   New control structures, actions, and tests can be added to the
   language.  Sites must make these features known to their users; this
   document does not define a way to discover the list of extensions



Showalter                 Expires 31 Jun 1998                  [Page 21]

Internet DRAFT                   Sieve                  January 21, 1998


   supported by the server.

   Any extensions to this language MUST define a string that uniquely
   identifies that extension.  If a new version of an extension changes
   the functionality of a previously defined extension, it MUST use a
   different name.  The purpose of such a string is for the "support"
   test, which mandates that script requires the use of that extension.

   Additionally, in a situation where there is a submission protocol and
   an extension advertisement mechanism aware of the details of this
   language, scripts submitted can be checked against the mail server to
   prevent use of an extension that that the server does not support.

7.1. Capability String

   Capability strings are typically short strings describing what
   capabilities are supported by the server.  The following capability
   strings are defined by this document:

   fileinto    The string "fileinto" indicates the implementation
               supports filing into mailboxes.


7.2. Registry

   In order to provide a standard set of extensions, a registry is
   provided by IANA.  Capability names may be registered on a first-
   come, first-served basis.  Extensions designed for interoperable use
   should be defined as standards track or IESG approved experimental
   RFCs.

   To: XXX@XXX.XXX
   Subject: Registration of new Sieve extension

   Capability name:
   Capability keyword:
   Capability arguments:
   Standards Track/IESG-approved experimental RFC number:
   Person and email address to contact for further information:

7.3. Capability Transport

   As the range of mail systems that this draft is intended to apply to
   is quite large, a method of advertising which capabilities an
   implementation supports is difficult due to the wide range of
   possible implementations.  Such a mechanism, however, should have the
   following properties.




Showalter                 Expires 31 Jun 1998                  [Page 22]

Internet DRAFT                   Sieve                  January 21, 1998


   (1)  The implementation can advertise the complete set of extensions
        that it supports.


   OPEN:   There needs to be a more complete description here.


8. Transmission

   The MIME type for a SIEVE script is "application/sieve".  Scripts are
   encoded in UTF-8 during transmission.

9. Acknowledgments

   I am very thankful to Chris Newman for his support and his ABNF
   syntax checker, to John Myers and Steve Hole for outlining the
   requirements for the original drafts, and to Rob Earhart for an early
   implementation and a great deal of help.  I am also indebted to all
   of the readers of the ietf-mta-filters@imc.org mailing list.

10.  Formal Grammar

   The grammar used in this section is the same as the ABNF described in
   [ABNF].

   In the case of alternative or optional rules in which a later rule
   overlaps an earlier rule, the rule which is listed earlier MUST take
   priority.  (This shouldn't happen.  Please let me know if it does.)

   action = reject / discard / fileinto / forward / keep / reply / stop

   address = string
           ;; any legal [IMAIL] address.

   anyof = "anyof" test-list

   allof = "allof" test-list

   block = "{" [WSP] commands [WSP] "}"
           ;; C-style block

   CHAR-NOT-DOT = (%x01-2d / %x2f-%xff)
           ;; all the characters that aren't "."

   control-structure = if

   command = ( action ";" ) / block / control-structure




Showalter                 Expires 31 Jun 1998                  [Page 23]

Internet DRAFT                   Sieve                  January 21, 1998


   commands = *([WSP] command [WSP])

   comment = "#" *VCHAR CRLF

   comparator = "octet"
           ;; octet is the only comparator mandated by this specification
           ;; but others may be defined by the ACAP registry.

   discard = "discard"

   exists = "exists" WSP string

   false = "false"

   fileinto = "fileinto" WSP string
           ;; string is a mailbox; semantics are defined by the
           ;; underlying mail system

   forward = "forward" WSP address

   if = "if" WSP test WSP command [ "else" command ]
           ;; Commands are typically blocks.

   header = "header" WSP string-list WSP match-keyword WSP string-list

   keep = "keep"

   match-keyword = ("contains" / "matches" / "is") ["-" comparator]

   multi-line = "text:" [WSP] CRLF
           *((1*CHAR-NOT-DOT *CHAR CRLF) / ("." 1*CHAR-NOT-DOT *CHAR CRLF) /
             (".." *CHAR CRLF) / CRLF)
           "." CRLF
           ;; Note when used,
           ;; a leading ".." on a line is mapped to ".".

   not = "not" WSP test

   number = 1*DIGIT [QUANTIFIER]
           ;; quantifier is a multiplier (or bit shift)

   QUANTIFIER = "K" / "M" / "G"
           ;; K == 2^10; M == 2^20; G = 2^30

   quoted-string = DQUOTE *CHAR DQUOTE
           ;; \" inside a string maps to "
           ;; \\ inside a string maps to \
           ;; All other characters map to themselves.



Showalter                 Expires 31 Jun 1998                  [Page 24]

Internet DRAFT                   Sieve                  January 21, 1998


           ;; Note that newlines and other weird characters
           ;; are all allowed strings.

   reject = "reject" WSP string
           ;; string is the reason contained in the DSN.

   reply = "reply" WSP string

   size = "size" WSP ( "over" / "under" ) WSP number

   stop = "stop"

   string = quoted-string / multi-line

   string-list = "(" [WSP] *(string [WSP] "," [WSP]) string [WSP] ")" / string
           ;; if there is only a single string, the parens are optional

   support = "support" WSP string

   test = [WSP] (anyof / allof / exists / false / header /
       not / size / support) [WSP]

   test-list = [WSP] "(" [WSP] *(test [WSP] "," [WSP])
       test [WSP] ")" [WSP]

   true = "true"

   WSP = 1*(SP / CRLF / HTAB) / comment
           ;; just whitespace.  anyplace this is allowed, a comment is
           ;; as well

11. Security Considerations

   Users must get their mail.  It is imperative that whatever method
   implementations use to store the user-defined filtering scripts be
   secure.

   It is equally important that implementations sanity-check the user's
   scripts, and not allow users to create on-demand mailbombs.  For
   instance, an implementation that allows a user to reject, forward, or
   reply multiple times to a single message might also allow a user to
   create a mailbomb triggered by mail from a specific user.

   Therefore, an implementation SHOULD only allow one "reject" per
   message processed, and MAY limit the number of forward and reply
   actions taken.  An implementation MUST refuse to forward a message to
   itself.  [OPEN: What do you do when a site limit prevents you from
   this?  Say I do three replies; which ones take effect when the limit



Showalter                 Expires 31 Jun 1998                  [Page 25]

Internet DRAFT                   Sieve                  January 21, 1998


   is 1? 2? 0?]

   Several commands, such as "discard", "forward", and "fileinto" allow
   for actions to be taken that are potentially very dangerous.

12. Author's Address

   Tim Showalter
   Carnegie Mellon University
   5000 Forbes Avenue
   Pittsburgh, PA 15213

   E-Mail: tjs@andrew.cmu.edu






































Showalter                 Expires 31 Jun 1998                  [Page 26]

Internet DRAFT                   Sieve                  January 21, 1998


Appendices

Appendix A.  References

   [ABNF] Crocker, D.,  "Augmented BNF for Syntax Specifications: ABNF",
   Internet Mail Consortium, Work in Progress.

   [DSN] Moore, K., and G. Vaudreuil, "An Extensible Message Format for
   Delivery Status Notifications", RFC 1894, January, 1996.

   [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
   Requirement Levels", RFC 2119, Harvard University, March 1997.

   [IMAP] Crispin, M., "Internet Mail Access Protocol - version 4rev1",
   RFC 2060, University of Washington, December 1996.

   [IMAIL] Crocker, D., "Standard for the Format of ARPA Internet Text
   Messages", STD 11, RFC 822, University of Delaware, August 1982.

   [MIME] Freed, N., and N. Borenstein, "Multipurpose Internet Mail
   Extensions (MIME) Part One: Format of Internet Message Bodies", RFC
   2045, Innosoft and First Virtual, November 1996.

   [SMTP] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821,
   USC/Information Sciences Institute, August 1982.

   [UTF-8] Yergeau, F. "UTF-8, a transformation format of Unicode and
   ISO 10646", RFC 2044, Alis Technologies, October 1996.



Appendix B. Full Copyright Statement

   Copyright (C) The Internet Society 1998. All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.



Showalter                 Expires 31 Jun 1998                  [Page 27]

Internet DRAFT                   Sieve                  January 21, 1998


   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

This document will expire before June 31, 1998.















































Showalter                 Expires 31 Jun 1998                  [Page 28]

