[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 06 07 08 09 10 11 RFC 3028

Network Working Group                                       T. Showalter
Internet Draft                                           Carnegie Mellon
Document: draft-showalter-sieve-01.txt                         June 1997
Expire in six months (12/97)



                    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.

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 which uses multiple folders.  It is meant to be
     extensible, simple, and independent of access protocol, mail
     architecture, and operating systems used to implement it.  It is
     not tied to any particular system or mail architecture.  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, and has no variables, loops, or ability to shell out to
     external programs.





Showalter                                                       [Page i]

Internet Draft                   Sieve                          May 1997





                           Table of Contents



Status of this memo
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
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
3.2. Require
4. Actions
4.1. Action bounce
4.2. Action fileinto
4.3. Action forward
4.4. Action keep
4.5. Action reply
4.6. Action stop
4.7. Action toss
5. Tests
5.1. all-of
5.2. any-of
5.3. exists
5.4. false
5.5. header



Showalter                                                      [Page ii]

Internet Draft                   Sieve                          May 1997


5.6. not
5.7. size
5.8. support
5.9. 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



































Showalter                                                     [Page iii]

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 previous version included a "valid" test.  I have tentatively
     removed it because Randy had noted it was too fuzzy to implement,
     and that's probably true.

     A vacation command has been requested for an extension.  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).





Showalter                                                       [Page 1]

Internet Draft                   Sieve                          May 1997


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

0.2.2. Known Bugs

     The formal grammar should be okay, but probably isn't.

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

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

     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 and require 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 any-of/all-of 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 bounced input message looks like,
     but it's still nearly incomplete.

     What happens when someone supplies an invalid escape sequence (like
     "\a") in a string or a match key?

     I moved the substring matching stuff out of the header command and
     into a section of its own as it is reusable by extensions.



Showalter                                                       [Page 2]

Internet Draft                   Sieve                          May 1997


     Suggestions on this section would be appreciated.

     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)?







































Showalter                                                       [Page 3]

1. Introduction

     This draft is offered to provide a standard 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.




Showalter                                                       [Page 1]

Internet Draft                   Sieve                          May 1997


     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", "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@anvil.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@anvil.org
     -----------------------------------------------------------













Showalter                                                       [Page 2]

Internet Draft                   Sieve                          May 1997


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


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



Showalter                                                       [Page 3]

Internet Draft                   Sieve                          May 1997


     versions of SI units that computers frequently use, K specifies
     kilo, 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
     draft.

2.5. Strings

     Scripts involve large numbers of strings, as they're used for
     pattern matching, addresses, and textual bodies, among other
     things..  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.

     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.














Showalter                                                       [Page 4]

Internet Draft                   Sieve                          May 1997



     Example:    if any-of (header ("from") contains
                           ("bart" "homer" "smithers" "burns" "lisa"),
                      header ("subject") contains ("URGENT")) {
                      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                                                       [Page 5]

Internet Draft                   Sieve                          May 1997


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 insure the addresses are syntactically valid,
     and need not insure 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 only valid escape sequences are "\*", "\?" and "\\".

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

     The "contains" and "matches" versions necessitate that one string



Showalter                                                       [Page 6]

Internet Draft                   Sieve                          May 1997


     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.

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
     draft borrows that registry.

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

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

     Some comparators may not be usable with substring matches; that is,
     they may only work with "is".  [OPEN: Not sure what to do about
     this.]  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 toss;

     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.

Implementations define the specific meanings of actions.
Implementations MAY impose restrictions on the actions taken, such as
only honoring one "reply", "bounce", or "forward" per message.

OPEN:   In this case, which is honored?  I'm tempted to say random, but
        restrict it to those commands that send mail back out (fileinto



Showalter                                                       [Page 7]

Internet Draft                   Sieve                          May 1997


        as many mailboxes as you want).

     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 left-to-right
order.  Those operations that can implement short-circuit evaluation
(such as "all-of" and "any-of") 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.

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, as
     follows: if the test is true, the first command 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" {
                      toss;
                 } else if  header ("subject") contains ("$$$") {
                      toss;
                 } 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                                                       [Page 8]

Internet Draft                   Sieve                          May 1997


3.2. Require


Syntax:     require <extension-name>

     Require SHOULD be declared in a user script before an extension is
used.  It instructs the evaluator that the extension named extension-
name, supplied as a string, MUST be present in order to allow further
processing.  If the string specifies an extension that the evaluating
mechanism supports, then processing continues.  Otherwise, an error has
been encountered, and the script should not be evaluated.

Require is intended to indicate that a script needs an extension not
described in this document, or a feature that is not mandatory.

The following example will fail on any server that  does  not  implement
the extension known as DWIM.


Example:    require "dwim";
            if header ("subject") contains-nocase ("the secret message")
            {
                 dwim blurdybloop body;
            } stop


OPEN:   I have serious concerns with require; it makes it impossible to
        separate parsing from evaluation, and introduces some awkward
        cases.  For instance, a script "if size under 1 { require "foo";
        do_foo; } else {... }" Even if the test will never happen, this
        require will prevent the script from working.  Just support
        seems to make more sense.

4. Actions

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

4.1. Action bounce


Syntax:     bounce <reason-string>

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

Example:    if header "from" contains "coyote@anvil.org" {



Showalter                                                       [Page 9]

Internet Draft                   Sieve                          May 1997


                 bounce "I am not taking mail from you, and I don't want
                 your birdseed, either!";
            }

A bounce message SHOULD 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 SHOULD 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 bounce prevent all other actions from taking affect?]

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 and require tests.

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

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






Showalter                                                      [Page 10]

Internet Draft                   Sieve                          May 1997


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 simply 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

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


4.5. Action reply


     Syntax:     reply <message>

          The "reply" action is used to generate a form letter reply to
     the original sender.  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).



Showalter                                                      [Page 11]

Internet Draft                   Sieve                          May 1997


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


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
                 Sunday.  I have thrown your message out.  Please resend
                 it later.
                 .
                 ; toss;

4.7. Action toss


     Syntax:     toss

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

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

          While an important part of this language, "toss" 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 "toss".  In order to protect



Showalter                                                      [Page 12]

Internet Draft                   Sieve                          May 1997


     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. all-of


     Syntax:     all-of ( <test> , <test> , ... <test> )

          The all-of test preforms a logical AND on the  tests  supplied
     to it.

     Example:    all-of (false, false)  =>   false
                 all-of (false, true)   =>   false
                 all-of (true, true)    =>   true

5.2. any-of


     Syntax:     any-of ( <test> , <test> , ... <test> )

          The any-of test preforms a logical OR on the tests supplied to
     it.

     Example:    any-of (false, false)  =>   false
                 any-of (false, true)   =>   true
                 any-of (true, true)    =>   true

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



Showalter                                                      [Page 13]

Internet Draft                   Sieve                          May 1997


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

5.4. false


     Syntax:     false

          The "false" test always evaluates to false.

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

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


     Syntax:     not <test>

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

5.7. size


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



Showalter                                                      [Page 14]

Internet Draft                   Sieve                          May 1997


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


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

5.9. 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
     insure 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



Showalter                                                      [Page 15]

Internet Draft                   Sieve                          May 1997


     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 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
     "require" and "support" conditionals, 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.



Showalter                                                      [Page 16]

Internet Draft                   Sieve                          May 1997


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.


     (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


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



Showalter                                                      [Page 17]

Internet Draft                   Sieve                          May 1997


     overlaps an earlier rule, the rule which is listed earlier MUST
     take priority.  [If you see any of these, please let me know]

     action = toss / fileinto / forward / bounce / reply / stop

     address = string
             ;; any legal [IMAIL] address

     any-of = "any-of" test-list

     all-of = "all-of" test-list

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

     bounce = bounce WSP string
             ;; string is the reason contained in the bounce message.

     control-structure = if

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

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

     comment = "#" *CHAR CRLF

     comparator = octet

     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

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

     multi-line = "text:" [WSP] CRLF "." CRLF
             ;; Note when used,
             ;; a leading ".." on a line is mapped to ".".

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




Showalter                                                      [Page 18]

Internet Draft                   Sieve                          May 1997


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

     quoted-string = <"> *CHAR <">
             ;; \" inside a string maps to "
             ;; \\ inside a string maps to \
             ;; All other escape sequences must be preserved.
             ;; Note that newlines and other weird characters
             ;; are all allowed strings.

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

     stop = "stop"

     string = quoted-string / multi-line

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

     test = [WSP] (any-of / all-of / exists / false / header /
         not / size) [WSP]

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

     WSP = 1*(SPACE / CRLF / tab) / 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
     reasonably 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 bounce,
     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 "bounce" 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



Showalter                                                      [Page 19]

Internet Draft                   Sieve                          May 1997


     from this?  Say I do three replies; which ones take effect when the
     limit is 1? 2? 0?]

     Several commands, such as "toss", "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                                                      [Page 20]

Internet Draft                   Sieve                          May 1997


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.






















Showalter                                                      [Page 21]


Html markup produced by rfcmarkup 1.108, available from http://tools.ietf.org/tools/rfcmarkup/