argument exist within the message. All of the headers must exist or
the test is false.
The following example throws out mail that doesn't have a From header
and a Date header.
Example: if not exists ["From","Date"] {
discard;
}
5.6. Test false
Syntax: false
The "false" test always evaluates to false.
5.7. Test header
Syntax: header [COMPARATOR] [MATCH-TYPE]
<header-names: string-list> <key-list: string-list>
The "header" test evaluates to true if any header name matches any
key. The type of match is specified by the optional match argument,
which defaults to ":is" if not specified, as specified in section
2.6.
Like address and envelope, this test returns true if any combination
of the string-list and key-list arguments match.
If a header listed in the header-names 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 :is ["X-Caffeine"] [""] => false
header :contains ["X-Caffeine"] [""] => true
5.8. Test not
Syntax: not <test>
The "not" test takes some other test as an argument, and yields the
opposite result. "not false" evaluates to "true" and "not true"
evaluates to "false".
5.9. Test size
Syntax: size <":over" / ":under"> <limit: number>
The "size" test deals with the size of a message. It takes either a
tagged argument of ":over" or ":under", followed by a number
representing the size of the message.
If the argument is ":over", and the size of the message is greater
than the number provided, the test is true; otherwise, it is false.
If the argument is ":under", and the size of the message is less than
the number provided, the test is true; otherwise, it is false.
Exactly one of ":over" or ":under" must be specified, and anything
else is an error.
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.
Note that for a message that is exactly 4,000 octets, the message is
neither ":over" 4000 octets or ":under" 4000 octets.
5.10. Test true
Syntax: true
The "true" test always evaluates to true.
6. 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 capability 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.
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 the server does not support.
Extensions MUST state how they interact with constraints defined in
section 2.10, e.g., whether they cancel the implicit keep, and which
actions they are compatible and incompatible with.
6.1. Capability String
Capability strings are typically short strings describing what
capabilities are supported by the server.
Capability strings beginning with "vnd." represent vendor-defined
extensions. Such extensions are not defined by Internet standards or
RFCs, but are still registered with IANA in order to prevent
conflicts. Extensions starting with "vnd." SHOULD be followed by the
name of the vendor and product, such as "vnd.acme.rocket-sled".
The following capability strings are defined by this document:
envelope The string "envelope" indicates that the implementation
supports the "envelope" command.
fileinto The string "fileinto" indicates that the implementation
supports the "fileinto" command.
reject The string "reject" indicates that the implementation
supports the "reject" command.
comparator- The string "comparator-elbonia" is provided if the
implementation supports the "elbonia" comparator.
Therefore, all implementations have at least the
"comparator-i;octet" and "comparator-i;ascii-casemap"
capabilities. However, these comparators may be used
without being declared with require.
6.2. IANA Considerations
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.
6.2.1. Template for Capability Registrations
The following template is to be used for registering new Sieve
extensions with IANA.
To: iana@iana.org
Subject: Registration of new Sieve extension
Capability name:
Capability keyword:
Capability arguments:
Standards Track/IESG-approved experimental RFCnumber:
Person and email address to contact for further information:
6.2.2. Initial Capability Registrations
The following are to be added to the IANA registry for Sieve
extensions as the initial contents of the capability registry.
Capability name: fileinto
Capability keyword: fileinto
Capability arguments: fileinto <folder: string>
Standards Track/IESG-approved experimental RFCnumber:
RFC3028 (Sieve base spec)
Person and email address to contact for further information:
Tim Showalter
tjs@mirapoint.com
Capability name: reject
Capability keyword: reject
Capability arguments: reject <reason: string>
Standards Track/IESG-approved experimental RFCnumber:
RFC3028 (Sieve base spec)
Person and email address to contact for further information:
Tim Showalter
tjs@mirapoint.com
Capability name: envelope
Capability keyword: envelope
Capability arguments:
envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
<envelope-part: string-list> <key-list: string-list>
Standards Track/IESG-approved experimental RFCnumber:
RFC3028 (Sieve base spec)
Person and email address to contact for further information:
Tim Showalter
tjs@mirapoint.com
Capability name: comparator-*
Capability keyword:
comparator-* (anything starting with "comparator-")
Capability arguments: (none)
Standards Track/IESG-approved experimental RFCnumber:
RFC3028, Sieve, by reference of
RFC2244, Application Configuration Access Protocol
Person and email address to contact for further information:
Tim Showalter
tjs@mirapoint.com
6.3. Capability Transport
As the range of mail systems that this document is intended to apply
to is quite varied, 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
property that the implementation can advertise the complete set of
extensions that it supports.
7. Transmission
The MIME type for a Sieve script is "application/sieve".
The registration of this type for RFC2048 requirements is as
follows:
Subject: Registration of MIME media type application/sieve
MIME media type name: application
MIME subtype name: sieve
Required parameters: none
Optional parameters: none
Encoding considerations: Most sieve scripts will be textual,
written in UTF-8. When non-7bit characters are used,
quoted-printable is appropriate for transport systems
that require 7bit encoding.
Security considerations: Discussed in section 10 of RFC3028.
Interoperability considerations: Discussed in section 2.10.5
of RFC3028.
Published specification: RFC3028.
Applications which use this media type: sieve-enabled mail servers
Additional information:
Magic number(s):
File extension(s): .siv
Macintosh File Type Code(s):
Person & email address to contact for further information:
See the discussion list at ietf-mta-filters@imc.org.
Intended usage:
COMMON
Author/Change controller:
See Author information in RFC3028.
8. Parsing
The Sieve grammar is separated into tokens and a separate grammar as
most programming languages are.
8.1. Lexical Tokens
Sieve scripts are encoded in UTF-8. The following assumes a valid
UTF-8 encoding; special characters in Sieve scripts are all ASCII.
The following are tokens in Sieve:
- identifiers
- tags
- numbers
- quoted strings
- multi-line strings
- other separators
Blanks, horizontal tabs, CRLFs, and comments ("white space") are
ignored except as they separate tokens. Some white space is required
to separate otherwise adjacent tokens and in specific places in the
multi-line strings.
The other separators are single individual characters, and are
mentioned explicitly in the grammar.
The lexical structure of sieve is defined in the following BNF (as
described in [ABNF]):
bracket-comment = "/*" *(CHAR-NOT-STAR / ("*" CHAR-NOT-SLASH)) "*/"
;; No */ allowed inside a comment.
;; (No * is allowed unless it is the last character,
;; or unless it is followed by a character that isn't a
;; slash.)
CHAR-NOT-DOT = (%x01-09 / %x0b-0c / %x0e-2d / %x2f-ff)
;; no dots, no CRLFs
CHAR-NOT-CRLF = (%x01-09 / %x0b-0c / %x0e-ff)
CHAR-NOT-SLASH = (%x00-57 / %x58-ff)
CHAR-NOT-STAR = (%x00-51 / %x53-ff)
comment = bracket-comment / hash-comment
hash-comment = ( "#" *CHAR-NOT-CRLF CRLF )
identifier = (ALPHA / "_") *(ALPHA DIGIT "_")
tag = ":" identifier
number = 1*DIGIT [QUANTIFIER]
QUANTIFIER = "K" / "M" / "G"
quoted-string = DQUOTE *CHAR DQUOTE
;; in general, \ CHAR inside a string maps to CHAR
;; so \" maps to " and \\ maps to \
;; note that newlines and other characters are all allowed
;; strings
multi-line = "text:" *(SP / HTAB) (hash-comment / CRLF)
*(multi-line-literal / multi-line-dotstuff)
"." CRLF
multi-line-literal = [CHAR-NOT-DOT *CHAR-NOT-CRLF] CRLF
multi-line-dotstuff = "." 1*CHAR-NOT-CRLF CRLF
;; A line containing only "." ends the multi-line.
;; Remove a leading '.' if followed by another '.'.
white-space = 1*(SP / CRLF / HTAB) / comment
8.2. Grammar
The following is the grammar of Sieve after it has been lexically
interpreted. No white space or comments appear below. The start
symbol is "start".
argument = string-list / number / tag
arguments = *argument [test / test-list]
block = "{" commands "}"
command = identifier arguments ( ";" / block )
commands = *command
start = commands
string = quoted-string / multi-line
string-list = "[" string *("," string) "]" / string ;; if
there is only a single string, the brackets are optional
test = identifier arguments
test-list = "(" test *("," test) ")"
9. Extended Example
The following is an extended example of a Sieve script. Note that it
does not make use of the implicit keep.
#
# Example Sieve Filter
# Declare any optional features or extension used by the script
#
require ["fileinto", "reject"];
#
# Reject any large messages (note that the four leading dots get
# "stuffed" to three)
#
if size :over 1M
{
reject text:
Please do not send me large attachments.
Put your file on a server and send me the URL.
Thank you.
.... Fred
.
;
stop;
}
#
# Handle messages from known mailing lists
# Move messages from IETF filter discussion list to filter folder
#
if header :is "Sender" "owner-ietf-mta-filters@imc.org"
{
fileinto "filter"; # move to "filter" folder
}
#
# Keep all messages to or from people in my company
#
elsif address :domain :is ["From", "To"] "example.com"
{
keep; # keep in "In" folder
}
#
# Try and catch unsolicited email. If a message is not to me,
# or it contains a subject known to be spam, file it away.
#
elsif anyof (not address :all :contains
["To", "Cc", "Bcc"] "me@example.com",
header :matches "subject"
["*make*money*fast*", "*university*dipl*mas*"])
{
# If message header does not contain my address,
# it's from a list.
fileinto "spam"; # move to "spam" folder
}
else
{
# Move all other (non-company) mail to "personal"
# folder.
fileinto "personal";
}
10. Security Considerations
Users must get their mail. It is imperative that whatever method
implementations use to store the user-defined filtering scripts be
secure.
It is equally important that implementations sanity-check the user's
scripts, and not allow users to create on-demand mailbombs. For
instance, an implementation that allows a user to reject or redirect
multiple times to a single message might also allow a user to create
a mailbomb triggered by mail from a specific user. Site- or
implementation-defined limits on actions are useful for this.
Several commands, such as "discard", "redirect", and "fileinto" allow
for actions to be taken that are potentially very dangerous.
Implementations SHOULD take measures to prevent languages from
looping.
11. Acknowledgments
I am very thankful to Chris Newman for his support and his ABNF
syntax checker, to John Myers and Steve Hole for outlining the
requirements for the original drafts, to Larry Greenfield for nagging
me about the grammar and finally fixing it, to Greg Sereda for
repeatedly fixing and providing examples, to Ned Freed for fixing
everything else, to Rob Earhart for an early implementation and a
great deal of help, and to Randall Gellens for endless amounts of
proofreading. I am grateful to Carnegie Mellon University where most
of the work on this document was done. I am also indebted to all of
the readers of the ietf-mta-filters@imc.org mailing list.
12. Author's Address
Tim Showalter
Mirapoint, Inc.
909 Hermosa Court
Sunnyvale, CA 94085
EMail: tjs@mirapoint.com
13. References
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC2234, November 1997.
[ACAP] Newman, C. and J. G. Myers, "ACAP -- Application
Configuration Access Protocol", RFC2244, November 1997.
[BINARY-SI] "Standard IEC 60027-2: Letter symbols to be used in
electrical technology - Part 2: Telecommunications and
electronics", January 1999.
[DSN] Moore, K. and G. Vaudreuil, "An Extensible Message Format
for Delivery Status Notifications", RFC1894, January
1996.
[FLAMES] Borenstein, N, and C. Thyberg, "Power, Ease of Use, and
Cooperative Work in a Practical Multimedia Message
System", Int. J. of Man-Machine Studies, April, 1991.
Reprinted in Computer-Supported Cooperative Work and
Groupware, Saul Greenberg, editor, Harcourt Brace
Jovanovich, 1991. Reprinted in Readings in Groupware and
Computer-Supported Cooperative Work, Ronald Baecker,
editor, Morgan Kaufmann, 1993.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC2119, March 1997.
[IMAP] Crispin, M., "Internet Message Access Protocol - version
4rev1", RFC2060, December 1996.
[IMAIL] Crocker, D., "Standard for the Format of ARPA Internet
Text Messages", STD 11, RFC822, August 1982.
[MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC2045, November 1996.
[MDN] Fajman, R., "An Extensible Message Format for Message
Disposition Notifications", RFC2298, March 1998.
[RFC1123] Braden, R., "Requirements for Internet Hosts --
Application and Support", STD 3, RFC1123, November 1989.
[SMTP] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC
821, August 1982.
[UTF-8] Yergeau, F., "UTF-8, a transformation format of Unicode
and ISO 10646", RFC2044, October 1996.
14. Full Copyright Statement
Copyright (C) The Internet Society (2001). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFCEditor function is currently provided by the
Internet Society.