Sieve mailbox extensions: The Sieve Mail-Filtering Language -- Extensions for Checking Mailbox Status and Accessing Mailbox Metadata
New Sieve tests that check whether a mailbox exists, read mailbox and server annotations, and create missing folders.
Melnikov, A., "The Sieve Mail-Filtering Language -- Extensions for Checking Mailbox Status and Accessing Mailbox Metadata", RFC 5490, DOI 10.17487/RFC5490, March 2009, <https://www.rfc-editor.org/info/rfc5490>.
@misc{rfc5490,
series = {Request for Comments},
number = 5490,
howpublished = {RFC 5490},
publisher = {RFC Editor},
doi = {10.17487/RFC5490},
url = {https://www.rfc-editor.org/info/rfc5490},
author = {A. Melnikov},
title = {{The Sieve Mail-Filtering Language -- Extensions for Checking Mailbox Status and Accessing Mailbox Metadata}},
pagetotal = 8,
year = 2009,
month = mar,
} RFC text
Contents
Network Working Group A. Melnikov
Request for Comments: 5490 Isode Limited
Category: Standards Track March 2009
The Sieve Mail-Filtering Language --
Extensions for Checking Mailbox Status and Accessing Mailbox Metadata
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Abstract
This memo defines an extension to the Sieve mail filtering language
(RFC 5228) for accessing mailbox and server annotations, checking for
mailbox existence, and controlling mailbox creation on "fileinto"
action.
Table of Contents
1. Introduction ....................................................2
2. Conventions Used in This Document ...............................2
3. "mailbox" and "mboxmetadata" Extensions .........................2
3.1. Test "mailboxexists" .......................................2
3.2. ":create" Argument to "fileinto" Command ...................3
3.3. Test "metadata" ............................................4
3.4. Test "metadataexists" ......................................4
4. "servermetadata" Extension ......................................5
4.1. Test "servermetadata" ......................................5
4.2. Test "servermetadataexists" ................................6
5. Security Considerations .........................................6
6. IANA Considerations .............................................7
7. Acknowledgements ................................................7
8. References ......................................................8
8.1. Normative References .......................................8
8.2. Informative References .....................................8
1. Introduction
This memo defines an extension to the Sieve mail filtering language
[SIEVE] for accessing mailbox and server annotations. This allows
for customization of the Sieve engine behaviour based on variables
set using [METADATA].
This document also defines an extension for checking for mailbox
existence and for controlling mailbox creation on "fileinto" action.
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [KEYWORDS].
Conventions for notations are as in [SIEVE] Section 1.1, including
the use of [ABNF].
This document is written with an assumption that readers are familiar
with the data model and terms defined in Section 3 of [METADATA].
3. "mailbox" and "mboxmetadata" Extensions
3.1. Test "mailboxexists"
Usage: mailboxexists <mailbox-names: string-list>
The "mailboxexists" test is true if all mailboxes listed in the
"mailbox-names" argument exist in the mailstore, and each allows the
user in whose context the Sieve script runs to "deliver" messages
into it. When the mailstore is an IMAP server, "delivery" of
messages is possible if:
a. the READ-WRITE response code is present for the mailbox (see
Section 7.1 of [IMAP]), if IMAP Access Control List (ACL)
[IMAPACL] is not supported by the server, or
b. the user has 'p' or 'i' rights for the mailbox (see Section 5.2
of [IMAPACL]).
Note that a successful "mailboxexists" test for a mailbox doesn't
necessarily mean that a "fileinto" action on this mailbox would
succeed. For example, the "fileinto" action might put user over
quota. The "mailboxexists" only verifies existence of the mailbox
and whether the user in whose context the Sieve script runs has
permissions to execute "fileinto" on it.
The capability string for use with the require command is "mailbox".
Example: The following example assumes that the Sieve engine also
supports "reject" [REJECT] and "fileinto" [SIEVE]. However, these
extensions are not required in order to implement the "mailbox"
extension.
require ["fileinto", "reject", "mailbox"];
if mailboxexists "Partners" {
fileinto "Partners";
} else {
reject "This message was not accepted by the Mailstore";
}
3.2. ":create" Argument to "fileinto" Command
Usage: fileinto [:create] <mailbox: string>
If the optional ":create" argument is specified with "fileinto", it
instructs the Sieve interpreter to create the specified mailbox, if
needed, before attempting to deliver the message into the specified
mailbox. If the mailbox already exists, this argument is ignored.
Failure to create the specified mailbox is considered to be an error.
The capability string for use with the ":create" parameter is
"mailbox".
3.3. Test "metadata"
Usage: metadata [MATCH-TYPE] [COMPARATOR]
<mailbox: string>
<annotation-name: string> <key-list: string-list>
This test retrieves the value of the mailbox annotation "annotation-
name" for the mailbox "mailbox" [METADATA]. The retrieved value is
compared to the "key-list". The test returns true if the annotation
exists and its value matches any of the keys.
The default match type is ":is" [SIEVE]. The default comparator is
"i;ascii-casemap" [SIEVE].
The capability string for use with the require command is
"mboxmetadata".
Annotations MUST be accessed with the permissions of the user in
whose context the Sieve script runs, and annotations starting with
the "/private" prefix MUST be those of the user in whose context the
Sieve script runs.
Example: The following example assumes that the Sieve engine also
supports the "vacation" [VACATION] extension. However, this
extension is not required in order to implement the "mboxmetadata"
extension.
require ["mboxmetadata", "vacation"];
if metadata :is "INBOX"
"/private/vendor/vendor.isode/auto-replies" "on" {
vacation text:
I'm away on holidays till March 2009.
Expect a delay.
.
}
3.4. Test "metadataexists"
Usage: metadataexists <mailbox: string> <annotation-names: string-
list>
The "metadataexists" test is true if all of the annotations listed in
the "annotation-names" argument exist (i.e., have non-NIL values) for
the specified mailbox.
The capability string for use with the require command is
"mboxmetadata".
4. "servermetadata" Extension
4.1. Test "servermetadata"
Usage: servermetadata [MATCH-TYPE] [COMPARATOR]
<annotation-name: string> <key-list: string-list>
This test retrieves the value of the server annotation "annotation-
name" [METADATA]. The retrieved value is compared to the "key-list".
The test returns true if the annotation exists and its value matches
any of the keys.
The default match type is ":is". The default comparator is "i;ascii-
casemap".
The capability string for use with the require command is
"servermetadata".
Annotations MUST be accessed with the permissions of the user in
whose context the Sieve script runs, and annotations starting with
the "/private" prefix MUST be those of the user in whose context the
Sieve script runs.
Example: The following example assumes that the Sieve engine also
supports "variables" [VARIABLES], "enotify" [NOTIFY], and "envelope"
[SIEVE] extensions. However, these extensions are not required in
order to implement the "servermetadata" extension.
require ["enotify", "servermetadata", "variables", "envelope"];
if servermetadata :matches
"/private/vendor/vendor.isode/notification-uri" "*" {
set "notif_uri" "${0}";
}
if not string :is "${notif_uri}" "none" {
# :matches is used to get the MAIL FROM address
if envelope :all :matches "from" "*" {
set "env_from" " [really: ${1}]";
}
# :matches is used to get the value of the Subject header
if header :matches "Subject" "*" {
set "subject" "${1}";
}
# :matches is used to get the address from the From header
if address :matches :all "from" "*" {
set "from_addr" "${1}";
}
notify :message "${from_addr}${env_from}: ${subject}"
"${notif_uri}";
}
4.2. Test "servermetadataexists"
Usage: servermetadataexists
<annotation-names: string-list>
The "servermetadataexists" test is true if all of the server
annotations listed in the "annotation-names" argument exist (i.e.,
have non-NIL values).
The capability string for use with the require command is
"servermetadata".
5. Security Considerations
Extensions defined in this document deliberately don't provide a way
to modify annotations.
A failure to retrieve data due to the server storing the annotations
being down or otherwise inaccessible may alter the result of Sieve
processing. So implementations SHOULD treat a temporary failure to
retrieve annotations in the same manner as a temporary failure to
retrieve a Sieve script. For example, if the Sieve script is stored
in the Lightweight Directory Access Protocol (LDAP) and the script
can't be retrieved when a message is processed, then the agent
performing Sieve processing can, for example, assume that the script
doesn't exist or delay message delivery until the script can be
retrieved successfully. Annotations should be treated as if they are
a part of the script itself, so a temporary failure to retrieve them
should be handled in the same way as a temporary failure to retrieve
the Sieve script itself.
Protocols/APIs used to retrieve annotations MUST provide at least the
same level of confidentiality as protocols/APIs used to retrieve
Sieve scripts. For example, if Sieve scripts are retrieved using
LDAP secured with Transport Layer Security (TLS) encryption, then the
protocol used to retrieve annotations must use a comparable mechanism
for providing connection confidentiality. In particular, the
protocol used to retrieve annotations must not be lacking encryption.
6. IANA Considerations
IANA has added the following registrations to the list of Sieve
extensions:
To: iana@iana.org
Subject: Registration of new Sieve extension
Capability name: mailbox
Description: adds test for checking for mailbox existence and a new
optional argument to fileinto for creating a mailbox
before attempting mail delivery.
RFC number: this RFC
Contact address:
The Sieve discussion list <ietf-mta-filters@imc.org>
Capability name: mboxmetadata
Description: adds tests for checking for mailbox metadata item
existence and for retrieving of a mailbox metadata
value.
RFC number: this RFC
Contact address:
The Sieve discussion list <ietf-mta-filters@imc.org>
Capability name: servermetadata
Description: adds tests for checking for server metadata item
existence and for retrieving of a server metadata
value.
RFC number: this RFC
Contact address:
The Sieve discussion list <ietf-mta-filters@imc.org>
7. Acknowledgements
Thanks to Cyrus Daboo for initial motivation for this document.
Thanks to Barry Leiba, Randall Gellens, and Aaron Stone for helpful
comments on this document.
The author also thanks the Open Mobile Alliance's Mobile Email
working group for providing a set of requirements for mobile devices,
guiding some of the extensions in this document.
8. References
8.1. Normative References
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[IMAP] Crispin, M., "Internet Message Access Protocol - Version
4rev1", RFC 3501, March 2003.
[IMAPACL] Melnikov, A., "IMAP4 Access Control List (ACL)
Extension", RFC 4314, December 2005.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[METADATA] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
February 2009.
[SIEVE] Guenther, P. and T. Showalter, "Sieve: An Email
Filtering Language", RFC 5228, January 2008.
8.2. Informative References
[NOTIFY] Melnikov, A., Leiba, B., Segmuller, W., and T. Martin,
"Sieve Email Filtering: Extension for Notifications",
RFC 5435, January 2009.
[REJECT] Stone, A., "Sieve Email Filtering: Reject and Extended
Reject Extensions", RFC 5429, March 2009.
[VACATION] Showalter, T. and N. Freed, "Sieve Email Filtering:
Vacation Extension", RFC 5230, January 2008.
[VARIABLES] Homme, K., "Sieve Email Filtering: Variables Extension",
RFC 5229, January 2008.
Author's Address
Alexey Melnikov
Isode Limited
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
EMail: Alexey.Melnikov@isode.com
AI ELI5
On this page
§1Introduction
This memo extends the Sieve mail filtering language from RFC 5228 so scripts can access mailbox and server annotations. This lets a Sieve engine's behavior be customized by values set using the IMAP METADATA extension in RFC 5464.
It also defines an extension for checking whether a mailbox exists and for controlling mailbox creation on the fileinto action. Readers are assumed to know the data model and terms in section 3 of RFC 5464. The author thanks the Open Mobile Alliance's Mobile Email working group for requirements from mobile devices that guided some of the extensions.
This note gives the mail-sorting helper a few new abilities, like peeking at notes attached to folders.
§2Checking and Creating Mailboxes
The mailboxexists test takes a list of mailbox names. It is true if all of them exist in the mailstore and each allows the user running the script to deliver messages into it. For an IMAP server, delivery is possible if the READ-WRITE response code is present (when the Access Control List extension is not supported), or the user has the 'p' or 'i' rights for the mailbox.
A true result does not guarantee that fileinto will succeed. For example, the user might be over quota. The test only checks existence and permission.
The :create argument to fileinto tells the interpreter to create the mailbox, if needed, before delivering. If the mailbox already exists the argument is ignored. Failure to create the mailbox is an error. Both features use the capability string mailbox.
The helper can ask, "Is there a folder called Partners?" and can also make the folder before putting a letter in it.
§3Mailbox Metadata Tests
The mboxmetadata capability adds two tests. metadata retrieves the value of a named annotation on a named mailbox and compares it to a list of keys. It is true if the annotation exists and its value matches any of the keys. The default match type is :is and the default comparator is i;ascii-casemap.
metadataexists takes a mailbox and a list of annotation names. It is true if all of the annotations exist, meaning they have non-NIL values.
Annotations MUST be accessed with the permissions of the user running the script, and annotations starting with /private MUST be those of that user.
In the RFC's example, a script checks the INBOX annotation /private/vendor/vendor.isode/auto-replies. If it equals on, the script sends a vacation reply.
Each folder can have little sticky notes. The helper can read a note, such as "auto-reply: on", and act on it.
§4Server Metadata Tests
The servermetadata capability works like the mailbox version but for annotations on the server as a whole. The servermetadata test retrieves a server annotation and compares it to a key list, with the same defaults (:is and i;ascii-casemap). The servermetadataexists test is true if all listed server annotations exist with non-NIL values.
The same permission rules apply: access uses the running user's permissions, and /private annotations belong to that user.
The RFC's example reads /private/vendor/vendor.isode/notification-uri into a variable, then, if it is not none, builds a notification message from the envelope sender, the Subject header and the From address. It combines this extension with the variables, enotify and envelope extensions, which are not required to implement this one.
Besides notes on folders, there can be notes on the whole mail server. The helper can read those too, for example to find where to send a notification.
§5Security Considerations
The extensions deliberately provide no way to modify annotations. A failure to retrieve annotations, such as the storing server being down, may change the result of Sieve processing. Implementations SHOULD treat a temporary failure to retrieve annotations the same way as a temporary failure to retrieve the Sieve script. Annotations should be treated as a part of the script itself.
Protocols and APIs used to retrieve annotations MUST provide at least the same level of confidentiality as those used to retrieve Sieve scripts. For example, if scripts come from LDAP secured with TLS, annotations must be fetched by a comparably protected mechanism.
The helper can only read the notes, never change them. If it cannot reach the notes, it should act as if it could not reach its rule list either.
§6IANA Registrations
IANA has added three registrations to the list of Sieve extensions. Each names a capability a script lists in its require command, and the contact address is the Sieve discussion list.
mailbox: the mailbox existence test and the:createargument tofileinto.mboxmetadata: tests for mailbox metadata existence and value retrieval.servermetadata: tests for server metadata existence and value retrieval.
The three new abilities were written in an official list so everyone uses the same names for them.
- mailboxmailboxexists, :create — Existence test and mailbox creation on fileinto.
- mboxmetadatametadata, metadataexists — Mailbox annotation tests.
- servermetadataservermetadata, servermetadataexists — Server annotation tests.