WDIFF

draft-showalter-sieve-00.txt --> draft-showalter-sieve-01.txt

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

SIEVE: (12/97)

Sieve: A Mail Filtering Language

Status of this Memo 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.

Mail filtering systems are widely used for a variety of reasons,
including organization of messages (filtering out mailing list
messages for separate reading). They are becoming increasingly
useful in avoiding unsolicited mail. Existing languages are not
consistant across client, server, or operating system, and are
frequently difficult for users to use. This language It is
not tied to any particular system or mail architecture and 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.
servers, and has no variables, loops, or ability to shell out to
external programs.

Showalter [Page 1]

draft-showalter-sieve-00.txt SIEVE April i]

Internet Draft Sieve May 1997

Table of Contents

This

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 is content-free.
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 2]

draft-showalter-sieve-00.txt SIEVE April 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. Unfinished 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 Weaknesses 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 usefulness 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 "subaddressing" "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.

The newline problem is relatively, but not completely, solved. We'll
be arguing this until the end of time.

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.

The formal grammar is not complete, and needs

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 revised okay, but probably isn't.

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

The error-handling clauses of ABNF, whatever its final state is. 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.

An "include" command
Please let me know if there is not included, but has been suggested for an
extension.

I need to run a spelling checker on this document.

I hate nroff.

0.2. good way to clean up the wording.

0.3. Open Issues

Do "fileinto" commands need

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 moved cleaner
to me).

Comma is mandatory in any-of/all-of but forbidden in a separate document?

1. Introduction

There are a number list of reasons
strings it should be required in both. This needs to use a filtering system. Mail
traffic for most users has been increasing due both be fixed.
I'm clinging to increased

Showalter [Page 3]

draft-showalter-sieve-00.txt SIEVE April 1997

usage of e-mail, the emergence status quo trying to fix the rest of unsolicited email as the
problems at the moment.

Should there be a form of
advertising, and increased usage of mailing lists.

This language is offered in order way to try and provide specify headers transmitted by reply?
Perhaps a standard
language separate command, since there are probably sites that can be used are
going to create filters for e-mail. It be really paranoid about what headers get sent.

In the event that there is not
tied to any particular operating 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 reasonably bulletproof safe server-side filtering system. The language is not Turing-complete, and provides no way to
write a loop or a function, nor are variables are provided. The
intention is to make it impossible for users to do anything more
complex (and dangerous) than write simple mail filters. 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. delivery, when the message is finally moved to the user-
accessible mailbox. In systems where the MTA does final delivery --
IMAP4 delivery,
such as and traditional UNIX mail, for instance, it 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 mailboxes,
as is the case under POP3), POP3, the MUA must do filtering into
local filters.

Experience at Carnegie Mellon has shown that if 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 users
others did not make use of the Andrew system's FLAMES filtering
language due to difficulty in programming it. Due setting it up.

Because of the expectation that users will make use of filtering if
it is offered and easy to this expectation, use, this language has been made simple
enough to allow many users to make use of it. 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

Line

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 an a test, action, or conditional control structure has a line
labeled "Syntax:". This line describes the arguments each command requires. 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 "]").
The However, the formal
grammar for these commands is described in section 10 and is the authoritative
reference on how to construct these commands.

Showalter [Page 4]

draft-showalter-sieve-00.txt SIEVE April 1997

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

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.dementia.org coyote@anvil.org
To: roadrunner@birdseed.thekeep.org roadrunner@birdseed.org
Subject: I have a present for you

Look, I'm sorry about the whole anvil thing, but and I can 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, and 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@znic.net b1ff@de.res.frobnitzm.edu
To: rube@znic.net 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

Showalter [Page 5]

draft-showalter-sieve-00.txt SIEVE April 1997 control structure is taken.

2.2. Whitespace

Whitespace is used to separate commands. Whitespace is made up of
tabs, newlines (which can be CR, LF, (CRLF, never just CR or both), 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 newline. CRLF.

Example: if size over 100K then { # this is a comment
toss
endif
toss;
}

2.4. Numbers

Numbers are normally given as ordinary decimal numbers. However, those
numbers that have a tendency to be fairly large, such as message
sizes, 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 power-of-two-based

Showalter [Page 3]

Internet Draft Sieve May 1997

versions of SI units that computers fre-
quently 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.

Numbers are limited to 32

Implementations MUST provide 31 bits by this specification.

[OPEN: If of magnitude in numbers, but
may provide more.

Negative, fractional, and decimal numbers are limited to 32 bits, gigabit-sized
numbers probably aren't very useful. Should I remove
them?] not permitted by this
draft.

2.5. Strings

Scripts involve large numbers of strings. Typically,
short quoted strings suffice 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. 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 two-
character sequence represents a

Showalter [Page 6]

draft-showalter-sieve-00.txt SIEVE April 1997 single backslash or double-quote
within the string. [If
there are missing words in the paragraph, I had problems
with nroff; please point it out to me.] string, respectively.

For entering larger amounts of text, such as an email message, a longer
multi-line form is allowed, known as a "user-
message". allowed. It starts with the keyword "message" "text:",
followed by a CRLF, and ends with the sequence of a newline, CRLF, a single
period, and another newline. Any line that begins with ".." is con-
sidered CRLF. In order to allow the message to begin
lines with ".".

XXX this example needs formatting work 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")) then
fileinto "INBOX" {
keep;
} else {
reply message 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.
, <-- XXX should
.
;
}

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 "." \.
endif

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

[OPEN ISSUE: Is this section necessary or useful?]

Headers are a subset of strings. In the Internet Message Specifica-
tion
Specification [IMAIL], each header line is allowed to have
whitespace nearly anywhere in the line, including after the field
name and before 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
subsequent colon. Thus, the lines "From: acm@andrew.cmu.edu" other is
equivalent to "From : acm@andrew.cmu.edu". Within a SIEVE
script, header names are never considered to have spaces. Only the
"From" in value.
Commands that utilize these comparisons, generally of the above headers form
"<value> <match-keyword> <key>", must be sure to differentiate
which is considered which.

2.6.2. Comparators

In order to be there. While a
header can be listed as "From " within a header list (say, allow for character set-independent matches, the
"header" command) such usage is absurd. The following colon is never
specified; match
keyword may be coupled with a header "From:", as well as comparator name. Comparators are
described for [ACAP]; a header ":From", registry is
guaranteed never to happen within a valid header.

2.5.2. Addresses

Showalter [Page 7]

draft-showalter-sieve-00.txt SIEVE April 1997

[OPEN ISSUE: Is this section necessary or useful?]

A number of commands call defined for email addresses, ACAP, and this
draft borrows that registry.

All implementations MUST support the octet comparator, which are also a sub-
set of strings. These addresses must be compliant simply
compares one octet with [IMAIL].
Implementations the next. If left unspecified, the
comparator is octet.

If an implementation supports a comparator "elbonia", it MUST insure
provide the addresses are syntactically valid, capability "comparator-elbonia" for support and need require
commands.

Some comparators may not insure be usable with substring matches; that is,
they are actually deliverable. 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 mail-
box,
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 then toss endif

then toss;

In cases like this, the "normal" "keep" action is taken. The "normal" "keep" action
is defined to be the action that is taken normally, such as in a situation where the user
does no filtering. Under most situations, the normal action
is to file into the user's main mailbox (such as "INBOX" For instance, under IMAP). an IMAP-based system, this
implies filing into INBOX.

Implementations define the specific meanings of actions. Implementa-
tions may
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 it more impor-
tant, order of operation
important, all arguments to rules MUST be evaluated in left-to-right
order. Those operations that may can implement short-circuit evaluation
(such as the "all-of" and "any-of" operators, which preform logical "and" and "or"
operations, respectively) SHOULD "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> then <commands>
[elsif <elsif-test> then <elsif-commands> [elsif ...]] <command> [else <else-commands>]
endif <command>]

The "if" control structure is borrowed from any number of
programming languages. It is evaluated in the usual way, as
follows: if <test> the test is true, then <commands> are evaluated. If an elsif keyword exists,
and <next-test> the first command supplied is true, then <elsif-commands> are
evaluated. Any

Showalter [Page 8]

draft-showalter-sieve-00.txt SIEVE April 1997

number of elsif cases may be included, and are evaluated serially. If <test> the test is false and an else keyword follows the <elsif-test>s are false as well, then if
block, the
<else-commands> are second command is evaluated. The "if" block is terminated with an
"endif" keyword, which is required. 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") "from" contains ("coyote") then
toss
elsif "coyote" {
toss;
} else if header ("subject") contains ("$$$")
then toss {
toss;
} else fileinto "INBOX"
endif "INBOX";

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

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

Example: if header ("") ("From") contains ("") then ("coyote") {
forward "acm@andrew.cmu.edu";
elsif "acm@frobnitzm.edu";
} else if header ("Subject") "Subject" contains ("$$$") then "$$$" {
forward "service@andrew.cmu.edu"; "postmaster@frobnitzm.edu";
} else
forward "postman@andrew.cmu.edu";
endif "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, 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. Other-
wise, Otherwise, an error has
been encountered, and the script should not be evaluated.

Require is intended to demand the use of indicate that a script needs an extension not present
described in this document. 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.

Showalter [Page 9]

draft-showalter-sieve-00.txt SIEVE April 1997

Example: require "dwim";
if header ("subject") contains-nocase ("the secret message") then
{
dwim blurdybloop body;
endif
} 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: normal,
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") "from" contains ("coyote@anvil.dementia.org")
then "coyote@anvil.org" {

Showalter [Page 9]

Internet Draft Sieve May 1997

bounce "I am not taking mail 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 you, you killer!"
endif taking affect?]

4.2. Action fileinto

Syntax: fileinto <folder>

[OPEN ISSUE: I could be talked into making fileinto optional for POP3
server agents that wanted to simply throw mail out and then do user
filtering on the client.]

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

A simple script can be used for forwarding:

Example: forward "tjs@andrew.cmu.edu"

Showalter [Page 10]

draft-showalter-sieve-00.txt SIEVE April 1997 "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 normal keep

Syntax: normal keep

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

Syntax:

Example: if size under 1M then normal keep; else toss 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.
The multi-line <user-message> production described in the Formal
Grammar section is intended for this purpose. In the following exam-
ple, example, any message over larger than 500K (or 512,000
(524288 octets) would be thrown out; replied to with a message explaining that
it was rejected; otherwise, the message would be filed into INBOX. INBOX
(by default).

Showalter [Page 11]

Internet Draft Sieve May 1997

Example: if size over 500K {
reply message text:
Your message was unnecessarily large.
I reject all large messages; you will need to contact me
directly.
toss
endif

OPEN: Specify headers transmitted?

OPEN: Specify way to do vacation? A previous version of this had a
-days switch to specify number of days unnecessarily large. I reject
all large messages; if you need to do send me a new reply. 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 normal keep action is taken.

In the following script, if the mail is from the address
"wall@andrew.cmu.edu"
"boss@frobnitzm.edu" it is forwarded to "tjs@xanadu.wv.us"; other-
wise "pleeb@frobnitzm.edu";
otherwise the mail receives a reply, and is thrown out.

Example: if (header header ("from") matches ("wall@andrew.cmu.edu"))
then ("boss@frobnitzm.edu") {
forward "tjs@xanadu.wv.us"; stop
endif "pleeb@xanadu.wv.us";
stop;
} reply "I'm text:
I'm on vacation and not taking any messages; try after
Sunday. I have thrown your message out. Please resend
it later." later.
.
; toss

Showalter [Page 11]

draft-showalter-sieve-00.txt SIEVE April 1997 toss;

4.7. Action toss

Syntax: toss

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

Example: if header ("from") contains ("wall@andrew.cmu.edu") then
toss endif ("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 condi-
tional
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.

The comma in between tests is optional.

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

5.2. any-of

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

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

The comma in between tests is optional.

Example: all-of (false any-of (false, false) => false
all-of (false
any-of (false, true) => true
all-of
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>
<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 12]

draft-showalter-sieve-00.txt SIEVE April 13]

Internet Draft Sieve May 1997

Example: if not exists ("From" "Date" "Subject" "To" "Message-ID")
then
toss
endif "Date") {
toss;
}

5.4. false

Syntax: false

The "false" test always evaluates to false.

5.5. header

Syntax: header <header-name-list>
<"contains"/"is"/"matches"/"contains-nocase" / "is-
nocase"/"matches-nocase"> <key-list>

The "header" test evaluates to true if the header name matches key.
How the match is done is described by the second argument. The basic
matching forms are case sensitive. Each matching form has a
corresponding form ending in "-nocase"; these are not case sensitive.

All matchings on header field names MUST be done in a case insensi-
tive manner.

The "is" argument demands that one of the fields of the headers
listed in header-name-list can be found in the key-list. It requires
an absolute match. It is true if there are repeated arguments in the
header-name-list or the key-list.

The "contains" argument demands that one of the values of header

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

The "header" test evaluates to true if the headers
named in header-name-list partially any header name
matches one of any key. How the values in
key-list. It match is true if there are repeated arguments in done is described by the header-
name-list or second
argument, which is one of the key-list. The string "" is contained comparison arguments discussed
in any header
that exists. section 2.6. The "matches" first argument demands that one of to header, the fields header-name-
list, is a list of the 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 matches a "glob" pattern described by one
of argument exists, it
contains the members of key-list. A glob pattern null key (""). However, if the named header is a UNIX-style filename
glob, which has not
present, it does not contain the following special characters:

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

The string "" matches all strings that exist. That is, null key. So if a message

Showalter [Page 13]

draft-showalter-sieve-00.txt SIEVE April 1997

contains the line [XXX formatted improperly]

X-Blurdybloop: death to the heathens
contained the header

X-Caffeine: C8H10N4O2

these tests on that header evaluate as follows:

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

5.6. not

Syntax: not <test>

The "not" test takes some other test, test as an argument, and returns
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 second first argument is "over" and the size of the
message is strictly greater than the number of octets specified as
limit. If the second 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.

Syntax:

Example: if support "black-magic" then

Showalter [Page 14]

draft-showalter-sieve-00.txt SIEVE April 1997 {
black-magic ("kgb@andrew.cmu.edu")
endif ("zork@frobnitzm.edu");
}

5.9. true

Syntax: true

The "true" test is always true.

6. Errors in Processing a Script

In any sort of programming language, even a very simple one, errors are inevitable. In this case, users Users are
expected to make errors --
even if errors, and changes in the actual script is machine-generated, mailbox rights might environment, such as a
change to disallow users from writing to in a mailbox, user's rights on a mailbox may no
longer exist, or mailbox, can cause a variety of other problems. script to fail.
It is imperative that mail be allowed to get through in any case.

If an error is found in a script, an implementation MUST make an
attempt to resolve the condition. through.

Implementations SHOULD check a script before it is run in order to
insure that it is valid. Imple-
mentations 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

Implementations found.

In an implementation that allow allows for a script to be checked when it
is turned over to the server, the script to can be checked for syntax errors in advance of mail receipt (i.e., client-based filtering, or
server-based filtering with a submission protocol aware of this
language)
before it is submitted. Implementations SHOULD notify the user of
the error and refuse to accept a syntactically invalid script, script or
one that makes use of extensions that the server does not report.

Implementations that allow server-based filtering (i.e., as part of
an IMAP server) MUST allow mail to be filed normally (i.e., for IMAP,
into the user's INBOX) without filtering in
case of a syntax error in the script, and
MUST notify the user of an error in some form (such as sending the
user a mail message notifying them of the error). script. Implementations
SHOULD MUST avoid over-sending error
sending multiple messages to describing the user's mailbox. 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 INBOX. the user's main mailbox. Implementations MUST NOT
discard mail.

Showalter [Page 15]

draft-showalter-sieve-00.txt SIEVE April 1997 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; an
extension negotiation mechanism is not defined by
this document.

For the formal grammar, an extension SHOULD document does not define one a way to discover the list of
extensions supported by the symbols
beginning with "extension-". server.

Any extensions to this language MUST define a unique string that
describes uniquely
identifies that extension. Such strings SHOULD include If a new version
number. 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 "sup-
port" "support" conditionals, which mandates that script
requires the use of that extension.

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

7.1. Capability Mechanism

[A brief description of 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 will be included here.] "fileinto" indicates the implementation
supports filing into mailboxes.

Showalter [Page 16]

Internet Draft Sieve May 1997

7.2. Registry

[A registration mechanism will be included here.]

7.3. Capability Transport

[A brief description

In order to provide a standard set of what is required for extensions, a capability transport
will be defined here. Transports will registry is
provided by IANA. Capability names may be defined in separate docu-
ments.]

8. Transmission

This document does not define registered on a method first-
come, first-served basis. Extensions designed for accessing stored scripts
at run-time or as they are written, nor does it define a character
set encoding 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 scripts.

If further information:

7.3. Capability Transport

As the method range of handing mail systems that this draft is intended to apply
to is quite large, a script off method of advertising which capabilities an
implementation supports is difficult due to the server allows for MIME-
typing wide range of data as described in [MIME] and
possible implementations. Such a mechanism, however, should have
the data is encoded in
UTF-8 as described in [UTF-8], 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
XXX/XXX.

Implementations SHOULD check a script before it is run "application/sieve". Scripts
are encoded 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 pri-
mary mailbox.

Showalter [Page 16]

draft-showalter-sieve-00.txt SIEVE April 1997 UTF-8 during transmission.

9. Acknowledgments

10. Formal Grammar

The grammar used in this section is the same as the ABNF described
in
[ABNF] with one exception: the delimiter used with "#" is any amount
of whitespace (that is, CR, LF, spaces, and tabs), as described by
the "WSP" terminal, followed by a single comma, and additional whi-
tespace. Two commas without something in between them is a protocol
error, and is prohibited. [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 /
extension-action

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

any-of = "any-of" WSP "(" [WSP] #(condition) [WSP] ")" test-list

all-of = "all-of" WSP "(" test-list

block = "{" [WSP] #(condition) commands [WSP] ")"

big-number = number [ UNIT ] "}"
;; C-style block

bounce = "bounce" bounce WSP string
;; string is a text message to be sent with the bounce as the
;; reason contained in the bounce message.

control-structure = if / extension-control-structure

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

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

comment = "#" *CHAR newline 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 "then" WSP commands WSP #("elsif" WSP
test WSP "then" WSP commands) [ "else" WSP commands WSP ]
"endif"
;; if <cond> then <commands>
;; [elsif <cond> then <commands> [elsif ...]]

Showalter [Page 17]

draft-showalter-sieve-00.txt SIEVE April 1997 command [ else command ]
;; [else <commands>] endif Commands are typically blocks.

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

match-keyword = "contains" ("contains" / "matches" / "is" / "contains-nocase" /
"contains-nocase" / "is-nocase"

newline "is") ["-" comparator]

multi-line = "text:" [WSP] CRLF / CR / LF
;; A "." CRLF
;; Note when used,
;; a leading ".." on a line is ALWAYS one newline. mapped to ".".

number = 1*DIGIT

or [QUANTIFIER]
;; quantifier is a multiplier (or bit shift)

Showalter [Page 18]

Internet Draft Sieve May 1997

QUANTIFIER = condition WSP "or" WSP condition "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 big-number number

stop = "stop"

string = quoted-string / user-message multi-line

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

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

UNIT = "K" / "M" / "G"
;; kilobytes, megabytes, or gigabytes

user-message

test-list = "message" [WSP] newline "." newline
;; note when used,
;; a CR that is not followed by an LF becomes a CRLF;
;; an LF that is not followed by a CR becomes a CRLF.
;; a leading .. on a line is mapped to . "(" [WSP] *(condition [WSP] "," [WSP])
condition [WSP] ")" [WSP]

WSP = " " 1*(SPACE / CR CRLF / LF tab) / tab comment
;; just whitespace

10. whitespace. anyplace this is allowed, a comment is
;; as well

11. Security Considerations

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

It is equally important that implementations sanity-check the
user's

Showalter [Page 18]

draft-showalter-sieve-00.txt SIEVE April 1997 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.

11.

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 19] 21]

----