7Network Working Group A. Melnikov
8Request for Comments: 5490 Isode Limited
9Category: Standards Track March 2009
12 The Sieve Mail-Filtering Language --
13Extensions for Checking Mailbox Status and Accessing Mailbox Metadata
17 This document specifies an Internet standards track protocol for the
18 Internet community, and requests discussion and suggestions for
19 improvements. Please refer to the current edition of the "Internet
20 Official Protocol Standards" (STD 1) for the standardization state
21 and status of this protocol. Distribution of this memo is unlimited.
25 Copyright (c) 2009 IETF Trust and the persons identified as the
26 document authors. All rights reserved.
28 This document is subject to BCP 78 and the IETF Trust's Legal
29 Provisions Relating to IETF Documents in effect on the date of
30 publication of this document (http://trustee.ietf.org/license-info).
31 Please review these documents carefully, as they describe your rights
32 and restrictions with respect to this document.
34 This document may contain material from IETF Documents or IETF
35 Contributions published or made publicly available before November
36 10, 2008. The person(s) controlling the copyright in some of this
37 material may not have granted the IETF Trust the right to allow
38 modifications of such material outside the IETF Standards Process.
39 Without obtaining an adequate license from the person(s) controlling
40 the copyright in such materials, this document may not be modified
41 outside the IETF Standards Process, and derivative works of it may
42 not be created outside the IETF Standards Process, except to format
43 it for publication as an RFC or to translate it into languages other
48 This memo defines an extension to the Sieve mail filtering language
49 (RFC 5228) for accessing mailbox and server annotations, checking for
50 mailbox existence, and controlling mailbox creation on "fileinto"
58Melnikov Standards Track [Page 1]
60RFC 5490 Sieve METADATA March 2009
65 1. Introduction ....................................................2
66 2. Conventions Used in This Document ...............................2
67 3. "mailbox" and "mboxmetadata" Extensions .........................2
68 3.1. Test "mailboxexists" .......................................2
69 3.2. ":create" Argument to "fileinto" Command ...................3
70 3.3. Test "metadata" ............................................4
71 3.4. Test "metadataexists" ......................................4
72 4. "servermetadata" Extension ......................................5
73 4.1. Test "servermetadata" ......................................5
74 4.2. Test "servermetadataexists" ................................6
75 5. Security Considerations .........................................6
76 6. IANA Considerations .............................................7
77 7. Acknowledgements ................................................7
78 8. References ......................................................8
79 8.1. Normative References .......................................8
80 8.2. Informative References .....................................8
84 This memo defines an extension to the Sieve mail filtering language
85 [SIEVE] for accessing mailbox and server annotations. This allows
86 for customization of the Sieve engine behaviour based on variables
89 This document also defines an extension for checking for mailbox
90 existence and for controlling mailbox creation on "fileinto" action.
922. Conventions Used in This Document
94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
96 document are to be interpreted as described in [KEYWORDS].
98 Conventions for notations are as in [SIEVE] Section 1.1, including
101 This document is written with an assumption that readers are familiar
102 with the data model and terms defined in Section 3 of [METADATA].
1043. "mailbox" and "mboxmetadata" Extensions
1063.1. Test "mailboxexists"
108 Usage: mailboxexists <mailbox-names: string-list>
114Melnikov Standards Track [Page 2]
116RFC 5490 Sieve METADATA March 2009
119 The "mailboxexists" test is true if all mailboxes listed in the
120 "mailbox-names" argument exist in the mailstore, and each allows the
121 user in whose context the Sieve script runs to "deliver" messages
122 into it. When the mailstore is an IMAP server, "delivery" of
123 messages is possible if:
125 a. the READ-WRITE response code is present for the mailbox (see
126 Section 7.1 of [IMAP]), if IMAP Access Control List (ACL)
127 [IMAPACL] is not supported by the server, or
129 b. the user has 'p' or 'i' rights for the mailbox (see Section 5.2
132 Note that a successful "mailboxexists" test for a mailbox doesn't
133 necessarily mean that a "fileinto" action on this mailbox would
134 succeed. For example, the "fileinto" action might put user over
135 quota. The "mailboxexists" only verifies existence of the mailbox
136 and whether the user in whose context the Sieve script runs has
137 permissions to execute "fileinto" on it.
139 The capability string for use with the require command is "mailbox".
141 Example: The following example assumes that the Sieve engine also
142 supports "reject" [REJECT] and "fileinto" [SIEVE]. However, these
143 extensions are not required in order to implement the "mailbox"
146 require ["fileinto", "reject", "mailbox"];
147 if mailboxexists "Partners" {
150 reject "This message was not accepted by the Mailstore";
1533.2. ":create" Argument to "fileinto" Command
155 Usage: fileinto [:create] <mailbox: string>
157 If the optional ":create" argument is specified with "fileinto", it
158 instructs the Sieve interpreter to create the specified mailbox, if
159 needed, before attempting to deliver the message into the specified
160 mailbox. If the mailbox already exists, this argument is ignored.
161 Failure to create the specified mailbox is considered to be an error.
163 The capability string for use with the ":create" parameter is
170Melnikov Standards Track [Page 3]
172RFC 5490 Sieve METADATA March 2009
177 Usage: metadata [MATCH-TYPE] [COMPARATOR]
179 <annotation-name: string> <key-list: string-list>
181 This test retrieves the value of the mailbox annotation "annotation-
182 name" for the mailbox "mailbox" [METADATA]. The retrieved value is
183 compared to the "key-list". The test returns true if the annotation
184 exists and its value matches any of the keys.
186 The default match type is ":is" [SIEVE]. The default comparator is
187 "i;ascii-casemap" [SIEVE].
189 The capability string for use with the require command is
192 Annotations MUST be accessed with the permissions of the user in
193 whose context the Sieve script runs, and annotations starting with
194 the "/private" prefix MUST be those of the user in whose context the
197 Example: The following example assumes that the Sieve engine also
198 supports the "vacation" [VACATION] extension. However, this
199 extension is not required in order to implement the "mboxmetadata"
202 require ["mboxmetadata", "vacation"];
204 if metadata :is "INBOX"
205 "/private/vendor/vendor.isode/auto-replies" "on" {
208 I'm away on holidays till March 2009.
2133.4. Test "metadataexists"
215 Usage: metadataexists <mailbox: string> <annotation-names: string-
218 The "metadataexists" test is true if all of the annotations listed in
219 the "annotation-names" argument exist (i.e., have non-NIL values) for
220 the specified mailbox.
226Melnikov Standards Track [Page 4]
228RFC 5490 Sieve METADATA March 2009
231 The capability string for use with the require command is
2344. "servermetadata" Extension
2364.1. Test "servermetadata"
238 Usage: servermetadata [MATCH-TYPE] [COMPARATOR]
239 <annotation-name: string> <key-list: string-list>
241 This test retrieves the value of the server annotation "annotation-
242 name" [METADATA]. The retrieved value is compared to the "key-list".
243 The test returns true if the annotation exists and its value matches
246 The default match type is ":is". The default comparator is "i;ascii-
249 The capability string for use with the require command is
252 Annotations MUST be accessed with the permissions of the user in
253 whose context the Sieve script runs, and annotations starting with
254 the "/private" prefix MUST be those of the user in whose context the
257 Example: The following example assumes that the Sieve engine also
258 supports "variables" [VARIABLES], "enotify" [NOTIFY], and "envelope"
259 [SIEVE] extensions. However, these extensions are not required in
260 order to implement the "servermetadata" extension.
262 require ["enotify", "servermetadata", "variables", "envelope"];
264 if servermetadata :matches
265 "/private/vendor/vendor.isode/notification-uri" "*" {
266 set "notif_uri" "${0}";
269 if not string :is "${notif_uri}" "none" {
270 # :matches is used to get the MAIL FROM address
271 if envelope :all :matches "from" "*" {
272 set "env_from" " [really: ${1}]";
275 # :matches is used to get the value of the Subject header
276 if header :matches "Subject" "*" {
277 set "subject" "${1}";
282Melnikov Standards Track [Page 5]
284RFC 5490 Sieve METADATA March 2009
287 # :matches is used to get the address from the From header
288 if address :matches :all "from" "*" {
289 set "from_addr" "${1}";
292 notify :message "${from_addr}${env_from}: ${subject}"
2964.2. Test "servermetadataexists"
298 Usage: servermetadataexists
299 <annotation-names: string-list>
301 The "servermetadataexists" test is true if all of the server
302 annotations listed in the "annotation-names" argument exist (i.e.,
303 have non-NIL values).
305 The capability string for use with the require command is
3085. Security Considerations
310 Extensions defined in this document deliberately don't provide a way
311 to modify annotations.
313 A failure to retrieve data due to the server storing the annotations
314 being down or otherwise inaccessible may alter the result of Sieve
315 processing. So implementations SHOULD treat a temporary failure to
316 retrieve annotations in the same manner as a temporary failure to
317 retrieve a Sieve script. For example, if the Sieve script is stored
318 in the Lightweight Directory Access Protocol (LDAP) and the script
319 can't be retrieved when a message is processed, then the agent
320 performing Sieve processing can, for example, assume that the script
321 doesn't exist or delay message delivery until the script can be
322 retrieved successfully. Annotations should be treated as if they are
323 a part of the script itself, so a temporary failure to retrieve them
324 should be handled in the same way as a temporary failure to retrieve
325 the Sieve script itself.
327 Protocols/APIs used to retrieve annotations MUST provide at least the
328 same level of confidentiality as protocols/APIs used to retrieve
329 Sieve scripts. For example, if Sieve scripts are retrieved using
330 LDAP secured with Transport Layer Security (TLS) encryption, then the
331 protocol used to retrieve annotations must use a comparable mechanism
332 for providing connection confidentiality. In particular, the
333 protocol used to retrieve annotations must not be lacking encryption.
338Melnikov Standards Track [Page 6]
340RFC 5490 Sieve METADATA March 2009
3436. IANA Considerations
345 IANA has added the following registrations to the list of Sieve
349 Subject: Registration of new Sieve extension
350 Capability name: mailbox
351 Description: adds test for checking for mailbox existence and a new
352 optional argument to fileinto for creating a mailbox
353 before attempting mail delivery.
356 The Sieve discussion list <ietf-mta-filters@imc.org>
358 Capability name: mboxmetadata
359 Description: adds tests for checking for mailbox metadata item
360 existence and for retrieving of a mailbox metadata
364 The Sieve discussion list <ietf-mta-filters@imc.org>
366 Capability name: servermetadata
367 Description: adds tests for checking for server metadata item
368 existence and for retrieving of a server metadata
372 The Sieve discussion list <ietf-mta-filters@imc.org>
376 Thanks to Cyrus Daboo for initial motivation for this document.
378 Thanks to Barry Leiba, Randall Gellens, and Aaron Stone for helpful
379 comments on this document.
381 The author also thanks the Open Mobile Alliance's Mobile Email
382 working group for providing a set of requirements for mobile devices,
383 guiding some of the extensions in this document.
394Melnikov Standards Track [Page 7]
396RFC 5490 Sieve METADATA March 2009
4018.1. Normative References
403 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
404 Specifications: ABNF", STD 68, RFC 5234, January 2008.
406 [IMAP] Crispin, M., "Internet Message Access Protocol - Version
407 4rev1", RFC 3501, March 2003.
409 [IMAPACL] Melnikov, A., "IMAP4 Access Control List (ACL)
410 Extension", RFC 4314, December 2005.
412 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
413 Requirement Levels", BCP 14, RFC 2119, March 1997.
415 [METADATA] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
418 [SIEVE] Guenther, P. and T. Showalter, "Sieve: An Email
419 Filtering Language", RFC 5228, January 2008.
4218.2. Informative References
423 [NOTIFY] Melnikov, A., Leiba, B., Segmuller, W., and T. Martin,
424 "Sieve Email Filtering: Extension for Notifications",
425 RFC 5435, January 2009.
427 [REJECT] Stone, A., "Sieve Email Filtering: Reject and Extended
428 Reject Extensions", RFC 5429, March 2009.
430 [VACATION] Showalter, T. and N. Freed, "Sieve Email Filtering:
431 Vacation Extension", RFC 5230, January 2008.
433 [VARIABLES] Homme, K., "Sieve Email Filtering: Variables Extension",
434 RFC 5229, January 2008.
440 5 Castle Business Village
442 Hampton, Middlesex TW12 2BX
445 EMail: Alexey.Melnikov@isode.com
450Melnikov Standards Track [Page 8]